← All Articles

UCP Totals Now Accept Signed Amounts

Why This Matters

UCP's checkout specification has always supported negative amounts — discounts, account credits, and promotional adjustments that reduce the total. The official examples show this clearly. But until now, there was a subtle schema bug: the total field referenced amount.json (unsigned) instead of signed_amount.json.

This mismatch meant that while the spec described negative totals, the schema would reject them. Implementers following the JSON Schema strictly would find their discount scenarios failing validation.

What Changed Technically

The fix is elegant in its simplicity: a single-line change swapping the schema reference from amount.json to signed_amount.json.

// Before
"total": { "$ref": "amount.json" }

// After
"total": { "$ref": "signed_amount.json" }

Commerce Scenarios Unlocked

This seemingly small change unlocks important commerce patterns that were technically unsupported:

• Account Credits: Customer has store credit exceeding the order value — total goes negative, merchant owes the customer.
• Promotional Overages: Aggressive first-order discounts that exceed item cost, subsidizing customer acquisition.
• Refund Previews: Showing negative totals when previewing refund amounts before confirmation.
• Gift Card Balances: When a gift card value exceeds checkout total, the difference is negative.

Implications for Implementers

If you're implementing a UCP merchant or agent:

1. Update your schema: Pull the latest UCP schemas to enable signed total validation.
2. Review total handling: Ensure your payment processing can handle negative totals gracefully — these typically indicate credits rather than charges.
3. Test edge cases: Validate that your checkout flows handle the zero-crossing correctly (positive → negative → positive).