变更商品订阅

API文档最后更新: 2026-09-21

6.5 变更商品订阅

  • 请求方式：POST

  • 请求地址：/goods/subscriptions

批量订阅：

{
  "action": "subscribe",
  "productRefs": [1001]
}

批量取消：

{
  "action": "unsubscribe",
  "productRefs": [
    1001,
    1002
  ]
}

清空全部订阅：

{
  "action": "clearAll"
}

subscribe 和 unsubscribe 一次最多提交 100 个 productRef。clearAll 不能同时提交 productRefs，它会删除当前账户的全部商品订阅。平台会逐个商品检查权限并返回哪些成功、哪些失败；clearAll 会返回实际删除了多少个订阅。

请求字段：

字段

JSON 类型

必填

含义

action

string

是

subscribe 订阅；unsubscribe 取消订阅；clearAll 清空全部订阅

productRefs

integer[]

订阅或取消时是

要处理的商品编号数组，最多 100 个；clearAll 时不能提交

返回字段：

字段

JSON 类型

必填

含义

code

integer

是

固定为 0，表示请求成功

message

string

是

本次请求的处理说明

data

object

是

本次处理结果

data.acceptedCount

integer

是

处理成功的商品数量

data.rejectedCount

integer

是

处理失败的商品数量

data.items

object[]

是

每个商品的处理结果；clearAll 时可以为空数组

data.items[].productRef

integer

是

商品编号

data.items[].accepted

boolean

是

true 处理成功；false 处理失败

data.items[].code

string 或 null

否

失败原因码；成功时为 null

data.items[].message

string 或 null

否

失败原因说明；成功时为 null

requestId

string

是

本次请求编号，排查问题时提供给平台

返回示例（对应上面的订阅商品 1001 请求）：

{
  "code": 0,
  "message": "success",
  "data": {
    "acceptedCount": 1,
    "rejectedCount": 0,
    "items": [
      {
        "productRef": 1001,
        "accepted": true,
        "code": null,
        "message": null
      }
    ]
  },
  "requestId": "req_01K0EXAMPLE"
}

订阅和推送规则：

  • 单个商品处理失败时，data.items[].code 只会返回 INVALID_ARGUMENT（商品编号无效或重复）或 SUBSCRIPTION_NOT_ALLOWED（当前账户不能订阅该商品）；同一批次中的其他合法商品仍会继续处理。

  • Webhook 默认启用，不设置事件开关。账户已经保存有效的默认回调地址时，订阅成功后会推送一次商品当前完整数据；没有回调地址时只保存订阅。

  • 后续只在商品价格、库存、是否可售、规格列表或下单模板版本变化时推送。

  • 未订阅或已经主动取消订阅的商品不会推送。

  • 每个订阅有效 90 天。再次执行 subscribe，或者成功创建该商品订单，都会从当天起重新计算 90 天；成功订单会在没有订阅时自动创建订阅。

  • 查询目录、查询详情、查询下单模板、商品自身变化和 Webhook 投递成功都不会续期。到期后该商品立即表现为 unsubscribed 并停止生成新的 product.changed；平台不会物理删除过期记录。

  • 第三方可以根据 subscriptionExpiresAt 在到期前再次执行 subscribe。自动到期不会额外发送 Webhook。

  • 一条 product.changed 按既定三次尝试仍未收到 HTTP 200 + OK 时，平台会取消该商品订阅；之后需要重新执行 subscribe 或成功创建该商品的新订单才能恢复。订单、卡密和售后 Webhook 投递失败不会取消商品订阅。

  • 商户停止供应或商品永久下架时，会最后推送一次 availability: unavailable。

  • 同一商品短时间内连续变化时，平台可以合并成一次完整商品数据。商品推送不保证到达顺序；需要确认当前价格、库存或状态时，重新查询商品列表或详情。

上一篇下一篇