🔒
Requires write_order access scope. More access scope

The Order Refund API processes order refunds, supports product selection, supports setting refund amounts for shipping and other charges, and supports specifying payment channels and refund amounts.

Request Parameters

Public Request Parameters

📘
Public Request Parameters

Path Parameters

Parameter	Type	Required	Description	Example
`order_id`	string	Yes	The unique ID of the order.	`1232123`

Body Parameters

Field	Type	Required	Example	Description
`refund_total`	string	yes	`100.00`	The total refund amount. If refund_payments are specified, this value must equal the sum of all refund_payments amounts.
`refund_shipping_total`	string	no	`10.00`	The total shipping amount to be refunded.
`refund_tip`	string	no	`5.00`	The tip amount to be refunded.
`refund_additional_total`	string	no	`15.00`	The total amount for additional refunded charges.
`refund_product_total`	string	no	`70.00`	The total refund amount for the refunded products.
`refund_line_items`	array of LineItem	no	`[{"line_item_id": "LI123", "quantity": 2}]`	The items being refunded. Refund items. See LineItem for details.
`refund_payments`	array of RefundPayment	no	`[{"payment_line_id": "PAY123", "refund_price": "50.00"}]`	The payment methods used for the refund. See RefundPayment for details.
`refund_additional_prices`	array of RefundAdditionalPrices	no	`[{"name": "Handling Fee", "price": "5.00"}]`	Additional charges included in the refund. See RefundAdditionalPrices for details.
`note`	string	no	`Refund for damaged items`	Remark

LineItem

Field	Type	Example	Description
`line_item_id`	string	`LI123`	Refund item ID
`quantity`	integer	`2`	Refund quantity
`waiting_ship_quantity`	integer	`1`	The refund quantity of waiting shipping goods
`return_inventory`	boolean	`true`	Whether to return inventory

RefundAdditionalPrices

Field	Type	Example	Description
`name`	string	`Handling Fee`	Additional price name
`price`	string	`5.00`	Additional price refund amount

RefundPayment

Field	Type	Example	Description
`payment_line_id`	string	`PAY123`	Refund payment channel ID
`refund_price`	string	`50.00`	Refund amount

Response Description

Public Response Fields

📘
Public Response Parameters

Success Response

RefundOrderResponse

Field	Type	Example	Description
`code`	string	`SUCCESS`	Error code
`message`	string	`Refund processed successfully`	Error message
`data`	object	`{ "refund_record_id": "R12345", "post_sale_id": "A67890" }`	Order refund response data. See `RefundOrderResponse_Data` for details.

RefundOrderResponse_Data

Field	Type	Example	Description
`refund_record_id`	string	`R12345`	Refund record ID
`post_sale_id`	string	`A67890`	After-sales ID

Error Response

Field	Type	Description	Example
`code`	string	The error code indicating the type of issue.	`InvalidParameter`
`message`	string	A detailed message describing the error.	`Order id is required.`

Error Detail

Status Code	Message	Possible Reason	Example Response
400	Bad Request	Invalid input format or request structure (e.g., missing required fields or incorrect data types).	`Bad Request`
	Unauthorized	The request is missing valid authentication credentials or the credentials provided are invalid.	`Unauthorized`