← Articles Breaking Change

UCP Breaking Change: Currency Now Required on Order Schema

April 2, 2026 · deinck6 · PR #283

The Change

Today's merge of PR #283 makes the currency field required on the Order schema. This completes a migration that started with PR #210, which added currency as an optional field with the explicit intention of making it required in the next breaking change window.

Migration Required: All Order payloads MUST now include a currency field. Existing implementations relying on implicit currency context from Checkout will fail validation.

Author Background

deinck6 has been actively contributing to UCP's schema evolution, focusing on capability independence and data completeness. This PR reflects the team's systematic approach to breaking changes — introducing features as optional, then promoting to required once adoption patterns are understood.

Why This Matters

The change addresses a fundamental design principle in UCP: capabilities should function independently. Previously, Order totals relied on currency context established during Checkout — a coupling that created several problems:

Order portability — Orders couldn't be understood without their originating Checkout session
Multi-currency scenarios — Cross-border transactions and currency conversions were ambiguous
Data integrity — Historical orders lacked self-contained monetary context
Agent interoperability — AI agents processing orders needed additional context lookups

Technical Details

The schema change is straightforward but has broad impact:

// Order schema before
{
  "totals": { ... },
  "currency": { "type": "string" }  // optional
}

// Order schema after
{
  "totals": { ... },
  "currency": { "type": "string" }  // required
}

The required array in the JSON schema now includes currency, meaning validation will reject Order payloads missing this field.

Context: Yesterday's Order Capability Overhaul

This change lands one day after PR #254, which restructured the Order capability significantly:

1:N Order:Checkout relationship — Orders can now reference multiple checkout sessions via a checkouts array (enabling order edits and exchanges)
Signed quantities/amounts — Adjustments support negative values for returns
Adjustment totals consistency — Renamed amount to totals for pattern alignment

Together, these changes represent UCP's most significant Order capability evolution since launch.

Implications for AI Agents

This change simplifies agentic commerce by making Orders self-describing:

No context lookups — Agents can understand order values without retrieving Checkout data
Cross-platform consistency — Orders from different merchants share the same currency semantics
Better error messages — Currency mismatches fail fast at validation, not runtime

Migration Path

Audit existing Order generation — Ensure currency is included in all payloads
Update validation schemas — Import the latest UCP schema definitions
Test historical order handling — Older orders may need currency backfill
Review currency source — Determine where currency originates (Checkout, merchant config, etc.)

Next Steps

UCP is in active release preparation (see ci: prepare for release). Implementers should expect these breaking changes to land in the next versioned release — plan migrations accordingly.

This change, combined with yesterday's Order restructuring and last week's signed_amount totals update, represents a coordinated hardening of UCP's commerce primitives ahead of broader enterprise adoption.