抖音开放平台Logo
控制台

更新主播发券库存上限

更新时间 2024-07-24 02:58:49
收藏
我的收藏

接口说明

该接口用于更新主播发券的库存上限。券模板首次授权和初始化主播的发送数量需要调用 主播发券权限配置 接口。

使用限制

  • 只有当主播与券模板存在绑定关系时，才能用本接口更新主播发券的库存上限。
  • 单个主播的券库存发放上限，不得超过券模板库存。
  • 券模板处于过期、删除状态的情况下，不能调整主播发券库存上限。
  • 券模板-主播发放上限-发放计划的三者之间的库存关系，可查看文档 「小程序券」组件接入指南。
  • 只支持追加库存，仅支持减少库存。

基本信息

名称描述
HTTP URL
https://open.douyin.com/api/promotion/v1/coupon/update_talent_coupon_stock/
HTTP Method
POST
Scope
promotion.coupon.admin

请求头

名称字段类型是否必填示例描述
access-tokenString是clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1KcxFnZ
调用https://open.douyin.com/oauth/client_token/生成的token
content-typeString是application/json
固定值"application/json"

请求参数

Body

名称字段类型是否必填示例描述
account_typeInt32是1

账号类型，1：talent_account，2：open_id

actionString是increase

增减动作（暂不支持减少）

增加：increase

app_idString是ttec789ac573xxxxxx01

小程序appid

coupon_meta_idString是702345xxxxxxx

已创建的抖音开放平台券模板id，通过/api/promotion/v2/coupon/create_coupon_meta/接口返回的coupon_meta_id字段获取

numberInt64是20

在当前基础上期望增减的库存上限数，与action配合使用，需大于0。例如action传increase、number传20时表示将主播发券库存在当前的基础上增加20。

unique_keyString是20230418152200abcd

幂等唯一键，对于重复的unique_key，本接口会返回上一次操作成功的结果，不会调整库存。

调用方对于失败重试的请求使用同一个unique_key，避免多次调整库存上限；对于不同的请求使用不同的unique_key

award_numberInt64否20

分配给主播奖励券的库存数，仅券模板玩法含奖励券时必填

open_idString否Cv4PoJXaTPn63rNu

用户open_id，account_type为2时必填。该字段通过 /api/apps/v2/jscode2session 接口返回的 openid 字段获取

talent_accountString否7932234

主播抖音号，account_type为1时必填。该字段通过查看主播个人主页获得

请求示例

curl --location --request POST 'https://open.douyin.com/api/promotion/v1/coupon/update_talent_coupon_stock' \
--header 'access-token: clt.xxx' \
--header 'Content-Type: application/json' \
--data-raw '{
    "account_type":1,
    "talent_account":"54130000582",
    "app_id":"ttcfdbbxxxxx",
    "coupon_meta_id":"7223221208xxxx",
    "action":"increase",
    "number":20,
    "unique_key":"20230418152200abcd"
}'

响应参数

Body

名称字段类型是否必填示例描述
err_msgString是

err_no非0时对应的错误信息文案提示，成功时为空字符串

err_noInt32是0

0表示成功

log_idString是202008121419360101980821035705926A

标识请求的唯一id

响应示例

正常响应示例

{
  "err_no": 0,
  "err_msg": "",
  "log_id": "202008121419360101980821035705926A"
}

异常响应示例

{
  "err_msg": "主播发券配置不存在",
  "err_no": 29005025,
  "log_id": "202304181452428BAD8F6FDE34EEB829AD"
}

错误码

http状态码错误码错误码描述排查建议
2000
success
接口成功，无需排查
20029005025
主播发券配置不存在
确认是否有调用主播发券权限配置 接口绑定主播与券模板的关系
20028001007
参数不合法
检查请求参数是否填写正常
20029005071
No Permission Operate
没有权限调用该接口，检查申请access-token的client_key是否与app_id一致
20028001005
系统内部错误，请重试
请求重试，若依然无解请向平台提交反馈
20029005023
不可使用的券模板
券模板已过期/删除，不能进行对应操作
20029005024
库存变更超过当前券模板最大库存
主播当前库存+期望增加的库存数已超过券模板库存上限，不能进行对应操作