Ucp fulfillment

UCP Fulfillment

中文摘要：在 UCP checkout session 上设置/解析履约——填目的地址、对 line items 分组、从商家 返回的选项里选配送/自提方案,用真实的 fulfillment.methods / groups / options 字段。需要确定 配送方式并把运费体现到 totals 时用。对应能力 dev.ucp.shopping.fulfillment。

When to use / 何时使用

• The user provides a shipping address or chooses pickup.
• You need the merchant's available shipping options + costs before showing a total.
• Different line items need different fulfillment (split shipments, pickup-only items).

Fulfillment is part of the checkout session, set via PUT /checkout-sessions/{id}. 履约是 checkout session 的一部分,通过 PUT 设置。

UCP mapping / UCP 映射

Capability dev.ucp.shopping.fulfillment. The fulfillment object lives on the checkout session. You send a destination + selections; the merchant returns options with prices, which appear in session totals as type: "fulfillment".

Fields / 字段 (verbatim)

Request — fulfillment.methods[] (what you send):

"fulfillment": {
  "methods": [
    {
      "type": "shipping",                    // e.g. "shipping" | "pickup"
      "line_item_ids": ["li_1"],
      "destinations": [
        { "street_address": "1 Hauptstr", "address_locality": "Berlin",
          "address_region": "BE", "postal_code": "10115", "address_country": "DE" }
      ],
      "groups": [ { "id": "grp_1", "selected_option_id": "opt_std" } ]
    }
  ]
}

Response — fulfillment.methods[] (what the merchant returns):

"fulfillment": {
  "methods": [
    {
      "id": "fm_1",
      "type": "shipping",
      "line_item_ids": ["li_1"],
      "selected_destination_id": "dest_1",
      "destinations": [ { "id": "dest_1", "address_country": "DE", "...": "…" } ],
      "groups": [
        {
          "id": "grp_1",
          "line_item_ids": ["li_1"],
          "selected_option_id": "opt_std",
          "options": [
            { "id": "opt_std",  "title": "Standard", "description": "5 days",
              "totals": [ { "type": "fulfillment", "amount": 0 } ] },
            { "id": "opt_exp",  "title": "Express",  "description": "1–2 days",
              "totals": [ { "type": "fulfillment", "amount": 990 } ] }
          ]
        }
      ]
    }
  ]
}

Workflow / 工作流

1. Send a destination + line_item_ids per method via PUT (remember: full-replace, keep line_items/buyer too).
2. Read returned groups[].options[] — each has id, title, description, and a totals entry of type: "fulfillment" (the price).
3. Present options + costs to the user; let them choose.
4. Select by setting groups[].selected_option_id and re-PUT.
5. Confirm the new session totals (the fulfillment line updated) before checkout completes.

Edge cases & failure modes / 边界与失败

• Address unsupported / not shippable → merchant returns a recoverable message; fix or warn.
• Mixed fulfillment → multiple methods / groups; some items pickup-only — handle per group.
• Split shipments → one group can map to a subset of line_item_ids; don't assume one shipment.
• Forgot to resend on PUT → fulfillment selection lost (full-replace semantics).
• Option went away on re-price → re-read options; never keep a stale selected_option_id.

Worked example / 示例

Ship 2×GTX to Berlin; user wants the cheapest option.

1. PUT with fulfillment.methods[0].destinations=[{…DE…}], line_item_ids:["li_1"].
2. Merchant returns groups[0].options = [opt_std €0/5d, opt_exp €9.90/1–2d].
3. User picks Standard → set selected_option_id:"opt_std", re-PUT.
4. totals now shows fulfillment: 0; total recomputed. Proceed to complete.

References / 参考

• UCP checkout REST (fulfillment shapes): https://ucp.dev/specification/checkout-rest/
• Native checkout guide: https://developers.google.com/merchant/ucp/guides/checkout/native
• Parent: ucp-checkout-session