商品变更推送

API文档最后更新: 2026-08-30

9.1 商品变更推送

平台使用 POST 发送 JSON。商品已经绑定 orderCallbackUrl 时发到该地址；没有绑定时，在该商品消息生成时读取当时的默认回调地址。同一条消息只发到一个固定地址，不会同时发两份。请求正文格式：

{
  "eventId": "product.changed:product:1001:1753776000",
  "eventType": "product.changed",
  "occurredAt": 1785216000,
  "productRef": 1001,
  "revision": 1753776000,
  "changedProperties": ["brand", "price", "remainingUnits", "purchaseSchemaRevision"],
  "productSnapshot": {
    "productRef": 1001,
    "catalogRef": 10,
    "brand": {
      "brandRef": 12,
      "name": "示例品牌",
      "imageUrl": "https://cdn.example.com/brands/example.png"
    },
    "availability": "available",
    "revision": 1753776000,
    "variants": [
      {
        "variantRef": 0,
        "title": "默认规格",
        "price": 100.00,
        "availability": "available",
        "inventoryType": "tracked",
        "remainingUnits": 37,
        "purchaseSchemaRevision": 1753776300
      }
    ]
  }
}

顶层字段：

字段	JSON 类型	必填	格式与含义
`eventId`	string	是	本次消息的唯一编号；第三方保存后用它判断消息是否已经处理过
`eventType`	string	是	固定为 `product.changed`
`occurredAt`	integer	是	消息产生时间，10 位 Unix 秒级时间戳
`productRef`	integer	是	商品编号
`revision`	integer	是	商品最后更新时间，10 位 Unix 秒级时间戳
`changedProperties`	string[]	是	变化提示：`availability` 表示商品或规格的可购买状态变化；`brand` 表示商品品牌关联变化；`variants` 表示规格新增、删除或名称变化；`price` 表示规格进货价格变化；`inventoryType` 表示规格库存类型变化；`remainingUnits` 表示单规格商品或多规格商品某个规格的可售库存数量变化；`purchaseSchemaRevision` 表示规格下单模板版本变化
`productSnapshot`	object	是	商品变化后的完整数据

productSnapshot 字段：

字段	JSON 类型	必填	格式与含义
`productRef`	integer	是	与顶层 `productRef` 相同
`catalogRef`	integer	是	分类编号
`brand`	object 或 null	否	当前商品品牌；商品未关联有效品牌时为 `null`
`brand.brandRef`	integer	品牌存在时是	品牌编号
`brand.name`	string	品牌存在时是	品牌名称
`brand.imageUrl`	string 或 null	品牌存在时是	品牌图片的公网 HTTPS 地址；没有图片时为 `null`
`availability`	string	是	`available` 或 `unavailable`
`revision`	integer	是	与顶层 `revision` 相同
`variants`	object[]	是	当前完整规格列表，至少一项；用整个数组更新第三方平台中的规格数据

productSnapshot.variants[] 字段：

字段	JSON 类型	必填	格式与含义
`variantRef`	integer	是	规格编号；单规格商品为 `0`
`title`	string	是	规格名称
`price`	number	是	当前接口账户购买该规格的进货价格，单位为人民币元，最多保留两位小数
`availability`	string	是	`available` 或 `unavailable`
`inventoryType`	string	是	`tracked`、`unlimited` 或 `undisclosed`
`remainingUnits`	integer 或 null	是	`tracked` 时为大于等于 0 的可售数量；`unlimited` 或 `undisclosed` 时为 `null`
`purchaseSchemaRevision`	integer	是	下单模板版本；值变化时重新获取模板

只有已经订阅且订阅没有到期的商品才会发送该消息。第三方可以直接用 productSnapshot 更新本地价格和库存，并检查下单模板版本是否变化。

changedProperties 中每个值的含义：

元素	含义	第三方处理方式
`availability`	商品整体或至少一个规格的可购买状态发生变化	读取 `productSnapshot.availability` 和各规格的 `availability`
`brand`	商品品牌关联发生变化	使用完整的 `productSnapshot.brand` 更新本地品牌；值为 `null` 时清除本地品牌关联
`variants`	规格结构发生变化，例如新增规格、删除规格或规格名称变化	使用完整的 `productSnapshot.variants` 更新本地规格
`price`	至少一个规格的进货价格发生变化	按 `variantRef` 更新各规格的 `price`
`inventoryType`	至少一个规格的库存类型发生变化	读取对应规格的 `inventoryType`；`tracked` 公开库存，`unlimited` 不限量，`undisclosed` 不公开库存
`remainingUnits`	单规格商品的可售库存数量，或多规格商品至少一个 `tracked` 规格的可售库存数量发生变化	单规格商品读取 `variantRef` 为数字 `0` 的唯一规格；多规格商品按 `variantRef` 更新 `remainingUnits`
`purchaseSchemaRevision`	至少一个规格的下单模板版本发生变化	对比各规格版本，版本与本地不同时重新调用 `GET /goods/tpl`

商品所属分类变化不会发送 product.changed，catalogRef 不会出现在 changedProperties 中。productSnapshot.catalogRef 只是完整商品数据中的当前分类编号。一次通知可以包含多个变化提示，但不会指出具体哪个规格变化，实际更新时应按 variantRef 对照或直接使用完整的 productSnapshot。

单规格商品也会在 productSnapshot.variants 中返回一项，variantRef 固定为数字 0。库存类型为 tracked 时，该项的 remainingUnits 就是单规格商品当前可售库存；库存类型为 unlimited 或 undisclosed 时为 null。

第三方把数据成功保存后，必须返回 HTTP 200 和纯文本 OK；正文忽略大小写，推荐使用 Content-Type: text/plain。详细规则见 9.5。