抖音开放平台Logo
开发者文档
“/”唤起搜索
控制台
  • 行业插件介绍
  • 申请行业插件
  • 使用行业插件
  • 电商插件
  • 短剧插件
  • 生服插件
  • 预下单
  • 支付
  • 营销
  • 预约
  • 逆向交易
  • plugin.applyRefund
  • plugin.applyRefundLife
  • 生服组件
  • plugin.applyRefund

    收藏
    我的收藏
    基础库 2.51.0 开始支持本方法,低版本需做兼容处理,这是一个异步方法。
    通过申请退款方法可退款指定份数/指定金额的商品。

    使用限制

    在使用生服插件中的组件和 API 前,需要对行业插件有一个基本了解,可以参考文档:行业插件介绍,然后按照以下步骤及顺序使用生服插件中的能力:
    1.参考 申请行业插件 完成插件的申请,注意只有小程序拥有生服类目资质才可见申请入口;
    2.参考 使用行业插件 进行能力的调用;
    行业插件在抖音 App 版本 31.8.0 及以上,小程序基础库版本 3.4x.0.0 及以上时支持。

    语法

    plugin.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[]
    否(外卖场景时,必传)
    退款理由对应的编码列表
    详见编码列表
    目前仅支持传入一个编码
    2.51.0.0
    note
    string
    否(reasonCode = 999 ,即其他时,必填)
    退款备注(退款备注字数不能超过200个)
    2.51.0.0
    feeDetailsList
    FeeDetailsInfo[]
    FeeDetailsInfo 说明见下文
    否(存在额外费用比如打包费、配送费、基建费、燃油费、税费时,必传)
    费用明细列表
    2.51.0.0

    编码列表

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

    FeeDetailsInfo

    属性名
    类型
    默认值
    是否必传
    说明
    最低支持版本
    feeType
    number
    费用类型
    1: 配送费
    2: 包装费
    18:基建费
    19:燃油费
    20:税费
    2.51.0.0
    refundAmount
    number
    费用退款总金额,单位分
    2.51.0.0

    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

    代码示例

    指定份数退

    const plugin = tt.requirePlugin('tta5a3d31e3aecfb9b11'); plugin.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); }, });

    指定金额退

    const plugin = tt.requirePlugin('tta5a3d31e3aecfb9b11'); plugin.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); }, });

    退配送费或包装费

    const plugin = tt.requirePlugin('tta5a3d31e3aecfb9b11'); plugin.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