接口说明

开发者可通过此接口查询退款单的详情。适用场景举例：查询是否发起退款，查询退款单状态。

支持 refund_id 查询
支持 out_refund_no 查询
支持 order_id 查询，查询可能返回多条记录，返回的结果数限制50条

使用限制

接入前，请先查看接入前准备是否完成

基本信息

名称	描述
HTTP URL	https://open.douyin.com/api/trade_basic/v1/developer/refund_query/
HTTP Method	POST
Scope	trade_basic.developer.trade_refund
权限要求	无

请求参数

请求头

access-token必填String

示例：clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1KcxFnZ

调用https://open.douyin.com/oauth/client_token/生成的token

content-type必填String

示例：application/json

固定值"application/json"

Body

order_idString

示例：ot71231

抖音开平内部交易订单号，长度<= 64byte。

注意：refund_id , out_refund_no , order_id 三选一，不能都不填。

out_refund_noString

示例：12313

开发者系统生成的退款单号。

注意：refund_id , out_refund_no , order_id 三选一，不能都不填。

refund_idString

示例：ot1231231

抖音开平内部交易退款单号，长度<= 64byte。

注意：refund_id , out_refund_no , order_id 三选一，不能都不填。

请求示例
curl --location --request POST 'https://open.douyin.com/api/trade_basic/v1/developer/refund_query/' \
--header 'Content-Type: application/json' \
--header 'access-token: clt.xxx' \
--data-raw='{
        "refund_id": "ot1231231"    
}'

响应参数

Body展开全部子属性

data必填Struct

返回数据信息

展开子属性

err_msg必填String

错误提示

err_no必填Int32

示例：0

错误码

log_id必填String

示例：2023010128382726

日志id，排查问题时使用

响应示例
正常响应示例异常响应示例
{
  "data": {
    "refund_list": [
      {
        "merchant_audit_detail": {
          "audit_status": "AGREE",
          "need_refund_audit": 1,
          "refund_audit_deadline": 1673253628929
        },
        "create_at": 1671994501000,
        "refund_at": 1672994501000,
        "refund_status": "SUCCESS",
        "refund_total_amount": 1992,
        "item_order_detail": [
          {
            "item_order_id": "motb700000000101",
            "refund_amount": 996
          },
          {
            "refund_amount": 996,
            "item_order_id": "motb700000000102"
          }
        ],
        "message": "",
        "order_id": "motb700000000777",
        "out_refund_no": "ext_refund_no_812832",
        "refund_id": "motb7000000007666"
      }
    ]
  },
  "err_no": 0,
  "err_msg": "success",
  "log_id": "2022092115392201020812109511046"
}

切换单列布局

错误码

HTTP 状态码	错误码	错误码描述	排查建议
200	10000	参数不合法：xxxx	对照错误提示和接口字段定义，检查对应的参数
200	13000	系统错误，请重试	请重试，若多次重试仍然报错，请联系oncall
200	20000	退款单不存在/订单不存在	按以下步骤进行排查： 1. 若刚刚发起退款，系统有延迟，建议等几秒钟再重试 2. 请仔细核对参数，out_refund_no、refund_id、order_id与app_id是否匹配 3. 如果是以refund_id、order_id查询，说明没有对应的退款单。 4. 如果是以out_refund_no查询，很可能是out_refund_no不存在。建议改用order_id查询退款，确认是否存在退款单。如果不存在退款单，说明没有成功发起退款。如果存在退款单且out_refund_no为空，说明开发者未响应退款申请回调。建议检查退款申请回调接口。以上步骤都排查过，仍然无法处理时请提oncall

常见问题

1.为什么开发者未发起退款，但是查询到订单在退款中？

A：除了开发者发起退款外，还存在用户通过抖音平台的入口发起、抖音客服发起等场景，请通过查询退款接口查询订单的退款记录，并检查 refund_source 字段，可以获得具体的退款来源。

2.为什么订单会存在抖音客服发起的退款

A：用户找到抖音客服投诉，客服会联系商家确认后发起客服退款，如有疑问请咨询运营。客服退不需要商家审核，但需要开发者响应退款申请回调

3.为什么一直处于退款中

A：查询退款接口查询退款信息，首先看 refund_status 是不是退款中，如果是，则按以下步骤确认：

a.

out_refund_no为空，说明退款申请回调未成功，请开发者确认自身系统接入了退款申请回调且正确响应了退款申请回调。72小时内交易系统会持续重试，直到回调成功(超过72小时，系统会自动通过)。排查方法请参考：退款申请回调文档末尾的退款申请回调接口排查模块

b.

out_refund_no不为空，则看审核状态audit_status，如果是待审核状态，请同步审核结果。

c.

以上都不是，请联系oncall

查询退款在线调试

接口说明

使用限制

基本信息

请求参数

响应参数

错误码

常见问题

1.为什么开发者未发起退款，但是查询到订单在退款中？

2.为什么订单会存在抖音客服发起的退款

3.为什么一直处于退款中

查询退款