用户撤销核销券__抖音开放平台

接口说明

使用场景：用户退款、取消预约、取消订单等需要撤回优惠券核销态的场景。
用户撤销核销券后，将券状态同步到开放平台，抖音卡包中券状态由“已核销”改为“待核销”。

使用限制

接口会校验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	调用https://open.douyin.com/oauth/client_token/生成的token
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	券撤销核销时间，单位秒
order_id	String	否	614167279916	抖音开放平台侧生成的订单号，立减券和满减券必填，权益券选填。来源于交易系统或担保支付：交易系统预下单回调、担保支付预下单接口

请求示例

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"
      }
    ]
  }
}

异常响应示例

{
  "err_no": 29005004,
  "err_msg": "券记录不存在",
  "log_id": "202008121419360101980821035705926A"
}

错误码

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	重复撤销核销	该券已经提交过撤销核销记录，无需再提交

用户撤销核销券在线调试

接口说明

使用限制

基本信息

请求头

请求参数

Body

请求示例

响应参数

Body

响应示例

正常响应示例

异常响应示例

错误码

用户撤销核销券