← Articles Breaking Change

UCP Breaking Change: Totals Now Use signed_amount

The Change

Today's merge of PR #299 updates UCP's total field to use signed_amount.json instead of the previous unsigned schema. This is a breaking change affecting all checkout and order flows.

Author Background

Ryan C has been a consistent UCP contributor, recently shepherding the release preparation (ci: prepare for release) and overseeing CI infrastructure improvements. His focus on schema correctness reflects the protocol's maturation toward production stability.

Why This Matters

The shift to signed amounts addresses a fundamental limitation in UCP's commerce model. Real-world checkout flows frequently produce negative totals:

• Store credits exceeding purchase amount
• Promotional balances covering entire orders
• Refund adjustments creating credit states
• Gift card overages leaving balances

Previously, these scenarios were technically unsupported despite being documented in examples — a classic "works in docs, fails in prod" gap. AI agents attempting to apply large discounts would encounter validation errors or undefined behavior.

Technical Details

The change updates the JSON schema reference:

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

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

The signed_amount.json schema permits negative values while maintaining the same structure (value + currency). Implementations should:

• Update validation logic to accept negative totals
• Handle display formatting for negative amounts (parentheses, minus signs)
• Consider business logic implications (e.g., "pay nothing" vs "receive credit")

Implications for AI Agents

This change directly benefits agentic commerce scenarios:

• Coupon stacking — Agents can apply multiple discounts without hitting schema errors
• Gift card redemption — Full balance application now works correctly
• Refund flows — Agents can understand and communicate credit states

Next Steps

The UCP team is preparing for release (see 02120f5), with this fix included. Implementations should:

1. Review total handling code for unsigned assumptions
2. Update UI components that display totals
3. Add test cases for negative total scenarios
4. Verify business logic handles "zero cost" and "credit due" states

This fix continues UCP's pattern of hardening schema definitions ahead of enterprise adoption — where edge cases become common cases at scale.