At a brick checkpoint, a keeper raises a stop hand while a buyer and luminous agent wait behind the lowered barrier.

At the Policy Forum, two townspeople argue over blank posted notices while a luminous agent reads beside them.

In the Trust Quarter, a key-cutter stamps a document while passing a newly cut key to a luminous agent.

At the Map Room, a cartographer and luminous agent trace a route across a chart and the district map behind it.

At the Money Changer, a buyer adds a coin pouch and card to one payment tray while a cyan agent contributes a third token; the merchant holds one parcel.

At the Weigh House, a keeper pours grain onto one balance pan while a buyer and luminous agent watch it settle against two weights.

At the Cart Exchange, a clerk hands a glowing QR card to a buyer while a luminous agent files another slip behind them.

An open-air screening in the bazaar: watchers from many centuries and three machines sit facing a taut hanging cloth, the shopping-bag mascot among them.

The Manifest

88 improvements. Itemized.

April → August 2026 · 142 commits · 263 files · 40 contributors · 24 features, 14 breaking

Complete fixture copy deck

`cold-open.cue`

This way in

`walk.gate.explainer.v2`

Name the blocking work, hand off the task, define what happens next.

`walk.forum.explainer.v4`

State the default, target exceptions, make the governing terms unambiguous.

`walk.trust.explainer.v3`

Reuse a trusted Buyer identity without another sign-in; every request stays scoped and signed.

`walk.maproom.explainer.v2`

Virtual when you want it, physical when you need it — stores became searchable.

`walk.money.explainer.v3`

Gift card, points, and card on one checkout; terms too — deposit now, pay later.

`walk.weighhouse.explainer.v2`

Transact in any unit and precision — and when reality differs, it settles provably.

`walk.cartroom.explainer.v2`

Capture purchase intent in a durable URL — QR it, text it, email it; it opens filled.

`walk.index.explainer.v1`

Every improvement in the release, itemized, each linked to the receipt behind it.

`cold-open.title.1`

The Manifest

`cold-open.title.2`

A Decade, Itemized

`cold-open.title.4`

The Ledger

`cold-open.kicker`

April → August 2026 · 142 commits · 263 files · 40 contributors · 24 features, 14 breaking

`cold-open.headline.v3a`

88 improvements. Itemized.

`cold-open.headline.v3b`

Count what shipped since April.

`cold-open.whisper.v3`

A decade, itemized.

`stop-b.skim.kicker`

THE GATE · ACTIONS

`stop-b.skim.headline.v3a`

Name the next steps,
eliminate dead ends.

`stop-b.cruise.common.label`

ACTIONS: PAUSE → TASK → CONTINUE

`stop-b.cruise.common.claim`

An extension names the work blocking a flow, hands the Platform a structured task, and defines what happens next.

`stop-b.cruise.common.shape`

actions[<type>] → [{ id, config? }]

`stop-b.cruise.common.intro`

Each entry names one occurrence of outstanding work.

`stop-b.cruise.common.surface`

Some Actions need no Buyer-facing surface. A concrete Action type can ask the Platform to present one.

`stop-b.cruise.common.anatomy.type`

what kind of work

`stop-b.cruise.common.anatomy.id`

unique Action identifier

`stop-b.cruise.common.anatomy.config`

instructions owned by its extension

`stop-b.cruise.common.body`

The extension owns processing and fallback; the parent capability owns the lifecycle.

`stop-b.cruise.common.receipt`

#582 · MERGED · 2026-07-22

`stop-b.dive.artifact.label`

PAYMENT AUTHENTICATION · 3-D SECURE (3DS)

`stop-b.dive.artifact.title`

Navigate the payment challenge. Then confirm the outcome.

`stop-b.dive.artifact.body`

Payment Authentication gives the Platform a Buyer-facing 3DS surface. When it closes, Get Checkout returns the Business's authoritative payment result.

`stop-b.dive.artifact.key`

dev.ucp.common.payment.three_ds_challenge

`stop-b.dive.artifact.receipt`

#458 · MERGED · 2026-08-04

`stop-b.dive.artifact.stage.1`

BUSINESS NAMES THE CHALLENGE

`stop-b.dive.artifact.stage.2`

3DS SURFACE → FINISH

`stop-b.dive.artifact.stage.3`

BUSINESS RETURNS THE OUTCOME

`stop-b.dive.artifact.takeaway.1`

Checkout cannot complete yet; the response names the 3DS work.

`stop-b.dive.artifact.takeaway.2`

The Platform renders the issuer challenge. Finishing that surface does not prove payment succeeded.

`stop-b.dive.artifact.takeaway.3`

Get Checkout returns the Business's authoritative result.

`stop-b.dive.control`

OPEN 3DS

`stop-b.dive.reconcile-control`

GET CHECKOUT

`stop-c.skim.kicker`

POLICY FORUM · POLICIES[]

`stop-c.skim.headline.v4a`

Structured policies,
down to the item.

`stop-c.cruise.common.label`

POLICIES · OPEN CONTAINER

`stop-c.cruise.common.claim`

Every purchase can carry the terms that govern it — from purchase-wide defaults to line-level resolution.

`stop-c.cruise.common.shape`

policies[] → [{ type, description, applies_to? }]

`stop-c.cruise.common.intro`

Each entry carries one typed policy with a human-readable description.

`stop-c.cruise.common.boundary`

The container is universal. Understanding every custom policy type is not.

`stop-c.cruise.common.anatomy.type`

open policy identifier

`stop-c.cruise.common.anatomy.description`

terms any Platform can present

`stop-c.cruise.common.anatomy.applies-to`

exact response targets; omitted means the whole response

`stop-c.cruise.common.body`

For same-type overlaps, the more specific target governs. It replaces the broader policy; Platforms never merge their bodies.

`stop-c.cruise.common.receipt`

#572 · MERGED · 2026-07-23

`stop-c.dive.artifact.label`

RETURN POLICY · DEFAULT + ITEM OVERRIDE

`stop-c.dive.artifact.title`

Thirty-day returns — except for the engraved item.

`stop-c.dive.artifact.body`

One Checkout response carries its line items and the policies that govern them.

`stop-c.dive.artifact.key`

dev.ucp.shopping.policy.return

`stop-c.dive.artifact.explanation`

applies_to uses JSONPath to point into the response. policies[0] omits it, so its 30-day terms cover the whole Checkout response. policies[1] targets $.line_items[1] — the Engraved Luggage Tag. Because both policies have the same type and the second has a narrower target, it replaces the default there: the Weekender Pack keeps 30-day returns; the engraved tag is final sale. The policies do not merge.

`stop-d.skim.kicker`

MONEY CHANGER · PAYMENT PRIMITIVES

`stop-d.skim.headline.v3a`

Split the payment.
Choose the terms.

`stop-d.common.label`

PAYMENT PRIMITIVES · WHAT PAYS / WHEN DUE

`stop-d.common.axis-pays.label`

WHAT PAYS?

`stop-d.common.axis-pays.name`

SPLIT PAYMENTS

`stop-d.common.axis-pays.body`

Defines which instruments can fund the checkout and what each one contributed.

`stop-d.common.axis-due.label`

WHEN IS IT DUE?

`stop-d.common.axis-due.name`

PAYMENT TERMS

`stop-d.common.axis-due.body`

Defines how much is due, and when, across one or more payment schedules.

`stop-d.pays.label`

WHAT PAYS? · SPLIT PAYMENTS

`stop-d.pays.title`

Allowed combination → ordered instruments → actual contributions

`stop-d.pays.receipt`

#409 · VIEW PR ↗

`stop-d.pays.stage-rules.label`

BUSINESS ALLOWS

`stop-d.pays.stage-rules.path`

allowed_combinations

`stop-d.pays.stage-submit.label`

BUYER ORDERS

`stop-d.pays.stage-submit.path`

payment.instruments[]

`stop-d.pays.stage-result.label`

BUSINESS REPORTS

`stop-d.pays.stage-result.path`

payment.instruments[].amount

`stop-d.due.label`

WHEN DUE? · PAYMENT TERMS

`stop-d.due.title`

Offered terms → Buyer selection → authoritative Checkout → accepted term

`stop-d.due.receipt`

#602 · VIEW PR ↗

`stop-d.due.stage-offer.label`

BUSINESS OFFERS

`stop-d.due.stage-offer.path`

payment.terms[]

`stop-d.due.stage-select.label`

BUYER SELECTS

`stop-d.due.stage-select.path`

payment.selected_term_id

`stop-d.due.stage-recompute.label`

BUSINESS RETURNS

`stop-d.due.stage-recompute.path`

totals[] · messages[] · payment_handlers

`stop-d.due.stage-order.label`

ORDER REMEMBERS

`stop-d.due.stage-order.path`

payment.accepted_term

`stop-e.skim.kicker`

TRUST QUARTER · IDENTITY

`stop-e.skim.headline.v3a`

Know the agent.
Recognize the Buyer.

`stop-e.cruise.card1.label`

BUYER AUTHORIZATION

`stop-e.cruise.card1.title`

Choose a sign-in both support

`stop-e.cruise.card1.body`

The merchant advertises its OAuth options and commerce permissions. The agent discovers the overlap and selects a compatible path for the Buyer—either the merchant’s own sign-in or a supported third-party provider. The resulting token is limited to the selected permission.

`stop-e.cruise.card2.label`

AGENT AUTHENTICATION

`stop-e.cruise.card2.title`

One signature binds the agent to the transaction

`stop-e.cruise.card2.body`

The agent’s UCP profile doubles as a valid JWK Set. Web Bot Auth interoperability lets the merchant use one RFC 9421 signature to authenticate the agent and verify the integrity of the transaction request.

`stop-e.dive.artifact.label`

IDENTITY · OAUTH + WEB BOT AUTH

`stop-e.dive.artifact.key`

dev.ucp.common.identity_linking · RFC 9421

`stop-e.dive.artifact.title`

Find a supported sign-in. Verify the agent.

`stop-e.dive.artifact.body`

Merchants publish the sign-in providers and commerce permissions they support. Agents discover a compatible path for the Buyer.

`stop-e.dive.profile.label`

WHAT THIS MERCHANT SUPPORTS

`stop-e.dive.profile.explanation`

The merchant advertises its own OAuth service, supported third-party sign-in providers, and available commerce permissions. The agent discovers the options and selects a compatible path for the Buyer.

`stop-e.dive.request.label`

END-TO-END REQUEST

`stop-e.dive.request.title`

Buyer authorized. Agent authenticated.

`stop-e.dive.request.buyer`

BUYER AUTHORIZATION

`stop-e.dive.request.agent`

AGENT AUTHENTICATION

`stop-e.dive.request.payoff`

One request carries both proofs: the OAuth token carries the Buyer’s granted permission, while the RFC 9421 signature authenticates the agent and covers the transaction request.

`stop-f.skim.kicker`

THE CART EXCHANGE · PERMALINKS

`stop-f.skim.headline.v3a`

Cart to URL.
URL to cart.

`stop-f.rail.permalink.label`

BROWSER-ADDRESSABLE SHOPPING INTENT

`stop-f.rail.permalink.claim`

Compress the entire shopping intent — items, quantities, discounts, and more — into a URL or QR code.

`stop-f.rail.permalink.travels.label`

TRAVELS THROUGH

`stop-f.rail.permalink.travels.channels`

EMAIL · SMS · SOCIAL · ADS · LANDING PAGES · PRINT · PACKAGING · QR

`stop-f.rail.permalink.shape`

{endpoint}/{items}?{field_paths}

`stop-f.rail.permalink.economy`

One control parameter: continue_to. Zero shopping-state fields of its own.

`stop-f.rail.permalink.anatomy.endpoint`

the absolute HTTPS browser endpoint declared by the Business

`stop-f.rail.permalink.anatomy.items`

purchasable item IDs paired with positive integer quantities

`stop-f.rail.permalink.anatomy.field-path`

recognized, applicable inputs in the Business’s active Cart or Checkout schema, including active profiles and extensions

`stop-f.rail.permalink.anatomy.continue-to`

an untrusted same-origin path preference; the Business validates and canonicalizes it, and it is never shopping state

`stop-f.rail.permalink.receipt`

#523 · MERGED · 2026-07-17

`stop-f.artifact.label`

TWO-ITEM PERMALINK · DECLARATIVE CART

`stop-f.artifact.title`

A declarative cart travels anywhere a URL can go.

`stop-f.artifact.body`

Preconfigure any cart. A click or tap becomes a fast path to a purchase flow with shopping state already in place.

`stop-f.artifact.key`

dev.ucp.shopping.permalink

`stop-f.artifact.endpoint.label`

BUSINESS-DECLARED HTTPS ENDPOINT

`stop-f.artifact.url.label`

COMPLETE PERMALINK · ANNOTATED

`stop-f.artifact.url.part.endpoint`

BUSINESS ENDPOINT · WHERE THE URL BEGINS

`stop-f.artifact.url.part.items`

ITEMS + QUANTITIES · TWO COMPACT PAIRS

`stop-f.artifact.url.part.field-path`

SUPPORTED PREFILL INPUTS · DISCOUNT + POSTAL CODE

`stop-f.artifact.url.part.continue-to`

DESTINATION PREFERENCE · continue_to=/checkout

`stop-f.artifact.url.prefill`

Field paths can prefill any supported, permalink-safe Cart or Checkout input, including inputs defined by active profiles and extensions.

`stop-f.artifact.playground.label`

EXPLORE THE PERMALINK PLAYGROUND

`stop-f.artifact.initialized.label`

INITIALIZED CHECKOUT CREATE REQUEST · PARTIAL EXCERPT

`stop-f.artifact.initialized.takeaway`

Two compact item pairs become line items; supported field paths place SAVE10 and postal code 94105 into the create request.

`stop-f.artifact.initialized.disclosure`

`stop-f.artifact.initialized.disclosure-label`

View the full initialized Checkout create request

`stop-f.artifact.opens.label`

WHEN THE LINK OPENS

`stop-f.artifact.opens.business-label`

BUSINESS APPLIES THE INTENT

`stop-f.artifact.opens.business`

In this fixture, the Business validates the inputs and runs Checkout create; the permalink itself does not require a durable resource.

`stop-f.artifact.opens.browser-label`

BUYER LANDS READY

`stop-f.artifact.opens.browser`

The browser follows the Business’s redirect to the validated /checkout destination.

`stop-f.artifact.response.label`

WIRE REDIRECT RECEIPT

`stop-f.artifact.response.disclosure`

`stop-f.artifact.response.disclosure-label`

View the full wire redirect response

`stop-map.skim.kicker`

THE MAP ROOM · LOCATIONS

`stop-map.skim.headline.v2a`

The physical world,
unlocked.

`stop-map.rail.search.label`

SEARCH THE PHYSICAL WORLD

`stop-map.rail.search.claim`

Ask for a product, radius, opening time, and service. Get back matching Locations.

`stop-map.rail.search.step.request`

SEARCH REQUEST

`stop-map.rail.search.step.response`

SEARCH RESPONSE

`stop-map.rail.search.connector.match`

match

`stop-map.rail.search.value.request`

distance + filters

`stop-map.rail.search.value.response`

locations[]

`stop-map.rail.search.anatomy.distance`

how far away?

`stop-map.rail.search.anatomy.item`

is the product there now?

`stop-map.rail.search.anatomy.hours`

is it open when you need it?

`stop-map.rail.search.anatomy.amenities`

what does the place offer?

`stop-map.rail.search.body`

Matching Locations include an ID, name, address, coordinates, hours, timezone, and amenities.

`stop-map.rail.journey.claim`

Find where it's available. Choose where to pick it up.

`stop-map.rail.journey.step.search`

SEARCH RESPONSE

`stop-map.rail.journey.step.request`

CHECKOUT REQUEST

`stop-map.rail.journey.step.response`

CHECKOUT RESPONSE

`stop-map.rail.journey.connector.choose`

choose

`stop-map.rail.journey.connector.revalidate`

revalidate

`stop-map.rail.journey.found`

locations[0].id

`stop-map.rail.journey.chosen`

selected_destination_id

`stop-map.rail.journey.accepted`

destinations[0].id

`stop-map.rail.journey.body`

Checkout carries the chosen Location into pickup. The Business validates it again before accepting.

`stop-map.artifact.label`

RUNNING SHOE PICKUP · LOCATION SEARCH → CHECKOUT

`stop-map.artifact.title`

Find the right product at the right place.

`stop-map.artifact.body`

Search nearby inventory and locations by proximity, amenities, hours, and more.

`stop-map.artifact.key`

dev.ucp.common.location.search

`stop-map.artifact.stage.1`

FIND LOCATIONS

`stop-map.artifact.stage.2`

CHOOSE A LOCATION FOR PICKUP

`stop-map.artifact.takeaway.request`

The request asks for the exact shoe to be available within 8 km, at a place that offers pickup and is open at 6 PM Pacific time (PDT, UTC−07:00).

`stop-map.artifact.takeaway.response`

Market Street Running matches all four requirements.

`stop-map.artifact.takeaway.checkout`

Pass the found Location to Checkout for pickup.

`stop-map.artifact.transition.match`

MATCH LOCATIONS

`stop-map.artifact.transition.1`

CHOOSE THIS LOCATION

`stop-map.search.request-label`

LOCATION SEARCH · REQUEST

`stop-map.result.wire-label`

LOCATION SEARCH · RESPONSE · locations[0]

`stop-map.handoff.request-label`

UPDATE CHECKOUT · REQUEST · fulfillment.methods[0]

`stop-map.handoff.response-label`

UPDATE CHECKOUT · RESPONSE · fulfillment.methods[0]

`stop-weigh.skim.kicker`

THE WEIGH HOUSE · UNITS & QUANTITIES

`stop-weigh.skim.headline.v2a`

Sell in any unit.
Settle to the penny.

`stop-weigh.cruise.receipt`

#653 · MERGED · BREAKING · 2026-08-12

`stop-weigh.cruise.common.label`

QUANTITY · SALE BASIS

`stop-weigh.cruise.common.claim`

Sell by weight, length, or time — at whatever precision the goods need.

`stop-weigh.cruise.common.shape`

quantity_unit → { unit, scale, increment? }

`stop-weigh.cruise.common.intro`

quantity counts steps, not units: 150 × 0.01 lb = 1.50 lb.

`stop-weigh.cruise.common.anatomy.unit`

what you sell by; a Rec 20 code where one fits, or your own

`stop-weigh.cruise.common.anatomy.scale`

how fine one step is; scale 2 means hundredths

`stop-weigh.cruise.common.anatomy.increment`

how Buyers may order it; advisory, never a limit

`stop-weigh.cruise.common.body`

Correct by construction, not by convention: every number on the wire is an integer plus a declared interpretation. 120 is cents of USD; 150 is hundredths of a pound.

`stop-weigh.dive.artifact.label`

BANANAS BY WEIGHT · PURCHASE TO SETTLEMENT

`stop-weigh.dive.artifact.key`

quantity_unit

`stop-weigh.dive.artifact.title`

Order 1.50 lb. Ship 0.50. Return 0.25. Nothing drifts.

`stop-weigh.dive.artifact.body`

Per-item units and precision, tracked from catalog to cart to order to fulfillment. Each surface inherits the basis it was handed rather than re-deriving it.

`stop-weigh.dive.artifact.stage.1`

THE PURCHASE

`stop-weigh.dive.artifact.stage.2`

THE SETTLEMENT

`stop-weigh.dive.artifact.takeaway.1`

Price is per whole pound, quantity is in steps: 80 × 150 × 10⁻² = 120 cents. Exactly $1.20 — no rounding, and no decimal anywhere in the arithmetic.

`stop-weigh.dive.artifact.takeaway.2`

Ordered 1.50 lb, short-picked to 0.50, then 0.25 returned. Both adjustments move quantity with money — and the 25 steps still owed are exactly 20 cents.

`stop-weigh.dive.control`

COMPLETE · SHIP 0.50 · RETURN 0.25 · GET ORDER

`stop-weigh.whisper`

The arithmetic holds — through the warehouse, the partial shipment, the refund.

`billboard.kicker`

THE BILLBOARD · INTERMISSION

`billboard.lede`

Want the design philosophy? It's 47 minutes, one click away.

`billboard.caption`

Tobi Lütke × Ilya Grigorik: Building the Universal Commerce Protocol — Shopify, 2026-05-19 · 47:18.

`billboard.wit`

At 20:01, Tobi says he'd love to see the bazaar actually visualized. You're standing in it.

`billboard.link`

youtube.com/watch?v=uNOFaCq8RZQ

`inspector.footer`

Every payload on this page validates against the release schemas — the same CI that keeps the spec's own examples honest.

`ng+.kicker`

RELEASE LEDGER · EVERY RECEIPT

Validator-sealed payloads

01 · CHECKOUT CREATE → COMPLETE

shopping/checkout · create request/response + complete request/response

An item-only checkout create request becomes one completed checkout with an order receipt.

create_request

{
  "line_items": [
    {
      "item": {
        "id": "sku_ceramic_mug_blue"
      },
      "quantity": 1
    }
  ],
  "buyer": {
    "email": "ava@example.com"
  },
  "context": {
    "address_country": "US",
    "postal_code": "94105",
    "currency": "USD"
  }
}

created_checkout

{
  "ucp": {
    "version": "2026-08-07",
    "status": "success",
    "capabilities": {
      "dev.ucp.shopping.checkout": [
        {
          "version": "2026-08-07"
        }
      ]
    },
    "payment_handlers": {}
  },
  "id": "chk_basic_01",
  "line_items": [
    {
      "id": "li_basic_01",
      "item": {
        "id": "sku_ceramic_mug_blue",
        "title": "Cobalt Ceramic Mug",
        "price": 2800
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 2800
        },
        {
          "type": "total",
          "amount": 2800
        }
      ]
    }
  ],
  "status": "ready_for_complete",
  "currency": "USD",
  "totals": [
    {
      "type": "subtotal",
      "amount": 2800
    },
    {
      "type": "total",
      "amount": 2800
    }
  ],
  "links": [],
  "expires_at": "2026-08-07T18:00:00Z"
}

complete_request

{
  "payment": {
    "instruments": [
      {
        "id": "pi_basic_card_01",
        "handler_id": "card_handler_basic",
        "type": "card",
        "credential": {
          "type": "card",
          "token": "tok_card_visa_4242"
        },
        "selected": true
      }
    ]
  }
}

completed_checkout

{
  "ucp": {
    "version": "2026-08-07",
    "status": "success",
    "capabilities": {
      "dev.ucp.shopping.checkout": [
        {
          "version": "2026-08-07"
        }
      ]
    },
    "payment_handlers": {
      "com.example.card": [
        {
          "id": "card_handler_basic",
          "version": "2026-08-07"
        }
      ]
    }
  },
  "id": "chk_basic_01",
  "line_items": [
    {
      "id": "li_basic_01",
      "item": {
        "id": "sku_ceramic_mug_blue",
        "title": "Cobalt Ceramic Mug",
        "price": 2800
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 2800
        },
        {
          "type": "total",
          "amount": 2800
        }
      ]
    }
  ],
  "status": "completed",
  "currency": "USD",
  "totals": [
    {
      "type": "subtotal",
      "amount": 2800
    },
    {
      "type": "total",
      "amount": 2800
    }
  ],
  "links": [],
  "payment": {
    "instruments": [
      {
        "id": "pi_basic_card_01",
        "handler_id": "card_handler_basic",
        "type": "card",
        "selected": true
      }
    ]
  },
  "order": {
    "id": "ord_basic_1042",
    "label": "Order #1042",
    "permalink_url": "https://merchant.example/orders/ord_basic_1042"
  }
}

Receipts: #359 · MERGED · 2026-05-20

02 · THE GATE · PAYMENT AUTHENTICATION

common/payment_authentication#dev.ucp.shopping.checkout · complete response + embedded JSON-RPC + Get Checkout response

The Business returns a 3DS challenge Action. The Platform opens its surface. After the surface finishes, the Platform reads the same Checkout again for the outcome.

action_outstanding

{
  "ucp": {
    "version": "2026-08-07",
    "status": "success",
    "capabilities": {
      "dev.ucp.shopping.checkout": [
        {
          "version": "2026-08-07"
        }
      ],
      "dev.ucp.common.payment.authentication": [
        {
          "version": "2026-08-07",
          "extends": "dev.ucp.shopping.checkout"
        }
      ]
    },
    "payment_handlers": {
      "com.example.card": [
        {
          "id": "card_handler_3ds",
          "version": "2026-08-07"
        }
      ]
    }
  },
  "id": "chk_gate_3ds_01",
  "line_items": [
    {
      "id": "li_gate_01",
      "item": {
        "id": "sku_ridge_trail_jacket",
        "title": "Ridge Trail Jacket",
        "price": 18900
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 18900
        },
        {
          "type": "total",
          "amount": 18900
        }
      ]
    }
  ],
  "currency": "USD",
  "totals": [
    {
      "type": "subtotal",
      "amount": 18900
    },
    {
      "type": "total",
      "amount": 18900
    }
  ],
  "links": [],
  "payment": {
    "instruments": [
      {
        "id": "pi_card_3ds_01",
        "handler_id": "card_handler_3ds",
        "type": "card",
        "selected": true
      }
    ]
  },
  "status": "complete_in_progress",
  "actions": {
    "dev.ucp.common.payment.three_ds_challenge": [
      {
        "id": "three_ds_challenge_01",
        "config": {
          "payment_instrument_id": "pi_card_3ds_01",
          "url": "https://payments.example/3ds/challenge/ch_8f31"
        }
      }
    ]
  }
}

surface_finished

{
  "action_ready_request": {
    "jsonrpc": "2.0",
    "id": "ready-3ds-01",
    "method": "action.ready",
    "params": {
      "id": "three_ds_challenge_01",
      "version": "2026-08-07"
    }
  },
  "action_ready_response": {
    "jsonrpc": "2.0",
    "id": "ready-3ds-01",
    "result": {}
  },
  "action_done_notification": {
    "jsonrpc": "2.0",
    "method": "action.done",
    "params": {
      "id": "three_ds_challenge_01"
    }
  }
}

business_outcome

{
  "ucp": {
    "version": "2026-08-07",
    "status": "success",
    "capabilities": {
      "dev.ucp.shopping.checkout": [
        {
          "version": "2026-08-07"
        }
      ],
      "dev.ucp.common.payment.authentication": [
        {
          "version": "2026-08-07",
          "extends": "dev.ucp.shopping.checkout"
        }
      ]
    },
    "payment_handlers": {
      "com.example.card": [
        {
          "id": "card_handler_3ds",
          "version": "2026-08-07"
        }
      ]
    }
  },
  "id": "chk_gate_3ds_01",
  "line_items": [
    {
      "id": "li_gate_01",
      "item": {
        "id": "sku_ridge_trail_jacket",
        "title": "Ridge Trail Jacket",
        "price": 18900
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 18900
        },
        {
          "type": "total",
          "amount": 18900
        }
      ]
    }
  ],
  "currency": "USD",
  "totals": [
    {
      "type": "subtotal",
      "amount": 18900
    },
    {
      "type": "total",
      "amount": 18900
    }
  ],
  "links": [],
  "payment": {
    "instruments": [
      {
        "id": "pi_card_3ds_01",
        "handler_id": "card_handler_3ds",
        "type": "card",
        "selected": true
      }
    ]
  },
  "status": "completed",
  "order": {
    "id": "ord_gate_1043",
    "label": "Order #1043",
    "permalink_url": "https://merchant.example/orders/ord_gate_1043"
  }
}

Receipts: #582 · MERGED · 2026-07-22 · #458 · MERGED · 2026-08-04

03 · POLICY FORUM · POLICIES[]

shopping/checkout · read response

A response-wide 30-day return policy covers the purchase; a same-type final-sale policy targets and replaces it for the engraved item.

checkout

{
  "ucp": {
    "version": "2026-08-07",
    "status": "success",
    "capabilities": {
      "dev.ucp.shopping.checkout": [
        {
          "version": "2026-08-07"
        }
      ]
    },
    "payment_handlers": {}
  },
  "id": "chk_policy_01",
  "line_items": [
    {
      "id": "li_weekender_pack",
      "item": {
        "id": "sku_weekender_pack",
        "title": "Weekender Pack",
        "price": 8700
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 8700
        },
        {
          "type": "total",
          "amount": 8700
        }
      ]
    },
    {
      "id": "li_engraved_luggage_tag",
      "item": {
        "id": "sku_engraved_luggage_tag",
        "title": "Engraved Luggage Tag",
        "price": 1800
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 1800
        },
        {
          "type": "total",
          "amount": 1800
        }
      ]
    }
  ],
  "status": "ready_for_complete",
  "currency": "USD",
  "totals": [
    {
      "type": "subtotal",
      "amount": 10500
    },
    {
      "type": "total",
      "amount": 10500
    }
  ],
  "links": [
    {
      "type": "refund_policy",
      "title": "Returns",
      "url": "https://merchant.example/policies/returns"
    }
  ],
  "policies": [
    {
      "type": "dev.ucp.shopping.policy.return",
      "description": {
        "plain": "Returns are accepted within 30 days of delivery."
      }
    },
    {
      "type": "dev.ucp.shopping.policy.return",
      "description": {
        "plain": "This engraved item is final sale and cannot be returned."
      },
      "applies_to": [
        "$.line_items[1]"
      ]
    }
  ],
  "messages": [
    {
      "type": "warning",
      "code": "dev.ucp.shopping.policy.return",
      "path": "$.line_items[1]",
      "content": "This engraved item is final sale and cannot be returned.",
      "presentation": "disclosure",
      "url": "https://merchant.example/policies/returns#final-sale"
    }
  ]
}

Receipts: #572 · MERGED · 2026-07-23

04 · PAYMENT PRIMITIVES — WHAT PAYS / WHEN DUE

common/payment_split_payments + common/payment_terms · profile, checkout request/response, order response

A Checkout can express what pays and when payment is due through two distinct, validated extension flows.

split_business_profile

{
  "ucp": {
    "version": "2026-08-07",
    "services": {},
    "capabilities": {
      "dev.ucp.common.payment.split_payments": [
        {
          "version": "2026-08-07",
          "schema": "https://ucp.dev/schemas/common/payment_split_payments.json",
          "extends": "dev.ucp.shopping.checkout",
          "config": {
            "allowed_combinations": [
              [
                {
                  "types": [
                    "gift_card"
                  ],
                  "min": 1,
                  "max": 1
                },
                {
                  "types": [
                    "loyalty"
                  ],
                  "min": 0,
                  "max": 1
                },
                {
                  "types": [
                    "card"
                  ],
                  "min": 0,
                  "max": 1
                }
              ]
            ]
          }
        }
      ]
    },
    "payment_handlers": {}
  }
}

split_complete_request

{
  "payment": {
    "instruments": [
      {
        "id": "pi_gift_01",
        "handler_id": "gift_card_handler_01",
        "type": "gift_card",
        "credential": {
          "type": "gift_card",
          "token": "gc_field_watch_25"
        },
        "selected": true
      },
      {
        "id": "pi_points_01",
        "handler_id": "loyalty_points_handler_01",
        "type": "loyalty",
        "credential": {
          "type": "loyalty",
          "token": "points_member_73a9"
        },
        "amount": 1500,
        "selected": true
      },
      {
        "id": "pi_card_split_01",
        "handler_id": "card_handler_split_01",
        "type": "card",
        "credential": {
          "type": "network_token",
          "number": "4895370012345678",
          "cryptogram": "AgAAAAAABk4DWZ4C28yUQAAAAAA="
        },
        "amount": 10000,
        "selected": true
      }
    ]
  }
}

split_complete_response

{
  "ucp": {
    "version": "2026-08-07",
    "status": "success",
    "capabilities": {
      "dev.ucp.shopping.checkout": [
        {
          "version": "2026-08-07"
        }
      ],
      "dev.ucp.common.payment.split_payments": [
        {
          "version": "2026-08-07",
          "extends": "dev.ucp.shopping.checkout"
        }
      ]
    },
    "payment_handlers": {
      "com.example.gift_card": [
        {
          "id": "gift_card_handler_01",
          "version": "2026-08-07"
        }
      ],
      "com.example.loyalty_points": [
        {
          "id": "loyalty_points_handler_01",
          "version": "2026-08-07"
        }
      ],
      "com.example.card": [
        {
          "id": "card_handler_split_01",
          "version": "2026-08-07"
        }
      ]
    }
  },
  "id": "chk_split_01",
  "line_items": [
    {
      "id": "li_split_01",
      "item": {
        "id": "sku_field_watch",
        "title": "Field Watch",
        "price": 14000
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 14000
        },
        {
          "type": "total",
          "amount": 14000
        }
      ]
    }
  ],
  "status": "completed",
  "currency": "USD",
  "totals": [
    {
      "type": "subtotal",
      "amount": 14000
    },
    {
      "type": "total",
      "amount": 14000
    }
  ],
  "links": [],
  "payment": {
    "instruments": [
      {
        "id": "pi_gift_01",
        "handler_id": "gift_card_handler_01",
        "type": "gift_card",
        "amount": 2500,
        "selected": true
      },
      {
        "id": "pi_points_01",
        "handler_id": "loyalty_points_handler_01",
        "type": "loyalty",
        "amount": 1500,
        "selected": true
      },
      {
        "id": "pi_card_split_01",
        "handler_id": "card_handler_split_01",
        "type": "card",
        "amount": 10000,
        "selected": true
      }
    ]
  },
  "order": {
    "id": "ord_split_1044",
    "label": "Order #1044",
    "permalink_url": "https://merchant.example/orders/ord_split_1044"
  }
}

terms_offer_response

{
  "ucp": {
    "version": "2026-08-07",
    "status": "success",
    "capabilities": {
      "dev.ucp.shopping.checkout": [
        {
          "version": "2026-08-07"
        }
      ],
      "dev.ucp.common.payment.terms": [
        {
          "version": "2026-08-07",
          "extends": [
            "dev.ucp.shopping.checkout",
            "dev.ucp.shopping.order"
          ]
        }
      ]
    },
    "payment_handlers": {
      "com.example.card_handler": [
        {
          "id": "card_handler",
          "version": "2026-08-07",
          "available_instruments": [
            {
              "type": "card"
            }
          ]
        }
      ]
    }
  },
  "id": "checkout_7c1",
  "status": "incomplete",
  "currency": "USD",
  "line_items": [
    {
      "id": "li_table",
      "item": {
        "id": "table_oak_made_to_order",
        "title": "Made-to-order Oak Dining Table",
        "price": 120000
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 120000
        },
        {
          "type": "total",
          "amount": 120000
        }
      ]
    }
  ],
  "links": [],
  "totals": [
    {
      "type": "subtotal",
      "amount": 120000
    },
    {
      "type": "discount",
      "amount": -5000,
      "display_text": "Pay-now saving"
    },
    {
      "type": "total",
      "amount": 115000
    }
  ],
  "payment": {
    "selected_term_id": "pt_pay_now",
    "terms": [
      {
        "id": "pt_pay_now",
        "title": "Pay now",
        "description": {
          "plain": "Save $50 by paying in full today."
        },
        "schedules": [
          {
            "id": "sched_full",
            "type": "immediate",
            "description": {
              "plain": "Due today when you order."
            },
            "amount": 115000
          }
        ]
      },
      {
        "id": "pt_deposit_30_days",
        "title": "Deposit now, balance in 30 days",
        "description": {
          "plain": "Pay a $300 deposit today and the $900 balance in 30 days."
        },
        "schedules": [
          {
            "id": "sched_deposit",
            "type": "immediate",
            "description": {
              "plain": "Due today when you order."
            },
            "amount": 30000
          },
          {
            "id": "sched_balance_30_days",
            "type": "deferred",
            "description": {
              "plain": "Due in 30 days on September 24, 2026 at 12:00 PM UTC."
            },
            "due_at": "2026-09-24T12:00:00Z",
            "amount": 90000
          }
        ]
      }
    ]
  },
  "policies": [
    {
      "type": "com.example.policy.payment_term_total",
      "applies_to": [
        "$.payment.terms[1]"
      ],
      "description": {
        "plain": "The deposit term totals $1,200, which is $50 more than paying in full today."
      }
    }
  ],
  "messages": [
    {
      "type": "warning",
      "code": "com.example.policy.payment_term_total",
      "path": "$.payment.terms[1]",
      "content": "$1,200 total — $50 more than paying today",
      "presentation": "disclosure"
    }
  ]
}

terms_select_request

{
  "line_items": [
    {
      "item": {
        "id": "table_oak_made_to_order"
      },
      "quantity": 1
    }
  ],
  "payment": {
    "selected_term_id": "pt_deposit_30_days"
  }
}

terms_selected_response

{
  "ucp": {
    "version": "2026-08-07",
    "status": "success",
    "capabilities": {
      "dev.ucp.shopping.checkout": [
        {
          "version": "2026-08-07"
        }
      ],
      "dev.ucp.common.payment.terms": [
        {
          "version": "2026-08-07",
          "extends": [
            "dev.ucp.shopping.checkout",
            "dev.ucp.shopping.order"
          ]
        }
      ]
    },
    "payment_handlers": {
      "com.example.card_handler": [
        {
          "id": "card_handler",
          "version": "2026-08-07",
          "available_instruments": [
            {
              "type": "card"
            }
          ]
        }
      ]
    }
  },
  "id": "checkout_7c1",
  "status": "incomplete",
  "currency": "USD",
  "line_items": [
    {
      "id": "li_table",
      "item": {
        "id": "table_oak_made_to_order",
        "title": "Made-to-order Oak Dining Table",
        "price": 120000
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 120000
        },
        {
          "type": "total",
          "amount": 120000
        }
      ]
    }
  ],
  "links": [],
  "totals": [
    {
      "type": "subtotal",
      "amount": 120000
    },
    {
      "type": "total",
      "amount": 120000
    }
  ],
  "payment": {
    "selected_term_id": "pt_deposit_30_days",
    "terms": [
      {
        "id": "pt_pay_now",
        "title": "Pay now",
        "description": {
          "plain": "Save $50 by paying in full today."
        },
        "schedules": [
          {
            "id": "sched_full",
            "type": "immediate",
            "description": {
              "plain": "Due today when you order."
            },
            "amount": 115000
          }
        ]
      },
      {
        "id": "pt_deposit_30_days",
        "title": "Deposit now, balance in 30 days",
        "description": {
          "plain": "Pay a $300 deposit today and the $900 balance in 30 days."
        },
        "schedules": [
          {
            "id": "sched_deposit",
            "type": "immediate",
            "description": {
              "plain": "Due today when you order."
            },
            "amount": 30000
          },
          {
            "id": "sched_balance_30_days",
            "type": "deferred",
            "description": {
              "plain": "Due in 30 days on September 24, 2026 at 12:00 PM UTC."
            },
            "due_at": "2026-09-24T12:00:00Z",
            "amount": 90000
          }
        ]
      }
    ]
  },
  "policies": [
    {
      "type": "com.example.policy.payment_term_total",
      "applies_to": [
        "$.payment.terms[1]"
      ],
      "description": {
        "plain": "The deposit term totals $1,200, which is $50 more than paying in full today."
      }
    }
  ],
  "messages": [
    {
      "type": "warning",
      "code": "com.example.policy.payment_term_total",
      "path": "$.payment.terms[1]",
      "content": "$1,200 total — $50 more than paying today",
      "presentation": "disclosure"
    }
  ]
}

terms_order_response

{
  "ucp": {
    "version": "2026-08-07",
    "capabilities": {
      "dev.ucp.shopping.order": [
        {
          "version": "2026-08-07"
        }
      ],
      "dev.ucp.common.payment.terms": [
        {
          "version": "2026-08-07",
          "extends": [
            "dev.ucp.shopping.checkout",
            "dev.ucp.shopping.order"
          ]
        }
      ]
    }
  },
  "id": "order_9f2",
  "checkout_id": "checkout_7c1",
  "permalink_url": "https://merchant.example/orders/order_9f2",
  "currency": "USD",
  "line_items": [
    {
      "id": "li_table",
      "item": {
        "id": "table_oak_made_to_order",
        "title": "Made-to-order Oak Dining Table",
        "price": 120000
      },
      "quantity": {
        "original": 1,
        "total": 1,
        "fulfilled": 0
      },
      "totals": [
        {
          "type": "subtotal",
          "amount": 120000
        },
        {
          "type": "total",
          "amount": 120000
        }
      ],
      "status": "processing"
    }
  ],
  "fulfillment": {
    "expectations": []
  },
  "totals": [
    {
      "type": "subtotal",
      "amount": 120000
    },
    {
      "type": "total",
      "amount": 120000
    }
  ],
  "payment": {
    "accepted_term": {
      "id": "pt_deposit_30_days",
      "title": "Deposit now, balance in 30 days",
      "description": {
        "plain": "Pay a $300 deposit today and the $900 balance in 30 days."
      },
      "schedules": [
        {
          "id": "sched_deposit",
          "type": "immediate",
          "description": {
            "plain": "Due today when you order."
          },
          "amount": 30000
        },
        {
          "id": "sched_balance_30_days",
          "type": "deferred",
          "description": {
            "plain": "Due in 30 days on September 24, 2026 at 12:00 PM UTC."
          },
          "due_at": "2026-09-24T12:00:00Z",
          "amount": 90000
        }
      ]
    }
  },
  "policies": [
    {
      "type": "com.example.policy.payment_term_total",
      "applies_to": [
        "$.payment.accepted_term"
      ],
      "description": {
        "plain": "The accepted term totals $1,200, which is $50 more than paying in full today."
      }
    }
  ],
  "messages": [
    {
      "type": "warning",
      "code": "com.example.policy.payment_term_total",
      "path": "$.payment.accepted_term",
      "content": "$1,200 total — $50 more than paying today",
      "presentation": "disclosure"
    }
  ]
}

Receipts: #409 · MERGED · 2026-05-23 · #602 · MERGED · 2026-08-14

05 · TRUST QUARTER · BUYER AUTHORIZATION

profile business_schema + OAuth RFC 8693/RFC 7523

As a labeled example, a Business advertises Shopify Accounts as a trusted external IdP and a capability-scoped checkout permission; a matching Platform can chain identity without a browser redirect and obtain a Business-issued token.

business_profile

{
  "ucp": {
    "version": "2026-08-07",
    "services": {
      "dev.ucp.shopping": [
        {
          "version": "2026-08-07",
          "transport": "rest",
          "endpoint": "https://merchant.example.com"
        }
      ]
    },
    "capabilities": {
      "dev.ucp.shopping.checkout": [
        {
          "version": "2026-08-07",
          "schema": "https://ucp.dev/schemas/shopping/checkout.json"
        }
      ],
      "dev.ucp.common.identity_linking": [
        {
          "version": "2026-08-07",
          "schema": "https://ucp.dev/schemas/common/identity_linking.json",
          "config": {
            "providers": {
              "com.shopify.accounts": [
                {
                  "type": "oauth2",
                  "auth_url": "https://accounts.shopify.com"
                }
              ]
            },
            "scopes": {
              "dev.ucp.shopping.checkout:manage": {
                "description": {
                  "plain": "Manage checkout for the linked Buyer account."
                }
              }
            }
          }
        }
      ]
    },
    "payment_handlers": {}
  }
}

idp_token_exchange_request

{
  "method": "POST",
  "authority": "accounts.shopify.com",
  "path": "/oauth/token",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded",
    "Authorization": "Basic dWNwX2V4YW1wbGVfcGxhdGZvcm06dWNwX2V4YW1wbGVfaWRwX3NlY3JldA=="
  },
  "body": "grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange&subject_token=ucp_example_shop_access_42A&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aaccess_token&resource=https%3A%2F%2Fmerchant.example.com&requested_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Ajwt"
}

idp_token_exchange_response

{
  "status": 200,
  "reason": "OK",
  "headers": {
    "Content-Type": "application/json",
    "Cache-Control": "no-store",
    "Pragma": "no-cache"
  },
  "body": {
    "access_token": "eyJhbGciOiJFZERTQSIsImtpZCI6IlRoTlZxdmhKNHJHSWk2cFExMzNmVldldjlCTGhydUsxdHRrYTJGYzhfcVkiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJodHRwczovL2FjY291bnRzLnNob3BpZnkuY29tIiwic3ViIjoiYnV5ZXJfZml4dHVyZV80MiIsImF1ZCI6Imh0dHBzOi8vbWVyY2hhbnQuZXhhbXBsZS5jb20iLCJpYXQiOjE3ODc3NDU2MDAsImV4cCI6MTc4Nzc0NTY2MCwianRpIjoiZ3JhbnRfZXhhbXBsZV9zaG9waWZ5X2FjY291bnRzXzAxIn0.Y7eIpuJuaDZc6uWdMR6jIV4wyWl29BMEIa1SUObXQMm1tFAiRPWBlmvJrJORC22KuMWpod8nllxA0d3gn-yOAg",
    "issued_token_type": "urn:ietf:params:oauth:token-type:jwt",
    "token_type": "N_A",
    "expires_in": 60
  }
}

business_token_request

{
  "method": "POST",
  "authority": "merchant.example.com",
  "path": "/oauth/token",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded",
    "Authorization": "Basic dWNwX2V4YW1wbGVfcGxhdGZvcm06dWNwX2V4YW1wbGVfc2VjcmV0"
  },
  "body": "grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJFZERTQSIsImtpZCI6IlRoTlZxdmhKNHJHSWk2cFExMzNmVldldjlCTGhydUsxdHRrYTJGYzhfcVkiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJodHRwczovL2FjY291bnRzLnNob3BpZnkuY29tIiwic3ViIjoiYnV5ZXJfZml4dHVyZV80MiIsImF1ZCI6Imh0dHBzOi8vbWVyY2hhbnQuZXhhbXBsZS5jb20iLCJpYXQiOjE3ODc3NDU2MDAsImV4cCI6MTc4Nzc0NTY2MCwianRpIjoiZ3JhbnRfZXhhbXBsZV9zaG9waWZ5X2FjY291bnRzXzAxIn0.Y7eIpuJuaDZc6uWdMR6jIV4wyWl29BMEIa1SUObXQMm1tFAiRPWBlmvJrJORC22KuMWpod8nllxA0d3gn-yOAg&scope=dev.ucp.shopping.checkout%3Amanage"
}

business_token_response

{
  "status": 200,
  "reason": "OK",
  "headers": {
    "Content-Type": "application/json",
    "Cache-Control": "no-store",
    "Pragma": "no-cache"
  },
  "body": {
    "access_token": "ucp_example_business_token_7Q2",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "dev.ucp.shopping.checkout:manage"
  }
}

Receipts: #354 · MERGED · BREAKING · 2026-05-05 · #423 · MERGED · 2026-06-12

06 · TRUST QUARTER · AGENT AUTHENTICATION

profile platform_schema + shopping/checkout create request + RFC 9421/WBA

One RFC 9421 signature covers UCP-Agent, Signature-Agent, the required request components, and the body digest; it uses the canonical keys[] thumbprint and passes both UCP and Web Bot Auth coverage gates.

platform_profile

{
  "ucp": {
    "version": "2026-08-07",
    "services": {},
    "capabilities": {
      "dev.ucp.shopping.checkout": [
        {
          "version": "2026-08-07",
          "spec": "https://ucp.dev/specification/shopping/checkout/",
          "schema": "https://ucp.dev/schemas/shopping/checkout.json"
        }
      ],
      "dev.ucp.common.identity_linking": [
        {
          "version": "2026-08-07",
          "spec": "https://ucp.dev/specification/common/identity-linking/",
          "schema": "https://ucp.dev/schemas/common/identity_linking.json"
        }
      ]
    },
    "payment_handlers": {}
  },
  "keys": [
    {
      "kid": "WoOeln2F5gNLAu8fKU7MY8iG_7B_g03qyFv38dV068w",
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "TGtJo8Q-qv7OXb9U6cQVT0D3nqjh3hYS7Ev4d-wI7ww",
      "use": "sig"
    }
  ]
}

runtime_request

{
  "method": "POST",
  "authority": "merchant.example.com",
  "path": "/checkout-sessions",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer ucp_example_business_token_7Q2",
    "UCP-Agent": "profile=\"https://platform.example/.well-known/ucp\"",
    "Signature-Agent": "sig1=\"https://platform.example/.well-known/ucp\";type=jwks_uri",
    "Idempotency-Key": "550e8400-e29b-41d4-a716-446655440000",
    "Content-Digest": "sha-256=:leXoa3FKKUAMFTdq8N3nWDxiosg58m3sa1Ijui1xSl4=:",
    "Signature-Input": "sig1=(\"@method\" \"@authority\" \"@path\" \"signature-agent\";key=\"sig1\" \"ucp-agent\" \"idempotency-key\" \"content-digest\" \"content-type\");keyid=\"WoOeln2F5gNLAu8fKU7MY8iG_7B_g03qyFv38dV068w\";created=1787745600;expires=1787749200;nonce=\"3sjp6eJ-E7bv5VFMkCDO5GF2tW-uwQ7mvSsxJpo_dTRYWZ6nJeFqdid1dm_c9juN1_NkYhe4VBQYUw1wiAJVsA\";tag=\"web-bot-auth\"",
    "Signature": "sig1=:Cv7tpyAk2P24CIh0UrvtJKiOF1WtaSrGiG2kuhW5adSWMeQc6GafFAtlgtvZLKA0dgJqbp0WF1FNmn9b8jsiBA==:"
  },
  "body": {
    "line_items": [
      {
        "item": {
          "id": "item_123"
        },
        "quantity": 2
      }
    ]
  }
}

Receipts: #483 · MERGED · 2026-07-03 · #566 · MERGED · BREAKING · 2026-07-12

THE MAP ROOM · LOCATION SEARCH → PICKUP

common/location_search · search request + response; shopping/fulfillment · checkout update request + response

Location Search discovers a physical place that satisfies four independent predicates; the Platform explicitly selects that stable Location ID for pickup, and the Business revalidates it.

search_request

{
  "distance": {
    "center": {
      "latitude": 37.775,
      "longitude": -122.419
    },
    "max": 8000
  },
  "filters": {
    "items": [
      "var_aerostride_7_cobalt_us10"
    ],
    "hours": {
      "open_at": "2026-08-25T18:00:00-07:00"
    },
    "amenities": [
      "dev.ucp.amenity.shopping.in_store_pickup"
    ]
  }
}

search_response

{
  "ucp": {
    "version": "2026-08-07",
    "status": "success",
    "capabilities": {
      "dev.ucp.common.location.search": [
        {
          "version": "2026-08-07"
        }
      ]
    }
  },
  "locations": [
    {
      "id": "loc_market_street",
      "name": "Market Street Running",
      "address": {
        "street_address": "100 Market Street",
        "address_locality": "San Francisco",
        "address_region": "CA",
        "address_country": "US",
        "postal_code": "94105"
      },
      "geo": {
        "latitude": 37.793,
        "longitude": -122.395
      },
      "amenities": {
        "dev.ucp.amenity.shopping.in_store_pickup": {
          "description": "In-store pickup"
        }
      },
      "timezone": "America/Los_Angeles",
      "hours": [
        {
          "day": "tuesday",
          "opens": "10:00",
          "closes": "20:00"
        }
      ]
    }
  ]
}

pickup_request

{
  "line_items": [
    {
      "id": "li_shoe_01",
      "item": {
        "id": "var_aerostride_7_cobalt_us10"
      },
      "quantity": 1
    }
  ],
  "fulfillment": {
    "methods": [
      {
        "id": "method_pickup",
        "type": "pickup",
        "line_item_ids": [
          "li_shoe_01"
        ],
        "selected_destination_id": "loc_market_street"
      }
    ]
  }
}

pickup_response

{
  "ucp": {
    "version": "2026-08-07",
    "status": "success",
    "capabilities": {
      "dev.ucp.shopping.checkout": [
        {
          "version": "2026-08-07"
        }
      ],
      "dev.ucp.shopping.fulfillment": [
        {
          "version": "2026-08-07",
          "extends": "dev.ucp.shopping.checkout"
        }
      ]
    },
    "payment_handlers": {}
  },
  "id": "chk_aerostride_01",
  "line_items": [
    {
      "id": "li_shoe_01",
      "item": {
        "id": "var_aerostride_7_cobalt_us10",
        "title": "AeroStride 7 · Cobalt · US 10",
        "price": 14800
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 14800
        },
        {
          "type": "total",
          "amount": 14800
        }
      ]
    }
  ],
  "status": "ready_for_complete",
  "currency": "USD",
  "totals": [
    {
      "type": "subtotal",
      "amount": 14800
    },
    {
      "type": "total",
      "amount": 14800
    }
  ],
  "links": [],
  "fulfillment": {
    "methods": [
      {
        "id": "method_pickup",
        "type": "pickup",
        "line_item_ids": [
          "li_shoe_01"
        ],
        "selected_destination_id": "loc_market_street",
        "destinations": [
          {
            "type": "business_location",
            "id": "loc_market_street",
            "name": "Market Street Running",
            "address": {
              "street_address": "100 Market Street",
              "address_locality": "San Francisco",
              "address_region": "CA",
              "address_country": "US",
              "postal_code": "94105"
            }
          }
        ]
      }
    ]
  }
}

Receipts: #589 · MERGED · BREAKING · 2026-08-25 · #688 · MERGED · BREAKING · 2026-08-18

07 · THE CART EXCHANGE · PERMALINK

shopping/permalink business_schema + shopping/discount#dev.ucp.shopping.checkout · create request

This fixture maps a discovered endpoint and compact item URL to one schema-valid, discount-extended Checkout create request, with a possible browser handoff.

business_profile

{
  "ucp": {
    "version": "2026-08-07",
    "services": {},
    "capabilities": {
      "dev.ucp.shopping.permalink": [
        {
          "version": "2026-08-07",
          "spec": "https://ucp.dev/2026-08-07/specification/permalink",
          "schema": "https://ucp.dev/2026-08-07/schemas/shopping/permalink.json",
          "config": {
            "endpoint": "https://merchant.example/buy"
          }
        }
      ],
      "dev.ucp.shopping.checkout": [
        {
          "version": "2026-08-07",
          "spec": "https://ucp.dev/2026-08-07/specification/shopping/checkout",
          "schema": "https://ucp.dev/2026-08-07/schemas/shopping/checkout.json"
        }
      ],
      "dev.ucp.shopping.discount": [
        {
          "version": "2026-08-07",
          "spec": "https://ucp.dev/2026-08-07/specification/shopping/extensions/discount",
          "schema": "https://ucp.dev/2026-08-07/schemas/shopping/discount.json",
          "extends": "dev.ucp.shopping.checkout"
        }
      ]
    },
    "payment_handlers": {}
  }
}

permalink_url

"https://merchant.example/buy/sku_ceramic_mug_blue:2,sku_cork_coaster:1?discounts/codes/0=SAVE10&context/postal_code=94105&continue_to=%2Fcheckout"

hydrated_checkout_create_request

{
  "line_items": [
    {
      "item": {
        "id": "sku_ceramic_mug_blue"
      },
      "quantity": 2
    },
    {
      "item": {
        "id": "sku_cork_coaster"
      },
      "quantity": 1
    }
  ],
  "context": {
    "postal_code": "94105"
  },
  "discounts": {
    "codes": [
      "SAVE10"
    ]
  }
}

possible_redirect_response

"HTTP/1.1 303 See Other\nLocation: https://merchant.example/checkout\nCache-Control: no-store\nReferrer-Policy: no-referrer"

Receipts: #523 · MERGED · 2026-07-17

08 · THE WEIGH HOUSE · SALE BASIS

shopping/checkout · read response → shopping/order · read response

A 1.50 lb line counts 150 hundredth-pound steps at $0.79/lb; a 0.25 lb return subtracts 25 steps and credits 20 cents.

checkout

{
  "ucp": {
    "version": "2026-08-07",
    "status": "success",
    "payment_handlers": {}
  },
  "id": "chk_bananas_1",
  "status": "incomplete",
  "currency": "USD",
  "line_items": [
    {
      "id": "li_bananas",
      "item": {
        "id": "var_bananas",
        "title": "Bananas",
        "price": 80,
        "quantity_unit": {
          "unit": "LBR",
          "scale": 2,
          "display_text": "lb",
          "increment": 25
        }
      },
      "quantity": 150,
      "totals": [
        {
          "type": "subtotal",
          "amount": 120
        },
        {
          "type": "total",
          "amount": 120
        }
      ]
    }
  ],
  "totals": [
    {
      "type": "subtotal",
      "amount": 120
    },
    {
      "type": "total",
      "amount": 120
    }
  ],
  "links": []
}

order

{
  "ucp": {
    "version": "2026-08-07",
    "capabilities": {
      "dev.ucp.shopping.order": [
        {
          "version": "2026-08-07"
        }
      ]
    }
  },
  "id": "order_bananas_1",
  "checkout_id": "chk_bananas_1",
  "permalink_url": "https://business.example.com/orders/bananas1",
  "currency": "USD",
  "line_items": [
    {
      "id": "li_bananas",
      "item": {
        "id": "var_bananas",
        "title": "Bananas",
        "price": 80,
        "quantity_unit": {
          "unit": "LBR",
          "scale": 2,
          "display_text": "lb",
          "increment": 25
        }
      },
      "quantity": {
        "original": 150,
        "total": 25,
        "fulfilled": 50
      },
      "totals": [
        {
          "type": "subtotal",
          "amount": 120
        },
        {
          "type": "total",
          "amount": 120
        }
      ],
      "status": "partial"
    }
  ],
  "fulfillment": {
    "events": [
      {
        "id": "evt_1",
        "occurred_at": "2026-01-08T10:30:00Z",
        "type": "shipped",
        "line_items": [
          {
            "id": "li_bananas",
            "quantity": 50
          }
        ],
        "tracking_number": "123456789",
        "tracking_url": "https://carrier.example/track/123456789",
        "description": "0.50 lb shipped"
      }
    ]
  },
  "adjustments": [
    {
      "id": "adj_1",
      "type": "cancellation",
      "occurred_at": "2026-01-08T10:30:00Z",
      "status": "completed",
      "line_items": [
        {
          "id": "li_bananas",
          "quantity": -100
        }
      ],
      "totals": [
        {
          "type": "total",
          "amount": -80
        }
      ],
      "description": "Short pick: 1.00 lb unavailable"
    },
    {
      "id": "adj_2",
      "type": "return",
      "occurred_at": "2026-01-10T14:30:00Z",
      "status": "completed",
      "line_items": [
        {
          "id": "li_bananas",
          "quantity": -25
        }
      ],
      "totals": [
        {
          "type": "total",
          "amount": -20
        }
      ],
      "description": "Returned 0.25 lb"
    }
  ],
  "totals": [
    {
      "type": "subtotal",
      "amount": 120
    },
    {
      "type": "total",
      "amount": 120
    }
  ]
}

Receipts: #653 · MERGED · BREAKING · 2026-08-12

RELEASE LEDGER

UNIVERSAL COMMERCE PROTOCOL · UCP · 2026-08 EDITION

For Buyers

Complete your bank's challenge in the presented surface; the Business's later Checkout response carries the outcome. — #458 · #582
Pay how you actually pay: gift card, points, and card together. — #409
Pay in full, put down a deposit, or split into installments — your call. — #602
Your memberships count everywhere your agent shops — tiers, benefits, forecasts. — #340
Say yes or no to marketing once; the answer travels, provenance attached. — #451
Grant your agent scoped access — never your password. — #354
Be recognized at a new business instantly — no redirect, no re-registration. — #423
See return windows before buying — comparable across businesses, structured for enforcement. — #572
Know pickup and delivery options before checkout, not after. — #507
Your agent's cart opens in your browser, ready to pay. — #523
Your preferred wallets rank first on every surface. — #523
A flaky network can't charge you twice. — #485

12 OF 88 IMPROVEMENTS

For Businesses

Ask the Platform or Buyer for any action mid-purchase — verify age, status, or payment. — #582
Accept cards that need a 3DS challenge without treating surface completion as payment success. — #458
Attach machine-readable policies to any cart, checkout, catalog, or order. — #572
Tell Platforms a transaction's narrower requirements up front — constraints ride the response. — #655 · #757
Present payment handlers in your preferred order — map_order makes registry ordering a contract. — #657
Units and fractional quantities, end to end — catalog, cart, fulfillment, returns. — #653
Collect marketing consent as data, with provenance: who asked, what was granted. — #451
Accept gift card, points, and card together — under combination rules you declare. — #409
Offer deposits, installments, or pay-in-full on one checkout — the Buyer picks the term. — #602
Express instrument requirements as request constraints — one grammar, normative across payments. — #424
Offer memberships, tiers, and earning forecasts wherever agents shop you. — #340
See which platform sent each sale; referral economics survive agentic traffic. — #391
Advertise shipping and pickup at discovery — availability answered before checkout. — #507
Turn any agent-built cart into one URL a human can open and pay. — #523
Your identifier can be your domain — an exact host match binds, no extra label. — #627
Let Buyers link accounts through scoped grants — never a shared password. — #354
Recognize returning Buyers instantly — trusted identity arrives without a redirect. — #423
Your namespace provably belongs to your domain; spoofers meet an algorithm. — #530
Retried requests can't double-charge; mutated replays fail loudly. — #485
Serve store-specific pricing and availability — grocery journeys name their branch. — #642
Fulfillment availability now has a defined location input — evaluate against context.location. — #671
Offer pickup and curbside as Business-authored, typed destinations the Platform selects from. — #688

22 OF 88 IMPROVEMENTS

For Platforms & agents

Bring your own identity provider — grants scoped to the capabilities you allow. — #354
Chain a trusted-IdP token to a brand-new business — zero browser redirects. — #423
Sign once — one signature satisfies UCP and Web Bot Auth; keys resolve from one JWK Set. — #483 · #566
Verify schema origin against namespace authority — a derivation algorithm, not an assertion. — #530
Retry safely: identical replays succeed; mutated ones fail — 409, −32000. — #485
Carry Buyer payment-handler preferences, priority-ordered, on every context-bearing surface. — #523
PAN and Network Token are distinct credential types — carry each as itself. — #424
Validate A2A, MCP, JSON-RPC, and Embedded envelopes against published schemas. — #359
Read webhook signatures from headers; payloads validate against base schemas. — #342
Pass a preferred location or store on any request — context.location. — #642
context.location shapes what is available — it is not a shipping address. — #671
Destinations describe themselves: type is required and open in Business responses. — #688
Find a Business's physical locations — search and lookup are protocol capabilities now. — #589
Read outstanding work from a Business response, then follow the declaring extension's processing and fallback rules. — #582
Run a 3DS challenge surface over embedded JSON-RPC, then Get Checkout for the authoritative outcome. — #458
Compare return policies across businesses — JSONPath-targeted data, not footer links. — #572
Stop discovering requirements by failed submission: read ucp.request_constraints — closed grammar, anyOf included. — #655 · #757
Express 1.50 kg exactly: quantity counts steps; quantity_unit declares their denomination. — #653
Carry Buyer consent across businesses, provenance intact: business or platform asked. — #451
Compose tender against declared constraints — combinations validated, not guessed. — #409
Read payment.terms[], submit a choice — the selected term determines total, disclosures, eligible instruments. — #602
Parse instrument requirements with the constraints grammar you already read. — #424
Answer "cheapest for me, points included" with per-business earning forecasts. — #340
Attach referral context to any request — credit for traffic you send. — #391
Know "can I get it, here, this way" at discovery time. — #507
Hand a checkout to a human with every field preserved in the URL. — #523
Crawl llms.txt links that describe themselves before you spend tokens. — #419
Parse messages that name their exact payload path — one convention everywhere. — #380 · #397

28 OF 88 IMPROVEMENTS

Developer ergonomics & housekeeping

Trust every example: CI validates each doc payload against schemas, or skips-with-reason. — #359
Catalog examples validate per operation and direction — no def= escape hatch. — #516
get_product examples get op-specific scaffolds; drift caught at build time. — #616
Validator error paths stay accurate after array elision — indices recorded post-strip. — #686
Validate examples under two schema roots — each resolves independently; cache keyed by root. — #722
Every cross-reference in the spec resolves — links and fragments alike. — #758 · #759
Requirement columns derive per-operation from schemas — tables can't contradict the source. — #542
Look up any term once: a centralized glossary with acronym standards. — #241
Extend the protocol safely: forward-compatibility guidelines, written down. — #290
Pin one dated release: services, capabilities, extensions, and schemas ship as one tested snapshot. — #614
Learn the protocol in one sitting — core concepts rewritten, +363 lines. — #336
llms.txt describes every link it lists — agents find Split Payments and the Glossary. — #419 · #720
Bring a coding agent: the repo ships AGENTS.md operating instructions. — #510
Start contributing from the README — schema and docs workflows documented. — #452
Shared types live in common/ — amounts, links, errors referenced, not copied. — #436
Navigate spec and schemas by vertical — Shopping, Payment, Common — room for more. — #723 · #736 · #761 · #741
The ucp namespace is reserved — protocol vocabulary like request_constraints registers into it. — #657
variant.selected_options is now options — one name, no puzzle. — #353
Profile schemas pass their own validation and honor the endpoint contract. — #429
Token binding works across every vertical — one grammar, not one per domain. — #746
One canonical business fulfillment config; the duplicate is gone. — #581
Cart updates omit id instead of requiring what the URL already says. — #633
cart.id sheds its transition annotation — the omit migration is complete. — #763
Scope a fulfillment method to line items — Platforms can supply line_item_ids now. — #763
Dead weight is gone: deprecated id markers, the orphaned account_info schema. — #646 · #639
Discounts extension schema and its doc examples agree again. — #371
Discount allocation examples show the valid totals path. — #558
create_cart REST carries ucp_agent — the binding matches the protocol. — #362
get_order responses document their signature headers — verifiable end to end. — #370
message.path means the same thing in every schema that carries it. — #380
Error Handling documents message.path conventions — targeting rules in one place. — #397
Signature examples show raw r||s bytes — copy-paste is conformant now. — #590
Signature requirements read cleanly — formatting pass on the normative text. — #242
The signature flow diagram is modern and legible. — #331
Signatures.md footnotes render; tables align. — #291
Identity-linking docs: formatting fixed. — #505
Identity-linked sessions: which values the Business populates, now explicit. — #585
Checkout REST binding gained its missing Discovery section. — #509
Catalog REST documents its headers. — #548
Create Checkout cross-links cart_id — no more hunting. — #439
Common types link to their shared reference section. — #536
get_product error severity note qualified — catalog errors read correctly. — #464
Fulfillment options[].total row corrected to match the schema: totals array. — #561
Fulfillment extension fields documented against checkout, where they actually apply. — #592
Capability-mismatch examples use the real code: capabilities_incompatible. — #562
Embedded session errors nest under params.error, as the schema intends. — #494
Index and versioning pages: typos gone, formatting straightened. — #416
Specification examples brought back into internal consistency. — #363
Documentation accuracy issues fixed across pages. — #365
Example line-item ids no longer masquerade as item ids. — #112
Spurious fulfillment-option entity removed from checkout docs. — #284
MCP response examples drop the entity wrapper they never needed. — #360
Cart error examples carry a valid UCP version. — #504
The docs Playground is correct — examples match the schema, no deprecated ids. — #236 · #332
Total and Totals render on the schema reference page. — #352
Catalog response metadata renders on the reference page. — #465
Embedded schemas keep their required fields when rendered. — #501
Inline oneOf branches show up in the type column. — #549
Array items labeled by type — "any" no longer stands in. — #552
Scalar $defs stop duplicating descriptions in generated docs. — #576
Declare requires in an extension — version negotiation, exercised live for the first time. — #409
Machine-check any transport envelope: strict wrappers, extensible payloads. — #359
Name namespaces with real-world domains — hyphens and digits parse. — #627
The constraints grammar lives in the ucp vocabulary — no parallel namespace invented. — #655 · #757

64 OF 88 IMPROVEMENTS

TOTAL: 88 IMPROVEMENTS OVER 21 WEEKS

+ 50 COMMITS OF UPKEEP — DEPENDENCIES, CI, GOVERNANCE RECORDS

UCP-SCHEMA VALIDATE · PASS

THANK YOU FOR BUILDING WITH UCP

The Screening