← Articles

UCP Order Currency Required: Multi-Currency Commerce Gets Explicit

The Change

A simple but significant schema change: the currency field in UCP Order objects moves from optional to required. This is a breaking change that affects all UCP implementations.

// Before (optional)
{
  "order": {
    "total": "99.99"
    // currency could be inferred, missing, or ambiguous
  }
}

// After (required)
{
  "order": {
    "total": "99.99",
    "currency": "USD"  // Always present
  }
}

Why It Matters

When an AI agent completes a purchase on behalf of a user, currency ambiguity is not acceptable. Consider these scenarios:

• Cross-border shopping: A US user buying from a UK merchant needs to know whether "99.99" means USD or GBP — a 20%+ difference
• Currency comparison: Agents comparing prices across merchants must normalize to a common currency, which requires knowing the source currency
• Budget constraints: Users set spending limits in their local currency; agents need explicit currency to enforce these correctly
• Audit trails: Enterprise compliance requires unambiguous transaction records

Technical Details

The change is minimal in schema terms:

// In order.schema.json
{
  "properties": {
    "currency": {
      "type": "string",
      "description": "ISO 4217 currency code",
      "pattern": "^[A-Z]{3}$"
    }
  },
  "required": ["currency", ...]  // Added to required array
}

Implementations must now:

1. Always include currency when creating Order objects
2. Validate that incoming Orders have the field present
3. Update API documentation to reflect the required status

Migration Path

For existing UCP implementations:

• Merchants: Ensure order responses always include the currency field — most already do, this formalizes the requirement
• Platforms: Validate incoming orders have currency present; return 400 errors for missing fields
• Agents: No action needed if already handling currency correctly; update any currency inference logic to fail explicitly on missing data

Next Steps

The PR is currently open and under review. Given this is a breaking change, expect discussion around:

• Version bump requirements (likely a minor version since it's additive validation)
• Deprecation timeline for non-compliant implementations
• Migration guidance in release notes

This change aligns with UCP's broader direction of making agent transactions explicit and unambiguous. Combined with the recent identity linking redesign and totals contract formalization, UCP is systematically closing gaps that could cause agent commerce failures.