Ucp order management

UCP Order Management

中文摘要：成单后通过 dev.ucp.shopping.order 能力管理订单——产生/消费必需的订单 webhook 事件(created/shipped/delivered),用 tracking number 跟踪履约事件,用真实字段处理调整 (cancellation/return/refund)。回答"订单到哪了"或处理售后变更时用。

When to use / 何时使用

• A webhook order event arrives and you must reconcile order state.
• The user asks about an existing order (status, tracking, ETA).
• The user wants a cancellation / return / refund.

Begins from the order.id returned by ucp-checkout-session completion.

UCP mapping / UCP 映射

Capability dev.ucp.shopping.order — webhook-based order lifecycle. On Google's integration, the merchant POSTs events to Google's ingestion endpoint:

POST https://shoppingdataintegration.googleapis.com/v1/webhooks/partners/{PARTNER_ID}/events/order?key={API_KEY}
# auth: X-Goog-Api-Key: {API_KEY}  (or ?key=)  + signature headers
#       Request-Signature / Content-Digest / Signature-Input / Signature (version-dependent)

Three mandatory event types: Order created, Order shipped, Order delivered.

Fields / 字段 (verbatim)

Order object:

{
  "id": "ord_77Q…",
  "checkout_id": "cs_01H…",
  "created_time": "2026-06-03T12:00:00Z",
  "currency": "EUR",
  "line_items": [
    {
      "id": "li_1",
      "item": { "id": "sku_8821", "title": "Trail Runner GTX", "price": 11900 },
      "quantity": { "total": 2, "fulfilled": 0, "original": 2 },
      "totals": [ { "type": "subtotal", "amount": 23800 } ],
      "status": "confirmed"
    }
  ],
  "totals": [ { "type": "total", "amount": 28322 } ],
  "fulfillment": {
    "events": [
      { "id": "fe_1", "occurred_at": "2026-06-04T09:10:00Z", "type": "shipped",
        "line_items": ["li_1"], "tracking_number": "DHL-XYZ",
        "tracking_url": "https://dhl…/DHL-XYZ", "description": "Shipped via DHL" }
    ]
  },
  "permalink_url": "https://merchant.example/orders/ord_77Q…"
}

Adjustments — type: cancellation | return | refund:

{ "id": "adj_1", "type": "refund", "description": "Returned 1 pair",
  "line_items": ["li_1"], "occurred_at": "2026-06-09T10:00:00Z", "status": "completed" }

Workflow / 工作流

1. Consume webhooks: verify signature/source, dedupe by event id, apply in occurred_at order, update the order's fulfillment.events + line quantity.fulfilled. Treat events as source of truth over cached state.
2. Answer status questions: report the latest meaningful fulfillment.events entry + tracking_number/tracking_url; link permalink_url.
3. Track partial fulfillment via quantity { total, fulfilled, original }; don't report "delivered" until all units are.
4. Adjustments: for cancel/return/refund, submit an adjustment with type + line_items
   • reason; reflect the returned status back to the user.
5. Reconcile with a re-fetch if a webhook may have been missed (idempotent).

Edge cases & failure modes / 边界与失败

• Out-of-order / duplicate webhooks → dedupe by id, order by occurred_at, idempotent apply.
• Missed webhook → re-fetch; never trust stale cache.
• Cancel after shipped → ineligible; convert to a return adjustment instead.
• Partial / split fulfillment → per-line_items events; track quantity.fulfilled.
• Refund money → only report what the merchant returns (adjustment.status); never fabricate.

Worked example / 示例

"Where's my Acme order?" → then "cancel one pair."

1. Latest fulfillment.events = type:shipped, tracking_number:DHL-XYZ → report + ETA.
2. Cancel-one but already shipped → ineligible → submit adjustment {type:"return", line_items:["li_1"]}.
3. On the refund adjustment reaching status:"completed", update totals + confirm amount.

References / 参考

• UCP order lifecycle (webhooks): https://developers.google.com/merchant/ucp/guides/orders
• UCP order capability: https://ucp.dev/specification/
• Starts from: ucp-checkout-session