Skip to main content

​
Guards Reference

QWED-UCP includes 6 verification guards that validate different aspects of UCP checkout data.

​
1. Money Guard

Verifies the total formula is mathematically correct. 
Total = Subtotal - Discount + Tax + Shipping + Fee

​
Usage

driver = MoneyGuard()
result = driver.verify_cart_totals(
    line_items=[{"price": 35.00, "quantity": 2}, {"price": 15.00, "quantity": 1}],
    taxes=8.25,
    discounts=10.00,
    claimed_total=98.25
)
# Returns: {"verified": True}

​
Tolerance

Uses Decimal precision with 1 cent ($0.01) tolerance for floating-point errors.

​
2. State Guard

Verifies valid checkout state machine transitions.

​
Valid States

incomplete → ready_for_complete → completed
                              ↓
                            failed
                              ↓
                           cancelled

​
Usage

from qwed_ucp.guards.state_guard import StateGuard

guard = StateGuard()
# Check if we can SHIP given the current state is PAID
result = guard.verify_transition(
    current_state="paid",
    action="ship"
)
# Returns: {"verified": True}

​
Rules

  • incomplete: Can be empty
  • ready_for_complete: Must have line items
  • completed: Must have order object
  • Cannot transition backwards

​
3. Schema Guard

Validates UCP JSON schema compliance.

​
Usage

from qwed_ucp.guards import SchemaGuard

guard = SchemaGuard()
result = guard.verify(checkout_data)

​
Validates

  • Required fields present
  • Correct types (string, number, array)
  • Valid enum values (status, total types)

​
4. Line Items Guard

Verifies price × quantity = line total for each item.

​
Usage

from qwed_ucp.guards import LineItemsGuard

guard = LineItemsGuard()
result = guard.verify({
    "line_items": [
        {"id": "roses", "quantity": 2, "item": {"price": 35.00}},
        {"id": "pot", "quantity": 1, "item": {"price": 15.00}}
    ],
    "totals": [{"type": "subtotal", "amount": 85.00}]  # 2×35 + 1×15 = 85 ✓
})

​
Checks

  • Each item: price × quantity = line_total
  • Sum of line items = subtotal
  • Quantities must be positive integers
  • Prices must be non-negative

​
5. Discount Guard

Verifies percentage and fixed discount calculations.

​
Usage - Percentage Discount

from qwed_ucp.guards import DiscountGuard
from decimal import Decimal

guard = DiscountGuard()
result = guard.verify_percentage_discount(
    subtotal=Decimal("100.00"),
    discount_amount=Decimal("10.00"),
    percentage=Decimal("10")  # 10% of 100 = 10 ✓
)

​
Usage - Fixed Discount

result = guard.verify_fixed_discount(
    subtotal=Decimal("50.00"),
    discount_amount=Decimal("5.00")  # Fixed $5 off ✓
)

​
Rules

  • Percentage: Must be 0-100%
  • Fixed: Cannot exceed subtotal
  • Discount must be non-negative

​
6. Currency Guard

Validates ISO 4217 currency codes and format.

​
Usage

from qwed_ucp.guards import CurrencyGuard

guard = CurrencyGuard()
result = guard.verify({"currency": "USD"})

​
Validates

  • 3-letter ISO 4217 codes (USD, EUR, GBP, JPY, etc.)
  • Zero-decimal currencies (JPY, KRW) have no decimals
  • Currency conversion accuracy

​
Zero-Decimal Currencies

# Valid - no decimals
{"currency": "JPY", "totals": [{"type": "total", "amount": 1000}]}

# Invalid - JPY shouldn't have decimals
{"currency": "JPY", "totals": [{"type": "total", "amount": 1000.50}]}

​
Running All Guards

Use UCPVerifier to run all guards at once: 
from qwed_ucp import UCPVerifier

verifier = UCPVerifier()
result = verifier.verify_checkout(checkout_data)

print(f"Verified: {result.verified}")
print(f"Guards passed: {len([g for g in result.guards if g.verified])}")