Square Connect API V2：商品税率设置及Upsert操作疑问

我来帮你梳理下这两个关于Square Connect API V2的问题，结合实际开发经验给你明确答案：

设置商品税率需要分两步走，核心是通过UpsertCatalogObject接口完成税率对象的准备和商品关联：

• 第一步：创建或获取目标税率对象
  如果还没有需要绑定的税率，先调用UpsertCatalogObject接口创建一个TAX类型的CatalogObject。示例请求体如下：

  {
    "idempotency_key": "your-unique-idempotency-key",
    "object": {
      "type": "TAX",
      "tax_data": {
        "name": "州销售税",
        "percentage": "7.25",
        "inclusion_type": "ADDITIVE",
        "applies_to_all": false
      }
    }
  }
  

  调用成功后会返回该税率的唯一id，请妥善保存。如果已经存在可用税率，直接通过ListCatalog或RetrieveCatalogObject接口获取对应ID即可。
• 第二步：将税率关联到指定商品
  再次调用UpsertCatalogObject接口，操作ITEM类型对象，在CatalogItem的tax_ids字段中传入目标税率的ID数组。示例请求体：

  {
    "idempotency_key": "another-unique-key",
    "object": {
      "type": "ITEM",
      "id": "target-item-id",
      "item_data": {
        "name": "你的商品名称",
        "tax_ids": ["your-tax-id"]
      }
    }
  }
  

  若需要绑定多个税率，只需在tax_ids数组中添加多个税率ID即可。

这个问题确实存在官方文档表述模糊的情况，我结合实际测试结果给你明确说明：

官方文档看似仅提及添加新税率，但实际upsert操作对商品的tax_ids字段是全量覆盖的逻辑。

具体行为细节：

• 执行商品upsert时，你传入的tax_ids数组会完全替换商品原有的税率关联列表，而非仅追加新税率。
• 举个实际场景：如果商品原本关联了tax_001和tax_002，你在upsert时传入的tax_ids是["tax_003"]，操作完成后商品只会关联tax_003，之前的tax_001和tax_002会被自动移除。
• 这种逻辑其实符合upsert（更新或插入）的常规全量更新设计，只是文档描述不够直白，容易造成误解。

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