用户撤销核销券
收藏接口说明
- 使用场景：用户退款、取消预约、取消订单等需要撤回优惠券核销态的场景。
- 用户撤销核销券后，将券状态同步到开放平台，抖音卡包中券状态由“已核销”改为“待核销”。
使用限制
接口会校验open_id对应的用户在24小时内是否登录过小程序，确保开发者撤销核销的真实性。
基本信息
| 名称 | 描述 |
|---|---|
| HTTP URL | https://open.douyin.com/api/promotion/v1/coupon/batch_rollback_consume_coupon/ |
| HTTP Method | POST |
| Scope | promotion.coupon.admin |
请求参数
请求头
access-token必填String
示例：clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1KcxFnZ
content-type必填String
示例：application/json
固定值"application/json"
Body展开全部子属性
app_id必填String
示例：ttec789ac573xxxxxx01
开发者 小程序appid
consume_out_no必填String
示例：123xxxxxxx
开发者核销单号（开发者内部系统的券核销记录自增id或uuid），由开发者系统生成，平台留底，用于后续产生撤销核销，平台定位之前的核销记录
coupon_id_list必填List
示例：["702345xxxxxx","702345xxxxxx"]
抖音开放平台券id列表（开发者通过平台的领券回调获得券id），一次最多核销10张券
展开子属性
open_id必填String
示例：ba253642-0590-40bc-xxx
核销用户在小程序的open_id。该字段通过 /api/apps/v2/jscode2session 接口返回的 openid 字段获取
rollback_consume_out_no必填String
示例：456xxxxxxx
开发者撤销核销单号（开发者内部系统的撤销核销记录自增id或uuid），由开发者系统生成，平台留底
rollback_consume_time必填Int64
示例：1676966474
券撤销核销时间，单位秒
请求示例
curl --location --request POST 'https://open.douyin.com/api/promotion/v1/coupon/batch_rollback_consume_coupon' \ --header 'Content-Type: application/json' \ --header 'access-token: clt.xxx' \ --data-raw '{ "open_id":"ba253642-0590-40bc-xxx", "consume_out_no": "123xxxxxxx", "rollback_consume_out_no": "456xxxxxxx", "app_id": "ttec789ac573xxxxxx01", "coupon_id_list": [ "702345xxxxxx", "702345xxxxxx" ], "order_id": 614167279916, "rollback_consume_time": 1676966474 }'
响应参数
Body展开全部子属性
data必填Struct
展开子属性
err_msg必填String
示例："access_token无效"
错误描述
err_no必填Int32
示例：28001003
错误码
log_id必填String
示例："202405291440576E078D8757B9"
日志id
响应示例
正常响应示例异常响应示例
{ "err_no": 0, "err_msg": "", "log_id": "202008121419360101980821035705926A", "data": { "results": [ { "coupon_id": "702345xxxxxx", "err_no": 0, "err_msg": "success" } ] } }
错误码
| HTTP 状态码 | 错误码 | 错误码描述 | 排查建议 |
|---|---|---|---|
| 200 | 28001005 | 系统内部错误，请重试 | 请求重试，若依然无解请向平台提交反馈 |
| 200 | 28001003 | access_token无效 | 重新请求生成access_token |
| 200 | 28001008 | access_token过期,请刷新或重新授权 | 重新请求生成access_token |
| 200 | 28001006 | 网络调用错误，请重试 | 重试即可 |
| 200 | 28001007 | 参数不合法 | 根据错误信息检查请求参数是否填写正常 |
| 200 | 29005028 | 用户24h内未登录小程序 | 撤销核销同步太晚，超过1天 |
| 200 | 29005043 | order_id为空 | 满减券和立减券，必须传订单id |
| 200 | 29005064 | 更新券记录状态失败 | 重试 |
| 200 | 29005066 | 重复撤销核销 | 该券已经提交过撤销核销记录，无需再提交 |
