Fulfillment 履约扩展

基本信息

  • Capability Name：dev.ucp.shopping.fulfillment
  • Version：2026-01-11
  • 官方规范：fulfillment.md

概述

Fulfillment 扩展允许商家声明支持物理商品履约（配送、自提等）。

此扩展在 Checkout 中添加 fulfillment 字段，包含：

  • methods[] — 适用于购物车项目的履约方式（配送、自提等）
    • line_item_ids — 此方式履约哪些项目
    • destinations[] — 履约到哪里（地址、门店位置）
    • groups[] — 商家生成的包裹，每个都有可选择的 options[]
  • available_methods[] — 每个项目的库存可用性（可选）

心智模型 

methods[0] 配送
    line_item_ids: 👕👖
    selected_destination_id = destinations[0].id → 123 Fake St
    groups[0] → 📦👕👖
        selected_option_id = options[0].id → Standard $5
        options[1] → Express $10

methods[1] 门店自提
    line_item_ids: 👞
    selected_destination_id = destinations[0].id → Uptown Store
    groups[0] → 📦👞
        selected_option_id = options[0].id → In-Store Pickup
        options[1] → Curbside Pickup

Schema 结构

当此能力激活时，结账会扩展 fulfillment 对象。

履约方法响应

字段类型必填描述
idstring是方法唯一标识符
typestring是方法类型（shipping、pickup等）
line_item_idsstring[]是此方法履约的行项目ID
selected_destination_idstring否选中的目的地ID
destinationsarray否目的地列表
groupsarray是履约组（包裹）

履约选项响应

字段类型必填描述
idstring是选项唯一标识符
titlestring是选项标题
descriptionstring否选项描述
totalsarray是价格总计

渲染

履约选项设计为方法无关的渲染。平台无需理解具体方法类型（配送、自提等）即可有意义地呈现选项。

商家职责

对于 options[].title：

  • 必须 区分此选项与其兄弟选项
  • 应该 包括方式和速度（如 “Express Shipping”、“Curbside Pickup”）
  • 必须 在没有 description 时足以让买家决策

对于 options[].description：

  • 不得 重复 title 或 total — 仅提供补充上下文
  • 应该 包括时间、承运商或其他决策相关细节
  • 应该 是完整短语（如 “12月12-15日通过USPS送达”）

平台职责

平台应该 将履约视为通用的可渲染结构：

  • 使用 title、description 和 total 将每个选项渲染为卡片
  • 按商家提供的顺序呈现选项
  • 呈现所有返回的方法 — 方法选择是买家决策

配置

商家和平台在 Profile 中声明履约约束。

平台 Profile

平台使用 platform_config 声明其渲染能力：

{
  "name": "dev.ucp.shopping.fulfillment",
  "version": "2026-01-11",
  "config": {
    "supports_multi_group": true
  }
}

商家 Profile

商家使用 merchant_config 声明支持的履约配置：

{
  "capabilities": [{
    "name": "dev.ucp.shopping.fulfillment",
    "version": "2026-01-11",
    "config": {
      "allows_multi_destination": {
        "shipping": true
      },
      "allows_method_combinations": [["shipping", "pickup"]]
    }
  }]
}

示例

基本 

{
  "fulfillment": {
    "methods": [
      {
        "id": "method_1",
        "type": "shipping",
        "line_item_ids": ["shirt", "pants"],
        "selected_destination_id": "dest_1",
        "destinations": [
          {
            "id": "dest_1",
            "street_address": "123 Main St",
            "address_locality": "Springfield",
            "address_region": "IL",
            "postal_code": "62701",
            "address_country": "US"
          }
        ],
        "groups": [
          {
            "id": "package_1",
            "line_item_ids": ["shirt", "pants"],
            "selected_option_id": "standard",
            "options": [
              {
                "id": "standard",
                "title": "Standard Shipping",
                "description": "Arrives Dec 12-15 via USPS",
                "totals": [{"type": "total", "amount": 500}]
              },
              {
                "id": "express",
                "title": "Express Shipping",
                "description": "Arrives Dec 10-11 via FedEx",
                "totals": [{"type": "total", "amount": 1000}]
              }
            ]
          }
        ]
      }
    ]
  }
}