开发者文档 / 带货内容发布

创作者TTS-添加橱窗商品

将 TikTok Shop 商品添加到创作者展示橱窗。可按商品 ID 批量添加，或通过单个商品链接添加。

POST/v1/creator/tiktokshop/product/addToShowcase

鉴权：: 请求头 x-api-key: <YOUR_API_KEY>；密钥仅保存在服务端。
成功判断：: HTTP 2xx 且响应 code=0；异步任务还需查询最终状态。

请求字段

字段	类型	必填	说明
`id`	`integer`	是	创作者账号 ID（creator account id）
`addType`	`PRODUCT_ID \| PRODUCT_LINK`	是	添加方式
`productIds`	`string[]`	条件	addType=PRODUCT_ID 时必填，1～20 个商品 ID
`productLink`	`string(uri)`	条件	addType=PRODUCT_LINK 时必填

所需 scope：creator.showcase.write、creator.video.write。

一次最多添加 20 个 productId。

业务 code=0 时仍需检查 data.errors；存在 errors 表示对应商品添加失败。

创作者授权失效时返回业务错误「授权过期，请重新授权」。

请求示例 · 按商品 ID 添加

{
  "id": 12345,
  "addType": "PRODUCT_ID",
  "productIds": [
    "1732280564607717841",
    "1732280564607717842"
  ]
}

请求示例 · 按商品链接添加

{
  "id": 12345,
  "addType": "PRODUCT_LINK",
  "productLink": "https://shop.tiktok.com/view/product/1732280564607717841"
}

响应示例 · 全部商品添加成功

{
  "code": 0,
  "data": {},
  "message": "success",
  "timestamp": 1786406400000
}

响应示例 · 部分商品添加失败

{
  "code": 0,
  "data": {
    "errors": [
      {
        "code": 16001001,
        "message": "Product is unavailable for this creator",
        "detail": {
          "productId": "1732280564607717842"
        }
      }
    ]
  },
  "message": "success",
  "timestamp": 1786406400000
}

响应示例 · 创作者授权过期

{
  "code": 40101,
  "data": {},
  "message": "授权过期，请重新授权",
  "timestamp": 1786406400000
}

响应与错误

主要响应字段来自接口规范；完整层级、联合类型和校验规则见 JSON Schema。必填指字段所在对象中的约束。

字段	类型	必填	说明
`code`	`integer`	是	业务状态码，0 表示请求已处理；仍需检查逐项结果。
`data`	`object`	是	—
`data.errors`	`object[]`	否	逐商品失败信息；全部添加成功时可能为空或省略。
`data.errors[].code`	`integer`	否	—
`data.errors[].message`	`string`	否	—
`data.errors[].detail`	`object`	否	—
`data.errors[].detail.productId`	`string`	否	添加失败的商品 ID。
`message`	`string`	是	—
`timestamp`	`integer`	是	Unix 时间戳，单位毫秒。

HTTP 400请求参数或请求体无效，请修正后重试。
HTTP 401API 密钥缺失或无效，请检查 x-api-key。
HTTP 403API 密钥没有此接口的调用权限。
HTTP 429请求过于频繁，请采用指数退避重试。
HTTP 500服务端发生错误；对于暂时性故障采用指数退避重试。

参数、权限或授权错误需先修正。创建发布或生成任务超时后先查询已有任务，避免重复创建；不要因轮询中断而重复提交。

最后更新 · 2026-09-29