抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台
  • JS API 列表
  • 基础
  • TTML
  • 网络
  • 媒体
  • 地图
  • 文件
  • 数据缓存
  • 地理位置
  • 设备
  • 画布
  • 界面
  • 页面导航
  • 开放接口
  • 行业开放
  • 通用交易系统
  • 交易系统(即将废弃)
  • 营销
  • 预约
  • 履约
  • 预下单
  • 支付
  • 逆向交易
  • (即将废弃)tt.applyRefund
  • 交易工具
  • 第三方平台
  • 其它
  • 生活服务(即将废弃)
  • 注意
    本文档即将废弃,新文档请参见plugin.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

    编码列表

    退款编码
    含义
    102
    没看清使用规则,要用时才发现有限制
    103
    其他平台/方式购买更优惠
    106
    商家营业但不接待
    107
    商家停业/装修/转让
    109
    朋友/网上评价不好
    114
    不能送外卖
    116
    可用的门店距离太远
    117
    担心安全问题(疫情、天气等)
    118
    需要加价/购买其他产品才能用
    119
    服务态度不好
    122
    实际与宣传/描述不一样
    123
    商家服务态度差
    125
    商家要求改用其他方式/平台付款
    158
    电话/发消息联系不上商家
    161
    排队太久/预约不上位置、包厢等
    211
    商家餐品有质量问题
    212
    商家地址信息错误,找不到店铺
    213
    不满足使用条件
    215
    因排队等原因放弃使用
    217
    商家设备/环境有质量问题
    304
    因疫情/天气等不可抗力无法使用
    305
    个人原因无法到店使用
    306
    券被错误核销
    401
    计划有变,暂时不需要了
    402
    买多了/买错了
    406
    商家缺货
    999
    其他原因(需填写备注)

    FeeDetailsInfo

    属性名
    类型
    默认值
    是否必传
    说明
    最低支持版本
    feeType
    number
    费用类型
    1: 配送费
    2: 包装费
    18:基建费
    19:燃油费
    20:税费
    行业 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 用法跟原来一致。