Ucp checkout session

UCP Checkout Session

中文摘要：用 UCP 真实 REST 端点驱动结算会话——create / get / update(PUT,整体替换)/ complete / cancel。购物车就是 session 里的 line_items(UCP 没有独立 cart 能力)。包含 buyer、totals、messages,以及完成时返回的 order。对应能力 dev.ucp.shopping.checkout。

When to use / 何时使用

• You have item.ids from discovery and need to build + complete a purchase.
• The user is iterating on quantities/items — that's editing line_items on the session.
• You need authoritative totals (tax, fulfillment, discount) and to place the order.

Cart = the session. Core UCP has no separate cart object; the cart is the line_items array of a checkout session. 购物车即 session 的 line_items。

UCP mapping / UCP 映射

Capability dev.ucp.shopping.checkout. Base URL = ucp.services["dev.ucp.shopping"].endpoint from the merchant's /.well-known/ucp. Five real endpoints:

Operation	Method	Path
Create	POST	/checkout-sessions
Get	GET	/checkout-sessions/{id}
Update	PUT	/checkout-sessions/{id}
Complete	POST	/checkout-sessions/{id}/complete
Cancel	POST	/checkout-sessions/{id}/cancel

PUT replaces the entire session. You must resend every field you want to keep — it is not a partial PATCH. PUT 是整体替换,需带上所有要保留的字段。

Required headers / 必需头部

UCP-Agent: profile="https://platform.example/.well-known/ucp"
Idempotency-Key: <uuid>          # on POST/PUT state changes — prevents double orders
Request-Id: <uuid>
Content-Type: application/json
Accept: application/json
# auth (one of): Authorization: Bearer {token} | X-API-Key: {key}
#               | HTTP Message Signatures (RFC 9421): Signature, Signature-Input, Content-Digest

Request & response fields / 请求与响应字段 (verbatim)

Create/Update request body:

{
  "line_items": [ { "id": "li_1", "item": { "id": "sku_8821" }, "quantity": 2 } ],
  "buyer":   { "first_name": "Ada", "last_name": "L", "email": "[email protected]", "phone_number": "+49…" },
  "fulfillment": { "methods": [ /* see ucp-fulfillment skill */ ] },
  "payment":     { "instruments": [ /* see ap2-payment-mandate skill */ ] },
  "signals":     { /* provided on complete */ }
}

Response (checkout session):

{
  "ucp": { "version": "2026-04-08", "capabilities": { }, "payment_handlers": { }, "status": "success" },
  "id": "cs_01H…",
  "status": "ready_for_complete",          // incomplete | ready_for_complete | completed | canceled | requires_escalation
  "currency": "EUR",
  "messages": [
    { "type": "error", "code": "buyer.email.missing", "path": "$.buyer.email",
      "content": "Email required", "severity": "recoverable" }   // severity: recoverable | unrecoverable
  ],
  "line_items": [
    { "id": "li_1", "item": { "id": "sku_8821", "title": "Trail Runner GTX", "price": 11900 },
      "quantity": 2, "totals": [ { "type": "subtotal", "amount": 23800 } ] }
  ],
  "totals": [                                 // type: subtotal | tax | fulfillment | fee | discount | total
    { "type": "subtotal",    "display_text": "Subtotal",     "amount": 23800 },
    { "type": "fulfillment", "display_text": "Shipping",     "amount": 0 },
    { "type": "tax",         "display_text": "Tax",          "amount": 4522 },
    { "type": "total",       "display_text": "Total",        "amount": 28322 }
  ],
  "fulfillment": { "methods": [ ] },
  "payment": { "instruments": [ ] },
  "links": [ ],
  "continue_url": "https://merchant.example/checkout/cs_01H…",
  "order": { "id": "ord_77Q…", "label": "#1042", "permalink_url": "https://merchant.example/orders/ord_77Q…" }
}

All money amount/price are integers in the currency's minor units. 金额均为最小货币单位整数。

Workflow / 工作流

1. POST /checkout-sessions with line_items → capture id. Server may re-validate inventory and return messages (severity: recoverable|unrecoverable).
2. PUT /checkout-sessions/{id} to set buyer, fulfillment (address + selected option), apply discounts → server returns authoritative totals. Resend all fields (full replace).
3. Drive status toward ready_for_complete; resolve every recoverable message. If requires_escalation, hand back to the user/UI — it can't be resolved via API.
4. Show the total (last totals[type=total].amount) and get explicit confirmation.
5. POST /checkout-sessions/{id}/complete with payment + signals and an Idempotency-Key. Build the AP2 payment proof first — see ap2-payment-mandate.
6. On success, status: completed + order { id, label, permalink_url } → hand to ucp-order-management.
7. POST /checkout-sessions/{id}/cancel to abandon.

Edge cases & failure modes / 边界与失败

• PUT drops fields → forgetting to resend a field deletes it; always send the full object.
• Total changed before complete → re-confirm; an AP2 mandate is bound to a specific amount.
• requires_escalation → needs buyer input outside the API; escalate, don't loop.
• Duplicate complete → same Idempotency-Key returns the same order, never double-charges.
• unrecoverable message → stop; the session can't reach ready_for_complete.
• Inventory lost at complete → server rejects; surface the line, re-cart.

Worked example / 示例

2 × sku_8821, ship-to DE, Acme account linked.

1. POST /checkout-sessions {line_items:[{item:{id:"sku_8821"},quantity:2}]} → cs_01H…, status:incomplete.
2. PUT /checkout-sessions/cs_01H… with full body incl. buyer, selected fulfillment option, Authorization: Bearer … → totals: subtotal 23800 + fulfillment 0 + tax 4522 = total 28322 EUR, status:ready_for_complete.
3. Show €283.22 → user confirms → build PaymentMandate bound to 28322.
4. POST /checkout-sessions/cs_01H…/complete (+Idempotency-Key) → status:completed, order.id=ord_77Q….

References / 参考

• UCP HTTP/REST binding: https://ucp.dev/specification/checkout-rest/
• Native checkout guide: https://developers.google.com/merchant/ucp/guides/checkout/native
• Schemas: https://ucp.dev/schemas/ · Payment proof: ap2-payment-mandate