← Articles Breaking Change

UCP Order Capability Restructuring: Multi-Checkout Support and Signed Quantities

Overview

PR #254 represents the most significant restructuring of UCP's Order capability since launch. The changes address fundamental modeling limitations that prevented proper handling of order edits, exchanges, and returns — scenarios that are increasingly common in agentic commerce.

Author Background

Lee Richmond (richmolj) has been instrumental in shaping UCP's capability model. His contributions focus on schema flexibility and real-world commerce scenarios — this PR reflects extensive analysis of edge cases encountered in production deployments.

Breaking Changes Summary

Change	Before	After
Checkout reference	checkout_id (string)	checkouts (array of objects)
Adjustment amounts	amount (single value)	totals (array of Total objects)
Line item quantities	minimum: 1	Signed (can be negative)
Amount values	minimum: 0	Signed (can be negative)

Key Changes Explained

1. Order:Checkout is Now 1:N

The most significant architectural change: Orders can now reference multiple Checkout sessions. This enables:

• Order edits — Customer changes quantity post-purchase, creating a new checkout session
• Exchanges — Return one item, purchase another in a linked transaction
• Subscriptions — Recurring orders can track renewal checkouts

// Before: Single checkout reference
{
  "checkout_id": "chk_abc123"
}

// After: Array with timestamps
{
  "checkouts": [
    { "id": "chk_abc123", "created_at": "2026-04-01T10:00:00Z" },
    { "id": "chk_xyz789", "created_at": "2026-04-01T14:30:00Z" }
  ]
}

2. Signed Quantities for Returns

Adjustment line item quantities no longer enforce minimum: 1. Negative quantities represent returned items:

// Adjustment: Customer returned 2 items, kept 3
{
  "line_items": [
    { "sku": "WIDGET-001", "quantity": -2 },
    { "sku": "GADGET-002", "quantity": 3 }
  ]
}

3. Adjustment Totals Alignment

The amount field on Adjustments has been renamed to totals and restructured to match the pattern used by Order and OrderLineItem:

// Before: Single amount
{
  "amount": { "value": "10.00", "currency": "USD" }
}

// After: Array of totals
{
  "totals": [
    { "type": "subtotal", "amount": { "value": "-10.00", "currency": "USD" } },
    { "type": "tax", "amount": { "value": "-0.90", "currency": "USD" } }
  ]
}

4. Documentation Clarifications

The PR also softens previously rigid language:

• "Append-only" on adjustments → now acknowledges adjustment modifications
• "Immutable" on line items → recognizes edit scenarios
• "Derived from events" quantity language → removed to allow direct specification

Implications for AI Agents

These changes significantly improve agent capabilities:

• Order modification flows — Agents can now properly model "change my order" requests
• Return processing — Negative quantities provide clear return semantics
• Transaction history — Multiple checkouts enable complete order lifecycle visibility
• Refund calculations — Signed amounts enable accurate partial refund computation

Migration Guide

1. Update checkout references — Replace checkout_id with checkouts array
2. Adjust validation rules — Remove minimum constraints on quantities and amounts
3. Rename adjustment fields — Change amount to totals with array structure
4. Handle negative values — Update display logic for quantities and amounts
5. Test exchange flows — Verify multi-checkout scenarios work correctly

Context: Part of a Larger Wave

This PR lands alongside other significant UCP changes:

• signed_amount for totals (PR #299, April 1)
• Required currency on Order (PR #283, April 2)
• ec.totals.change for embedded checkout (March 27)

Together, these represent UCP's most significant breaking change window — positioning the protocol for enterprise adoption where complex order lifecycle management is the norm, not the exception.