Square Checkout API初始POST请求ITEM参数取值澄清问询

我之前也碰到过Square官方文档这里的模糊表述问题，现在给你明确拆解下向https://connect.squareup.com/v2/locations/{{LOCATION_ID}}/checkouts发起POST请求时，ITEMS参数的具体有效值要求：

核心结构规则 #

ITEMS是一个数组，每个元素对应一个商品条目，必须满足以下二选一的结构：

1. 自定义非目录商品

当你要售卖Square商品目录中没有的商品时，每个条目必须包含：

• name：字符串类型，商品名称（必填）
• quantity：字符串格式的正整数（必填，注意是字符串，不能直接传数字）
• base_price_money：定义商品价格的对象，包含两个必填字段：
  • amount：非负整数，代表最小货币单位（比如1美元对应100，1欧元对应100）
  • currency：字符串类型，符合ISO 4217标准的货币代码（比如USD、EUR）

2. Square目录中的已有商品

当你售卖的是Square后台商品目录里的商品时，每个条目必须包含：

• name：字符串类型，商品名称（必填）
• quantity：字符串格式的正整数（必填）
• catalog_object_id：字符串类型，对应Square商品目录中该商品（或商品变体）的ID（必填）

可选补充字段 #

除了必填字段外，你还可以添加以下可选字段来丰富商品信息：

• note：字符串类型，商品备注（比如定制要求、特殊说明）
• variation_name：字符串类型，商品变体名称（比如尺寸、颜色）

完整请求示例 #

{
  "idempotency_key": "your-unique-request-id",
  "order": {
    "items": [
      // 自定义商品示例
      {
        "name": "手工陶瓷马克杯",
        "quantity": "1",
        "base_price_money": {
          "amount": 2500,
          "currency": "USD"
        },
        "note": "蓝色釉面，手工制作"
      },
      // 目录商品示例
      {
        "name": "有机棉T恤",
        "quantity": "2",
        "catalog_object_id": "sq0idp-xxxxxxxxx-xxxxxxxxx",
        "variation_name": "M码"
      }
    ]
  },
  "checkout_options": {
    "redirect_url": "https://your-domain.com/checkout-confirmation"
  }
}

关键注意事项 #

• 不能同时在同一个商品条目中提供base_price_money和catalog_object_id，API会返回参数错误
• quantity必须是字符串（即使是数字也要用引号包裹，比如"1"而不是1）
• 订单的items数组至少要有一个条目，不能为空
• base_price_money.amount不能为负数，必须是最小货币单位的整数

内容的提问来源于stack exchange，提问作者user2355051