• JS API 列表
  • 基础
  • TTML
  • 网络
  • 媒体
  • 地图
  • 文件
  • 数据缓存
  • 地理位置
  • 设备
  • 画布
  • 界面
  • 页面导航
  • 开放接口
  • 行业开放
  • 交易系统
  • 履约
  • 预下单
  • 支付
  • 逆向交易
  • tt.applyRefund
  • 预约
  • 营销
  • 通用交易系统
  • 交易工具
  • 第三方平台
  • 其它
  • 基础库 2.51.0 开始支持本方法,低版本需做兼容处理,这是一个异步方法。
    通过申请退款方法可退款指定份数/指定金额的商品。

    使用限制

    最低支持版本上注明行业 SDK ,表示仅在行业 SDK 上才支持,需要在代码中配置行业 SDK 的权限。当完成行业 SDK 的权限配置后,可通过 tt.canIUse('createOrder') 判断该 API 是否可用。

    语法

    tt.applyRefund(options);

    参数说明

    options 为 object 类型,属性如下:
    属性名
    类型
    默认值
    必填
    说明
    最低支持版本
    outOrderNo
    string
    外部商户订单号
    2.51.0.0
    refundInfo
    Object
    退款信息
    2.51.0.0
    goodsList
    RefundGoods[]
    RefundGoods说明见下文
    goodsList、itemOrderList、skuList 和refundTotalAmount必填一个
    退款商品信息
    2.51.0.0
    skuList
    RefundSku[]
    goodsList、itemOrderList、skuList 和refundTotalAmount必填一个
    退款 sku 信息
    2.77.0.0
    itemOrderList
    ItemOrderList[]
    ItemOrderlist 说明见下文
    goodsList、itemOrderList、skuList 和refundTotalAmount必填一个
    退款 item 单信息,最小长度为1
    2.59.0.3
    refundTotalAmount
    number
    goodsList、itemOrderList、skuList 和refundTotalAmount必填一个
    老订单退款指定金额,新订单该参数无效
    2.51.0.0
    callbackData
    Object
    退款透传至服务端的信息,会被JSON.stringfy处理
    2.51.0.0
    success
    Function
    接口调用成功的回调函数
    2.51.0.0
    fail
    Function
    接口调用失败的回调函数
    2.51.0.0
    complete
    Function
    接口调用结束的回调函数(调用成功、失败都会执行)
    2.51.0.0

    refundInfo

    属性名
    类型
    默认值
    必填
    说明
    最低支持版本
    reason
    string[]
    是(外卖场景时,不是必填)
    退款理由(总数不能超过20个,单个退款理由字数不能超过60个)
    2.51.0.0
    reasonCode
    number[]
    否(外卖场景时,必传)
    退款理由对应的编码列表
    详见编码列表
    目前仅支持传入一个编码
    行业 SDK
    note
    string
    否(reasonCode = 999 ,即其他时,必填)
    退款备注(退款备注字数不能超过200个)
    2.51.0.0
    feeDetailsList
    FeeDetailsInfo[]
    FeeDetailsInfo 说明见下文
    否(存在配送费或包装费时,必传)
    费用明细列表
    行业 SDK

    编码列表

    退款编码
    含义
    401
    临时有事,我不想要了
    402
    买错了/买多了/买少了
    403
    地址/电话填写错误
    404
    配送时间太长
    408
    送达时间选错(仅预约单可填写)
    999
    其他原因(需填写备注)

    FeeDetailsInfo

    属性名
    类型
    默认值
    是否必传
    说明
    最低支持版本
    feeType
    number
    费用类型
    1: 配送费
    2: 包装费
    行业 SDK
    refundAmount
    number
    费用退款总金额,单位分
    行业 SDK

    ItemOrderList

    字段名
    类型
    是否必传
    描述
    itemOrderId
    string
    退款的商品单号
    refundAmount
    number
    该子单需要退款的金额,单位分,不能大于该子单实付金额,未填入该字段,则默认为对应子单最大退款金额

    RefundGoods

    属性名
    类型
    默认值
    必填
    说明
    goodsId
    string
    商品 ID
    goodsType
    number
    商品类型
      1:商品库商品
      2:非商品库商品
    quantity
    number
    退款数量

    RefundSku

    属性名
    类型
    默认值
    必填
    说明
    最低支持版本
    skuId
    string
    退款 skuId
    2.77.0.0
    skuType
    number
    skuId类型
      1:商品库商品
      2:非商品库商品
    2.77.0.0
    quantity
    number
    退款的 sku 数量
    2.77.0.0

    回调成功

    object 类型
    属性名
    类型
    说明
    最低支持版本
    orderId
    string
    内部商户订单号
    2.51.0
    outRefundNo
    string
    开发者退款单号
    2.51.0
    refundId
    string
    内部退款单号
    2.51.0

    回调失败

    object 类型
    属性名
    类型
    是否一定存在
    说明
    最低支持版本
    errNo
    string
    错误码,对应信息可查看 errNo 说明
    2.51.0
    errMsg
    string
    错误信息提示
    2.51.0
    errLogId
    string
    当申请退款接口失败时会提供该数据,可供服务端排查问题
    2.51.0

    代码示例

    指定份数退

    tt.applyRefund({ refundInfo:{ reason: ['理由'], // 退款理由 必填 note:'不需要', // 备注 非必填 } outOrderNo: 'xxxx', // 外部订单号 必填 goodsList: [ { goodsId: '123', // 商品ID 必填 goodsType: 2, // 商品类型 必填 quantity: 1, // 退款商品数量 必填 }, ], // 退款商品列表 新订单全部使用该数组退款 refundGoodsList和refundTotalAmount必填一个 callbackData:{ test:123 }, // 透传数据 会被 JSON.stringfy 化 非必填 // refundTotalAmount:1, // 老订单指定金额退款,新订单该参数无效 success: res => { const { orderId, outRefundNo, refundId } = res; console.log('申请退款成功'); console.log('orderId', orderId, 'outRefundNo', outRefundNo, 'refundId', refundId); }, fail: res => { const { errNo, errMsg, errLogId } = res; console.log('申请失败', errNo, errMsg, errLogId); }, });

    指定金额退

    tt.applyRefund({ outOrderNo: orderId, refundInfo: { reason: ["test"], }, itemOrderList: [ { itemOrderId: "ot423412", refundAmount: 100 }, { itemOrderId: "ot423413" }, ], success(res) { const { outRefundNo } = res; tt.showToast({ title: outRefundNo }); }, fail(res) { console.log("fail", res); }, });

    退配送费或包装费

    tt.applyRefund({ refundInfo: { reason: ["理由"], // 退款理由 必填 note: "不需要", // 备注 reasonCode: [401], feeDetailsList: [ { feeType: 1, refundAmount: 1, }, ], }, outOrderNo: "xxx", // 外部订单号 必填 itemOrderList: [ { itemOrderId: "ot423412", refundAmount: 10 }, { itemOrderId: "ot423413" }, ], callbackData: { test: 123 }, // 透传数据 会被 JSON.stringfy 化 非必填 success: (res) => { const { orderId, outRefundNo, refundId } = res; console.log("申请退款成功"); console.log( "orderId", orderId, "outRefundNo", outRefundNo, "refundId", refundId ); }, fail: (res) => { const { errNo, errMsg, errLogId } = res; console.log("申请失败", errNo, errMsg, errLogId); }, });

    Bug & Tip

      Tip:外卖场景时,需要在代码中配置行业 SDK 的权限:行业 SDK 的权限配置,行业 SDK 的权限配置在基础库 2.74.0.0 抖音版本 23.0 以上支持,API 用法跟原来一致。