开发者文档 / 联盟订单
联盟订单查询
按创作者查询联盟带货订单,支持时间范围与游标分页。
POST
/v1/creator/tiktokshop/affiliateOrders/search- 鉴权:
- 请求头 x-api-key: <YOUR_API_KEY>;密钥仅保存在服务端。
- 成功判断:
- HTTP 2xx 且响应 code=0;异步任务还需查询最终状态。
请求字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
id | integer | 是 | 创作者账号 ID(不是店铺 ID) |
startTime | string | 是 | 开始时间,格式 YYYY-MM-DD |
endTime | string | 是 | 结束时间,格式 YYYY-MM-DD,按当天 23:59:59 计 |
pageToken | string | 否 | 分页游标,首页不传 |
pageSize | integer | 否 | 每页条数 1-100,不传默认 20;越界由后端参数校验拦截,不会请求平台 |
这是创作者维度接口:`id` 传创作者账号 ID,服务端用该创作者的 access_token 调 TikTok Shop `/affiliate_creator/202410/orders/search`,不是店铺 ID。
时间范围:`startTime` / `endTime` 传 `YYYY-MM-DD`,后端按「起始日 00:00:00」到「结束日次日 00:00:00」换算成秒,结束日当天的订单也会返回。
分页:首页不传 `pageToken`;用返回的 `nextPageToken` 继续翻页,返回空字符串表示最后一页。翻页时须沿用同一组 `startTime` / `endTime`。`totalCount` 与 `pageSize` 都按 SKU 行计数,一个订单可能包含多个 SKU,所以返回的订单对象数量可能少于 `pageSize`。
金额字段都是「本地化字符串 + 币种」,不要直接转数字参与计算;佣金率以万分之一为单位,`3000` 表示 30%。
`isr`、`iva` 仅墨西哥创作者返回,`pit` 仅越南、泰国、菲律宾、印尼创作者返回,其他地区可能不出现这些字段。
请求体
{
"id": 12345,
"startTime": "2026-11-01",
"endTime": "2026-11-16",
"pageSize": 20
}成功响应
{
"code": 0,
"message": "success",
"data": {
"orders": [
{
"id": "789078671231123124",
"createTime": 1685548800,
"deliveryTime": 1685548800,
"status": "SETTLED",
"skus": [
{
"id": "1729793769377925388",
"campaignId": "73661290629",
"productName": "black_suit",
"productId": "1729793769377859852",
"price": {
"amount": "Rp9.900",
"currency": "IDR"
},
"shopName": "TestCase idl2l",
"contentType": "VIDEO",
"contentId": "7493990579714164574",
"quantity": 2,
"commissionRate": 3000,
"commissionModel": "Fixed commission",
"estimatedCommission": {
"amount": "Rp1.980",
"currency": "IDR"
},
"actualCommission": {
"amount": "Rp1.900",
"currency": "IDR"
},
"returnedQuantity": 0,
"refundedQuantity": 0,
"traceInfo": {
"id": "15678763",
"type": "SPECIFIC"
},
"lastUpdateTime": 1685548800,
"isCarousel": false
}
]
}
],
"nextPageToken": "",
"totalCount": 1
},
"timestamp": 1794463889000
}响应与错误
主要响应字段来自接口规范;完整层级、联合类型和校验规则见 JSON Schema。必填指字段所在对象中的约束。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
code | integer | 是 | 0 表示成功 |
message | string | 是 | — |
data | object | 是 | — |
data.orders | object[] | 否 | 命中的订单列表。 |
data.orders[].id | string | 否 | 订单标识 |
data.orders[].createTime | integer | 否 | 下单时间,Unix 秒 |
data.orders[].deliveryTime | integer | 否 | 送达时间,Unix 秒 |
data.orders[].status | string | 否 | 订单状态:UNSPECIFIED(尚未确定)、AWAITING PAYMENT(未支付,只有预估佣金)、To-SETTLE(待结算,只有预估佣金)、SETTLED(佣金已结算)、REFUNDED(已退货/退款/取消,不结算佣金)、FROZEN(疑似欺诈暂时冻结,处理完成后解冻) |
data.orders[].skus | object[] | 否 | 订单包含的 SKU 列表。 |
data.orders[].skus[].id | string | 否 | SKU 标识 |
data.orders[].skus[].campaignId | string | 否 | 该订单关联的活动 ID |
data.orders[].skus[].openCollaborationId | string | 否 | 公开合作 ID |
data.orders[].skus[].targetCollaborationId | string | 否 | 定向合作 ID |
data.orders[].skus[].productName | string | 否 | TikTok Shop 商品名称 |
data.orders[].skus[].productId | string | 否 | 商品 ID |
data.orders[].skus[].price | object | 否 | 本地化金额:amount 是带符号和千分位的字符串,不要直接转数字参与计算。 |
data.orders[].skus[].shopName | string | 否 | 商品所属店铺名称 |
data.orders[].skus[].contentType | string | 否 | 成交内容形式:SHOP、VIDEO、LIVE、PRE_LIVE、PROMOTION_PAGE 或 LINKSHARE |
data.orders[].skus[].contentId | string | 否 | 成交内容 ID |
data.orders[].skus[].quantity | integer | 否 | 该 SKU 数量,含退款数量 |
data.orders[].skus[].commissionRate | integer | 否 | 总佣金率,万分之一为单位:3000 = 30%;等于标准、店铺广告、奖励与分成各项佣金率之和 |
data.orders[].skus[].commissionTierSetting | string | 否 | 阶梯佣金模式下卖家设置的各档佣金率,例如 3.0 OR 5.0 |
data.orders[].skus[].commissionModel | string | 否 | 佣金模式:Fixed commission 或 Tiered commission |
data.orders[].skus[].commissionBonusRate | integer | 否 | 奖励佣金率,万分之一为单位 |
data.orders[].skus[].estimatedCommissionBase | object | 否 | 本地化金额:amount 是带符号和千分位的字符串,不要直接转数字参与计算。 |
data.orders[].skus[].standardCommissionRate | integer | 否 | 标准联盟佣金率,万分之一为单位 |
data.orders[].skus[].shopAdsCommissionRate | integer | 否 | 店铺广告佣金率,万分之一为单位 |
data.orders[].skus[].estimatedBonusCommission | object | 否 | 本地化金额:amount 是带符号和千分位的字符串,不要直接转数字参与计算。 |
data.orders[].skus[].estimatedStandardCommission | object | 否 | 本地化金额:amount 是带符号和千分位的字符串,不要直接转数字参与计算。 |
data.orders[].skus[].estimatedShopAdsCommission | object | 否 | 本地化金额:amount 是带符号和千分位的字符串,不要直接转数字参与计算。 |
data.orders[].skus[].estimatedCommission | object | 否 | 本地化金额:amount 是带符号和千分位的字符串,不要直接转数字参与计算。 |
data.orders[].skus[].actualCommission | object | 否 | 本地化金额:amount 是带符号和千分位的字符串,不要直接转数字参与计算。 |
data.orders[].skus[].actualBonusCommission | object | 否 | 本地化金额:amount 是带符号和千分位的字符串,不要直接转数字参与计算。 |
data.orders[].skus[].actualCommissionBase | object | 否 | 本地化金额:amount 是带符号和千分位的字符串,不要直接转数字参与计算。 |
data.orders[].skus[].actualStandardCommission | object | 否 | 本地化金额:amount 是带符号和千分位的字符串,不要直接转数字参与计算。 |
data.orders[].skus[].actualShopAdsCommission | object | 否 | 本地化金额:amount 是带符号和千分位的字符串,不要直接转数字参与计算。 |
data.orders[].skus[].returnedQuantity | integer | 否 | 该 SKU 退货数量 |
data.orders[].skus[].refundedQuantity | integer | 否 | 该 SKU 退款数量 |
data.orders[].skus[].tag | string | 否 | 自定义标记,供调用方跟踪用 |
data.orders[].skus[].creatorCommissionRewardRate | integer | 否 | 联盟伙伴分配给达人的佣金奖励率,万分之一为单位:1000 = 10% |
data.orders[].skus[].estimatedCreatorCommissionRewardFee | object | 否 | 本地化金额:amount 是带符号和千分位的字符串,不要直接转数字参与计算。 |
data.orders[].skus[].actualCreatorCommissionRewardFee | object | 否 | 本地化金额:amount 是带符号和千分位的字符串,不要直接转数字参与计算。 |
data.orders[].skus[].isr | object | 否 | 本地化金额:amount 是带符号和千分位的字符串,不要直接转数字参与计算。 |
data.orders[].skus[].iva | object | 否 | 本地化金额:amount 是带符号和千分位的字符串,不要直接转数字参与计算。 |
data.orders[].skus[].pit | object | 否 | 本地化金额:amount 是带符号和千分位的字符串,不要直接转数字参与计算。 |
data.orders[].skus[].sharedWithPartner | object | 否 | 本地化金额:amount 是带符号和千分位的字符串,不要直接转数字参与计算。 |
data.orders[].skus[].traceInfo | object | 否 | 归因信息。 |
data.orders[].skus[].lastUpdateTime | integer | 否 | 该记录最后更新时间,Unix 秒 |
data.orders[].skus[].isCarousel | boolean | 否 | 订单是否归因于轮播内容;轮播内容可能涉及佣金率折扣 |
data.nextPageToken | string | 否 | 下一页游标,空字符串表示最后一页 |
data.totalCount | integer | 否 | 命中的 SKU 订单总行数;一个订单可能包含多个 SKU,所以订单对象数量可能少于 pageSize |
timestamp | integer | 否 | — |
参数、权限或授权错误需先修正。创建发布或生成任务超时后先查询已有任务,避免重复创建;不要因轮询中断而重复提交。
最后更新 · 2026-11-16