基础能力

触达与营销

支付

运营

生活服务

通用能力

生活服务交易系统（全融合版）

通用参数

错误码和返回码

查询接口

预下单

营销算价

支付

核销

分账

退货退款

预约

生活服务交易系统（账号融合版）

CPS佣金设置与查询

即送（原随心团）解决方案

核销工具解决方案

历史版本（不推荐使用）

垂直行业

其它

查询退款

我的收藏

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

使用限制

无

接口说明

•

支持 refund_id 查询

•

支持 out_refund_no 查询

•

支持 order_id 查询

基本信息

基本信息
HTTP URL	https://open.douyin.com/api/apps/trade/v2/refund/query_refund
HTTP Method	POST
Scope	industry_open.trade.refund
权限要求	不需要用户授权

请求头

名称	类型	是否必填	描述
Content-Type	string	是	固定值 "application/json"
access-token	string	是	调用/oauth/client_token/生成的token，此token不需要用户授权。示例: clt.xxx

请求参数

注意：

refund_id , out_refund_no , order_id 三选一，不能都不选。优先级：refund_id >out_refund_no >order_id

order_id维度的不兼容老退款单查询，只支持查询交易系统的退款。查询返回的结果数限制50条

名称	类型	是否必填	描述	示例值
refund_id	`string`	否	抖音开平内部交易退款单号，长度 <= 64byte	ot1231231
out_refund_no	`string`	否	开发者系统生成的退款单号，长度 <= 64byte	12313
order_id	`string`	否	抖音开平内部交易订单号，长度 <= 64byte	ot7231231

请求示例

curl --location --request POST 'https://open.douyin.com/api/apps/trade/v2/refund/query_refund' \
--header 'Content-Type: application/json' \
--header 'access-token: clt.xxx' \
--data-raw='{
        "refund_id": "ot1231231", //当有refund_id时，优先使用refund_id查询
        "out_refund_no": "12313",
        "order_id": "ots712313",
}'

响应参数

名称	类型	是否必填	描述	示例
data	`object`	否	返回数据信息
extra	`object`	是	额外信息，参考通用参数中的说明

data 信息

名称	类型	是否必填	描述	示例
error_code	`int`	是	错误码，0为成功	0
description	`string`	是	错误码描述	success
refund_list	`Array<object>`	是	退款查询结果列表，最多返回50条 (建议开发者用这个字段)
refund_id	`string`	是	系统退款单号，开放平台生成的退款单号	ot13213
out_refund_no	`string`	否	开发者系统生成的退款单号，与抖音开平退款单号 refund_id 唯一关联	2313
refund_total_amount	`int64`	是	退款金额，单位[分]	100
refund_status	`string`	是	退款状态退款中- PROCESSING 已退款- SUCCESS 退款失败- FAIL	PROCESSING
refund_at	`int64`	否	退款时间，13 位毫秒时间戳，只有已退款才有退款时间	1643009622000
message	`string`	否	退款结果信息，非商家拒绝退款导致的退款失败，可以通过该字段了解退款失败原因	退款失败
order_id	`string`	是	系统订单信息，开放平台生成的订单号	ot123123
item_order_detail	`Array<object>`	否	商品单信息
merchant_audit_detail	`object`	否	退款审核信息
create_at	int64		退款创建时间，13 位毫秒时间戳	1643009622000
refund_related_order_detail	list	否	预售单主单关联订单退款算价信息

refund_list 说明

名称	类型	是否必填	描述	示例
refund_id	`string`	是	系统退款单号，开放平台生成的退款单号	ot13213
out_refund_no	`string`	否	开发者系统生成的退款单号，与抖音开平退款单号 refund_id 唯一关联	2313
refund_total_amount	`int64`	是	退款金额，单位[分]	100
refund_status	`string`	是	退款状态退款中- PROCESSING 已退款- SUCCESS 退款失败- FAIL	PROCESSING
refund_at	`int64`	否	退款时间，13 位毫秒时间戳，只有已退款才有退款时间	1643009622000
message	`string`	否	退款结果信息，非商家拒绝退款导致的退款失败，可以通过该字段了解退款失败原因	退款失败
order_id	`string`	是	系统订单信息，开放平台生成的订单号	ot123123
item_order_detail	`Array<object>`	否	商品单信息 (交易系统订单退款才有的信息)
merchant_audit_detail	`object`	否	退款审核信息 (交易系统订单退款才有的信息)
create_at	int64	是	退款创建时间，13 位毫秒时间戳	1643009622000
refund_source	int64	否	退款来源，仅交易2.0退款有来源，老的担保交易/1.0订单可能没有记录来源 1: 用户发起退款 2: 开发者发起退款 3: 自动退款 4: 抖音客服退款 5: 预约失败自动发起退款 6: 开发者拒绝接单退款 7: 后约单触发先买单退款	1

item_order_detail 说明

名称	类型	是否必填	描述	示例值
item_order_id	`string`	是	抖音开平侧的商品单号	ot123123
refund_amount	`int64`	是	该商品单退款金额，单位[分]	50

merchant_audit_detail 说明

名称	类型	是否必填	描述	示例
refund_audit_deadline	`int64`	是	退款审核的最后期限，过期无需审核，自动退款，13 位 unix 时间戳，精度：毫秒	151231321231
audit_status	`string`	是	退款审核状态： •INIT：初始化 •TOAUDIT：待审核 •AGREE：同意 •DENY：拒绝 •OVERTIME：超时未审核自动同意	AGREE
deny_message	`string`	否	不同意退款信息，长度 <= 512 byte	不同意退款

refund_related_order_detail 说明

名称	类型	是否必填	描述	示例
order_id	`string`	是	到综融合：预约加价单ID、服务加项单ID	ot123123
order_type	`int64`	否	订单类型 1 预约加价单；2 服务加项单	1,2
deduct_fee_amount	`int64`	否	手续费金额预约单预约完成前可传入、预约完成后不可传	1
refund_amount	`int64`	是	退款金额	100

响应示例

正常示例

•

由于旧协议没有兼容退款结果列表，所以新增了refund_list字段，建议开发者使用refund_list字段

{
  "data": {
    "refund_list": [
      {
        "merchant_audit_detail": {
          "audit_status": "AGREE",
          "need_refund_audit": 1,
          "refund_audit_deadline": 1673253628929
        },
        "create_at": 1671994501000,
        "refund_source": 1,
        "refund_at": 1672994501000,
        "refund_status": "SUCCESS",
        "refund_total_amount": 1992,
        "item_order_detail": [
          {
            "item_order_id": "800000000101757849613437984",
            "refund_amount": 996
          },
          {
            "refund_amount": 996,
            "item_order_id": "800000000101757824013547984"
          }
        ],
        "message": "",
        "order_id": "8000000001017577984",
        "out_refund_no": "ext_refund_no_718536707992153502030519534",
        "refund_id": "718536707992153502030519534"
      }
    ],
    "order_id": "8000000001017577984",
    "refund_id": "718536707992153502030519534",
    "refund_status": "SUCCESS",
    "refund_total_amount": 1992,
    "merchant_audit_detail": {
      "audit_status": "AGREE",
      "need_refund_audit": 1,
      "refund_audit_deadline": 1673253628929
    },
    "message": "",
    "create_at": 1671994501000,
    "refund_at": 1672994501000,
    "item_order_detail": [
      {
        "item_order_id": "800000000101757849613437984",
        "refund_amount": 996
      },
      {
        "item_order_id": "800000000101757824013547984",
        "refund_amount": 996
      }
    ],
    "out_refund_no": "ext_refund_no_718536707992153502030519534",
    "error_code": 0,
    "description": ""
  },
  "extra": {
    "error_code": 0,
    "description": "",
    "sub_error_code": 0,
    "sub_description": "success",
    "logid": "02168173575240700000000000000000000ffff0a706f38ab32d2",
    "now": 1681735753
  }
}

异常示例

{
  "data": {
    "error_code": 13000,
    "description": "系统错误"
  },
  "extra": {
    "sub_error_code": 13000,
    "sub_description": "系统错误",
    "logid": "2022092115392201020812109511046",
    "now": 1663745962686,
    "error_code": 2191000,
    "description": ""
  }
}

错误码

详情参见错误码/返回码。

错误码	错误提示	建议解决方案
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查询退款，确认是否存在退款单。 a.如果不存在退款单，说明没有成功发起退款。 b.如果存在退款单且out_refund_no为空，说明开发者未响应退款申请回调。建议检查退款申请回调接口。以上步骤都排查过，仍然无法处理时请提oncall

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

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

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

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