Calculate Refund

POST

/return_refund/202602/refunds/calculate

Use this API to estimate the refundable amount for a cancellation, refund, or return-and-refund request. The estimate depends on the selected request_type, reason_name, and targeted items. If skus, order_line_item_ids, and order_line_list are all omitted, all order lines in the order are selected as inputs to the refund calculation. For return-and-refund scenarios, the estimate can also depend on the selected return shipping method.

Authorizations

• accessToken

Parameters

Query Parameters

shop_cipher

required

string

Identifies the shop. Obtain it from the Get Authorized Shops API.

Request Body^required

Media typeapplication/json

object

order_id

required

TikTok Shop order id.

string

request_type

required

Request type

• CANCEL
• REFUND
• RETURN_AND_REFUND Note: different request types are used for different aftersales scenarios. Also, different request types might have different refund amounts, because the refund amount calculation policy is different.

string

shipment_type

How buyer ships items to seller when in a return request, could be:

• PLATFORM
• BUYER_ARRANGE

string

handover_method

Which handover method buyer chooses to use when returning goods to seller by platform

• DROP_OFF: buyer drops off the parcel in logistics service collect point.
• PICKUP: logistics service picks up the buyer package.

string

reason_name

required

Seller’s reason for the selected cancellation, refund, or return-and-refund request. Use the Get Aftersale Eligibility endpoint to retrieve the currently available reasons, and submit the returned reason name in this field.

string

order_line_item_ids

TikTok Shop order line item IDs to include in the refund calculation. Do not provide non-empty values in both order_line_item_ids and order_line_list in the same request.

Array<string>

skus

Skus

Array<object>

object

sku_id

required

TikTok Shop SKU ID to include in the refund calculation.

string

quantity

required

Quantity of this SKU to include in the refund calculation.

integer format: int64

order_line_list

Order lines to include in the refund calculation. Use this field when you need to identify individual sub-items in a bundle product. Note: This field is completely backward compatible with the previous order_line_item_ids field. Do not provide non-empty values in both order_line_list and order_line_item_ids in the same request.

Array<object>

object

order_line_item_id

The corresponding order line ID

string

sub_order_line_item_id

The sub-order-line ID inside a bundle product

• Required for bundle products
• Not required for non-bundle products

string

Example

{
  "order_id": "576469648086175911",
  "request_type": "REFUND",
  "shipment_type": "PLATFORM",
  "handover_method": "DROP_OFF",
  "reason_name": "ecom_order_delivered_refund_reason_missing_product_seller",
  "order_line_item_ids": [
    "576469648086306986"
  ],
  "skus": [
    {
      "sku_id": "1729386416015578024",
      "quantity": 1
    }
  ],
  "order_line_list": [
    {
      "order_line_item_id": "576469648086306986",
      "sub_order_line_item_id": "576469648086306987"
    }
  ]
}

Responses

200

Success

Media typeapplication/json

object

code

Status code; 0 means success.

integer format: int64

message

Success or failure message.

string

request_id

Request log ID.

string

data

object

order_refund_amount

Refund amount to buyer.

object

currency

Currency for payment.

string

refund_total

Total amount refund to buyer.

string

refund_subtotal

Subtotal amount included in the calculated refund.

string

refund_shipping_fee

Shipping fee refund to buyer.

string

refund_tax

Tax returned to buyer.

string

retail_delivery_fee

Retail delivery fee takes effect once platform GMV exceeds 500,000 USD, according to US Colorado states’ compliance rules.

string

Example

{
  "code": 0,
  "data": {
    "order_refund_amount": {
      "currency": "USD",
      "refund_total": "1.23",
      "refund_subtotal": "1",
      "refund_shipping_fee": "0.2",
      "refund_tax": "0.03",
      "retail_delivery_fee": "0.1"
    }
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}