商家经营工具-开发指引
退款退货业务接入说明
一、基础说明
本文档将涵盖API调用场景及注意事项，天猫与淘宝的退货退款API将统一为一大套API接口对外开放。
适用于接入退款退货管理功能的第三方开发者（下文简称：isv）或自主开发的商家。
注意：消费者发起退款后，为了避免出现资损和投诉，建议除了系统对接退款退货流程外，还需要售后客服与消费者沟通确认，再最终往下推进退款流程。
1）订单付款未发货前，消费者发起退款，卖家可以同意退款，资金原路退回；卖家也可以进行发货，订单进入发货状态。
2）已发货订单的退款，消费者可以发起<退款退货>或者<退款不退货> , 不同的退款类型和原因，卖家侧也有响应时效限制，如果不处理会自动同意退款。
获取退款单API
taobao.refunds.receive.get 查询卖家收到的退款列表
taobao.refund.get 获取单笔退款详情
二、退款退货调用流程
1. taobao.rp.refund.review( 审核退款单 ) 审核退款单，标志是否可用于批量退款，目前仅支持天猫订单，仅支持主账号操作。
2. 天猫订单退款必须先调用审核接口，再调用同意退款接口 taobao.rp.refunds.agree( 同意退款 )。
1）同意退款接口仅支持许子账号授权调用，当前调用 API所用的子账号必须在卖家中心→子账号管理 授权退款操作的权限，并设定具体的操作限额，详情点击参考子账号授权流程介绍。
注意：需要保证该子账号拥有客户服务-售中售后管理-同意退款（集市需要交易管理-子账号售中退款-同意子账号退款）的权限点。
2）该接口分两个阶段，第一次不带Code参数，系统会发送验证码到当前授权所代表的子账号用户注册的手机上，第二次带Code参数（参数内容为验证码），执行同意退款打款操作，调用成功，则直接通过支付宝打款给买家。
注意：目前不支持同意退款接口只调用一次即完成退款操作，由于接口调用会直接打款至支付宝，基于安全必须通过获取短信的方式完成退款。
3）并且集市支持批量(20笔以内，总金额6000以内)，天猫支持30笔以内，总金额10000以内。
4）入参refund_infos说明：
① 对于集市，包含信息如下：RefundId（退款单ID）、Fee（退款金额）、Version（通过taobao.refund.get接口获取refund_version）；
② 对于天猫，包含的数据有退款ID|其对应的金额|对应版本号列表|退款阶段（onsale\aftersale），其中金额以分为单位，ID与金额以“|”符号分隔，多笔订单以“,”分隔。
格式：RefundId1|Fee1|Version1|Refund_phase,RefundId2|Fee2|Version2|Refund_phase ...
示例：192242532288979|6000|12312|onsale,192242532298979|6000|32112|onsale
4）判断是否退款成功
success 为 true 时，【不一定】全部成功，ISV需要取到results后逐个判断是否成功。
三、退款状态变化
退款单的状态可以在Refund数据结构中的Status获取，会根据退款操作的变化而变化。
关于退款单状态的变化情况请参考上文天猫退款退货流程，以下列表仅做描述，现有的退款单状态：
| API |
描述 |
说明 |
| WAIT_SELLER_AGREE |
买家已经申请退款，等待卖家同意 |
买家提交退款申请时的状态 |
| WAIT_BUYER_RETURN_GOODS |
卖家已经同意退款，等待买家退货 |
退款申请包含退货时，卖家同意退货（后台或者taobao.rp.returngoods.agree）后的状态 |
| WAIT_SELLER_CONFIRM_GOODS |
买家已经退货，等待卖家确认收货 |
退款申请包含退货，买家上传退货物流信息后的状态 |
| SELLER_REFUSE_BUYER |
卖家拒绝退款 |
卖家拒绝退货或者拒绝退款时 |
| SUCCESS |
退款成功 |
卖家批量同意退款操作后的状态 |
| CLOSED |
退款关闭 |
退款申请超时或者未发货的订单申请退款时卖家强制发货后的状态 |
四、退款/退货/换货卖家响应时效
不适用“立即退款”（以下简称“秒退”）规则的特殊类目及场景有哪些？
1）本地生活/点券、航旅、虚拟、天猫卡券及定制相关类目（明细类目点此查看）；
2）根据天猫《滥用会员权利的规则及实施细则》，会员滥用会员权利产生的订单；
3）特殊交易流程或新型业务场景下产生的订单，包括新零售居然之家城市站、淘宝特价版APP/“阿里鱼-造点新货”频道等特殊渠道、涉及资金出入境的业务场景、天猫大闸蟹商品等虚拟商品/服务交易场景等。
以上“退款/退货/换货卖家响应时效”信息根据淘宝网的平台规则内容整理，可能存在主站规则变更，开放平台信息同步不及时问题，以主站平台规则为准，可以查看：淘宝网超时说明，天猫交易时效规定
五、未发货2H秒退订单
| 退款类型 |
变更前超时时限 |
变更后超时时限 |
||
| 退款（无需退货） |
货物状态：未发货 |
不想要了 |
2日 |
除特殊类目及场景外，付款2小时内且订单金额≤200元的订单买家申请退款时享受“秒退”，除上述情形外的超时时效为24小时 |
| 拍错了/订单信息错误 |
||||
| 商家缺货 |
3日 |
|||
| 商家未按约定时间发货 |
||||
| 货物状态：已发货(消费者未收到货) |
设置了“支持售中自动退款”的电子凭证商品的所有退款原因 |
1日 |
24小时 |
|
| 除上述情形外 |
3日 |
48小时 |
||
| 退货退款/换货 |
已发货需要退货/换货/我要换货-“转退货” |
1、退款原因为“试了不合适”的商品； 2、退款原因为“7天无理由退换货”的部分商品，详情请点此查看 |
立即 |
立即 |
| 1日 |
24小时 |
|||
| 除上述情形外 |
3日 |
48小时 |
||
| 已退货待退款 |
快递 |
10日 |
240小时 |
|
| 平邮 |
30日 |
336小时 |
||
| 等待买家修改协议 |
未退货 |
7日 |
120小时 |
|
| 已退货 |
15日 |
|||
要点一：商家需要在新规要求时间内响应买家的退款申请（同意或者拒绝），逾期系统将默认同意买家的退款/退货/换货申请；
要点二：针对未发货状态下付款后2小时内，且订单金额≤200元的中秒退的订单，商家需及时关注异常情况，有需要第一时间联系快递/买家协商处理。
符合平台“未发货2H秒退”订单查看路径：“商家中心→退款售后管理，进入退款管理页面，在“业务类型”筛选框下选择“未发货2小时零秒退”则可符合规则订单明细
1）Q：店铺ERP如何通过 API接口 识别该笔订单是不是未发货2H秒退订单？
A：目前未发货秒退的识别方式为接口taobao.refund.get( 获取单笔退款详情 ) 请求参数 fileds中加上 attribute，响应返回列表中“attribute” 字段中含有 “newAutoRefund” 即为未发货秒退订单。
2）Q：商家后台如何查询该笔订单是属于平台“未发货2H秒退”的订单？
A：您可以在店铺后台店铺管理页面查询该笔订单是否符合“未发货2H秒退”，具体查询路径为“商家中心-退款管理-业务类型（选择未发货2H秒退）
商家端后台查询页面展示如下图：
3）Q：在属于平台“未发货2H秒退”的订单中，若商品实际已发货，应该怎么办？
A：：若商品您已发货，建议您第一时间联系快递拦截退回，且同时对买家端做好拒签的提醒，若前面过程都无法拦截，建议及时联系买家协商，未协商一致的情况下可以联系天猫客服协助。
同时，建议您及时调整商品发货等操作流程哦，若订单状态已发货，就不属于“未发货2H秒退”订单范围。
4）Q：如果在商家响应退款前，消费者突然修改了退款协议，退款的超时时间怎么计算？
A：订单超时会根据退款状态调整，按照最新退款状态的显示计算，比如：消费者修改为 退款（无需退货），则会按照 退款（无需退货）的超时时间开始计算。
5）Q：商家响应退款的时间要求缩短了，有什么工具可以帮助我更快速的处理吗？
A：亲，有以下两个工具可以帮助您批量自动化处理退款：
① 您可使用平台为商家推出的AG产品，设置自动化退款，详细操作【点此查看】；若您对AG产品有其他问题，也可【点此查看】提交工单流程，处理人会在1个工作内在提交工单链接中答复；
② 您可在商家中心-退款管理页面，使用【托管设置】工具，进行自动化退款，详细操作【点此查看】。
6）0秒退快递拦截场景
为了提升消费者在逆向环节的购物体验，针对符合平台自动退款规则的订单，且订单状态在“已发货”后“待派件”前，消费者申请退款时将执行0秒退。同时，平台也会向快递公司发起快递拦截指令。为了更好地帮助商家服务消费者，服务商系统需要识别0秒退的订单及快递拦截状态。
对接方案如下：
taobao.refunds.receive.get和taobao.refund.get在attribute新增以下返回值：
| 返回值 |
说明 |
| autoInterceptAgree |
= 1 ，代表淘天平台自动拦截 |
| interceptInvestor |
代表快递拦截费用的出资方，枚举值有： |
| LogisticInterceptEnum |
商品截单状态，具体值如下： |
| interceptFailCode |
截单失败原因 |
六、FAQ
1. Q：如何知道是否有退货？
A：通过 taobao.refund.get( 获取单笔退款详情 )Refund. has_good_return“买家是否需要退货”判断，true为退款退货，false退款（无需退货）。
2. Q：如何获取退款单的refund_phase和refund_version？
A：可以通过refund_id 查询接口 taobao.refund.get( 获取单笔退款详情 )获取 refund_phase“退款阶段，onsale/aftersale”和 refund_version“退款版本号”，以时间戳格式返回。
3. Q：买家修改退款申请后卖家操作退款单有什么影响？
A：买家修改退款申请后，退款版本号 refund_version 会变化，退款操作时会校验 refund_version，在操作中可以通过taobao.refund.get( 获取单笔退款详情 ) 接口查询具体退款单的Refund信息。
4. Q：子账号操作 taobao.rp.refunds.agree（同意退款）报错"操作失败"，"msg_code":"40001"
A：报该错误一般有以下几种情况，
1) 淘宝退款一次退款超过20笔了，总金额超过6000元了。
2) 天猫退款一次退款超过30笔了，总金额超过10000元了。
3) 子账号单笔可操作退款的金额超出限制；
建议商家用主账号在商家后台处理 或 给子账号调整单笔可操作退款金额上限大于实际退款金额。
示例：主账号给子账号设置的单笔可操作的退款金额上限是 800元，退款单实际退款的金额是：900元，这时子账号操作同意退款就会报错。
4) 一笔订单多个子订单，如A子订单TRADE_FINISHED(交易成功)，B子订单还在交易中。买家申请A子订单退款，这时A子订单卖家同意退款报“操作失败”；这种场景需要所以其余子订单交易完结，卖家才可操作同意退款。
5. Q：权益金、购物金退款金额获取？
A：
交易订单退款，包含购物金支付部分的退款信息，可通过：taobao.refund.get( 获取单笔退款详情 )
字段 attribute“退款扩展属性”获取进行解析。
（权益金退款具体金额是 卖家同意退款完成之后，卖家才可以获取。）
使用了权益金且退款完成【"refund_status":"SUCCESS(退款成功)"】的订单，退款接口才会返回权益金相应字段。
资金退款组成售中退款：pmtRD；
资金退款组成售后退款：pmtARD；
权益金：TMALL_MCARD_PZ_SP 单位：分。
本金：TMALL_MERCHANTCARD_SP 单位：分。
注意：
1）权益金退款，是退款完成之后，商家才可以得知具体金额的。退款完成之前，不会返回权益金，退款单也不会包含权益金退款金额。请核实订单状态是否"refund_status":"SUCCESS(退款成功)"
2）如果退款没有完成，退款单状态是以下这些情况的订单，"refund_status": "WAIT_SELLER_AGREE"(等待卖家同意) /WAIT_SELLER_AGREE(买家已经申请退款，等待卖家同意) /WAIT_BUYER_RETURN_GOODS(卖家已经同意退款，等待买家退货) /WAIT_SELLER_CONFIRM_GOODS(买家已经退货，等待卖家确认收货) /SELLER_REFUSE_BUYER(卖家拒绝退款) /CLOSED(退款关闭) ，都是不会返回权益金退款的相关字段的。
6. 同意退款接口 taobao.rp.refunds.agree（同意退款）返回的error_code列表有：
| 前台错误信息（message字段） |
错误信息解析说明 |
| 系统繁忙，请稍候再试 |
这种情况是平台内部计算逻辑异常报错，遇到此信息请稍后半小时重试，如果重试还是存在异常请通过开放平台工单反馈处理 |
| 子账号校验金额权限不足 |
退款的金额超过了商家给这个子账号设置的同意退款金额上限，需要更换子账号操作或者在子账号管理后台调整同意退款金额上限 |
| 资金正在处理中，请稍后查看处理结果 |
这类提示是因为订单应该是通过其它非支付宝渠道做退款处理的，这个需要等待下游渠道返回实际出账成功，这个可以稍后刷新看状态是否同步处理成功。 |
| 资金正在处理中，请在成交24小时后再次尝试 |
团长代付订单，支付成功后需要T+1才到商家账户，需要在24小时后同意退款 |
| 您店铺主体的支付宝账号代扣协议签署已过期，请重新签署。如您的店铺曾经过户，需要新主体的支付宝账号签署代扣协议，才能操作过户前的退款申请 |
商家执行过店铺过户，新主体操作老主体的退款会校验店铺过户协议，需要新主体签署店铺过户协议 |
| 退款失败，卖家支付宝账户异常，请联系支付宝确认 |
此类问题是因为执行退款的时候，卖家的支付宝账户出现了异常导致无法正常打款，此类问题需要卖家确认下自己的支付宝账户是否是正常可用状态，如果账号确实异常请反馈支付宝官方客服确认异常原因和处理 |
| 退款失败，卖家支付宝账户司法冻结，请联系支付宝确认 |
|
| 退款失败，卖家支付宝账户异常，请联系支付宝确认 |
|
| 退款失败，卖家支付宝账户异常，请联系支付宝确认 |
|
| 您需要重新签署子账号协议，然后再用子账号操作退款，或者让商家用主账号操作退款 |
子账号免密退款协议未签署 |
| 支付宝可用余额或者保证金不足, 请充值后再尝试操作 |
余额不足 |
| 客官别急，稍等再试试~ |
通用错误信息，未明确原因可以重试看是否能成功，如果重试多次无法成功请通过工单反馈处理 |
| 同一主订单下多笔子订单退款存在冲突，请稍后重试 |
多出现在一主多子的订单，同时操作同意退款，在支付宝并发导致，一般重试即可 |
| 系统异常 |
通用错误信息，未明确原因可以重试看是否能成功，如果重试多次无法成功请通过工单反馈处理 |
| 由于其余子订单尚未完结，售后退款失败。待买家将其余子订单确认收货后，即可操作售后退款。 |
主子订单状态不一致，需要主订单推进到售后，才能操作退款 |
| 您需要联系支付宝客服解锁该笔交易，然后再重试退款操作 |
支付宝交易被锁定 |
七、错误码信息获取与业务解析
taobao.rp.refunds.agree，接口处理错误信息的反馈，目前接口针对每笔退款失败的退款单都透出了错误信息文案，赋给message字段。
| 前台错误信息（message字段） |
错误信息解析说明 |
| 系统繁忙，请稍候再试 |
这种情况是平台内部计算逻辑异常报错，遇到此信息请稍后半小时重试，如果重试还是存在异常请通过开放平台工单反馈处理 |
| 子账号校验金额权限不足 |
退款的金额超过了商家给这个子账号设置的同意退款金额上限，需要更换子账号操作或者在子账号管理后台调整同意退款金额上限 |
| 资金正在处理中，请稍后查看处理结果 |
这类提示是因为订单应该是通过其它非支付宝渠道做退款处理的，这个需要等待下游渠道返回实际出账成功，这个可以稍后刷新看状态是否同步处理成功。 |
| 资金正在处理中，请在成交24小时后再次尝试 |
团长代付订单，支付成功后需要T+1才到商家账户，需要在24小时后同意退款 |
| 您店铺主体的支付宝账号代扣协议签署已过期，请重新签署。如您的店铺曾经过户，需要新主体的支付宝账号签署代扣协议，才能操作过户前的退款申请。 |
商家执行过店铺过户，新主体操作老主体的退款会校验店铺过户协议，需要新主体签署店铺过户协议 |
| 退款失败，卖家支付宝账户异常，请联系支付宝确认 |
此类问题是因为执行退款的时候，卖家的支付宝账户出现了异常导致无法正常打款，此类问题需要卖家确认下自己的支付宝账户是否是正常可用状态，如果账号确实异常请反馈支付宝官方客服确认异常原因和处理 |
| 退款失败，卖家支付宝账户司法冻结，请联系支付宝确认 |
|
| 退款失败，卖家支付宝账户异常，请联系支付宝确认 |
|
| 退款失败，卖家支付宝账户异常，请联系支付宝确认 |
|
| 您需要重新签署子账号协议，然后再用子账号操作退款，或者让商家用主账号操作退款 |
子账号免密退款协议未签署 |
| 支付宝可用余额或者保证金不足, 请充值后再尝试操作 |
余额不足 |
| 客官别急，稍等再试试~ |
通用错误信息，未明确原因可以重试看是否能成功，如果重试多次无法成功请通过工单反馈处理 |
| 同一主订单下多笔子订单退款存在冲突，请稍后重试 |
多出现在一主多子的订单，同时操作同意退款，在支付宝并发导致，一般重试即可 |
| 系统异常 |
通用错误信息，未明确原因可以重试看是否能成功，如果重试多次无法成功请通过工单反馈处理 |
| 由于其余子订单尚未完结，售后退款失败。待买家将其余子订单确认收货后，即可操作售后退款。 |
主子订单状态不一致，需要主订单推进到售后，才能操作退款 |
| 您需要联系支付宝客服解锁该笔交易，然后再重试退款操作 |
支付宝交易被锁定 |
八、涉及API
| API |
功能描述 |
| 查询商家信息 |
|
| 查询退款列表 |
|
| 查询单笔退款 |
|
| 拒绝退货 |
|
| 同意退货 |
|
| 天猫商家回填退款物流单号 |
|
| 退款单标记 |
|
| 审核退款单 |
|
| 拒绝退款 |
|
| 同意退款 |