🔒
Requires write_order access scope. More access scope

The Get Order's Refund Record initiates a refund for a specific order with detailed refund allocation options.

This API is especially useful for:

Processing full or partial order refunds
Managing refunds across multiple payment methods
Handling complex refund scenarios with item-level control

Request Parameters

Public Request Parameters

📘
Public Request Parameters

Path Parameters

Parameter	Type	Required	Description	Example
`order_id`	string	Yes	Unique identifier of the order	`"ord_123456789"`

Body Parameters

Parameter	Type	Required	Description	Example
`refund.refund_total`	string	Yes	Total refund amount	`"100.00"`
`refund.refund_shipping_total`	string	No	Shipping cost to refund	`"10.00"`
`refund.refund_tip`	string	No	Tip amount to refund	`"5.00"`
`refund.refund_additional_total`	string	No	Additional charges to refund	`"15.00"`
`refund.refund_product_total`	string	No	Product subtotal to refund	`"70.00"`
`refund.note`	string	No	Refund reason or notes	`"Customer requested return"`
`refund.refund_line_items[]`	object	No	array of refund_line_items object
`refund.refund_line_items[]. line_item_id`	string	Yes	ID of the order line item	`"li_12345"`
`refund.refund_line_items[]. quantity`	int32	No	Quantity to refund	`1`
`refund.refund_line_items[]. refund_item_type`	int32	No	Default `0` if no value entered. This field determines whether to refund items that are already shipped(`1`), waiting to ship(`2`), or automatically handle both states(`0`). For more details.	`0`
`refund.refund_line_items[]. return_inventory`	boolean	No	Restock inventory. return_inventory should keep same value for one same line item.	`true`
`refund.refund_payments[]`	object	No	array of objects
`refund.refund_payments[]. payment_line_id`	string	Yes	Original payment method ID	`"pay_12345"`
`refund.refund_payments[].refund_price`	string	Yes	Amount to refund via this method	`"50.00"`
`refund.refund_additional_prices[]`	object	No	array of objects
`refund.refund_additional_prices[]. name`	string	Yes	Name of additional charge	`"Gift Wrapping"`
`refund.refund_additional_prices[]. price`	string	Yes	Amount to refund	`"5.00"`

refund_item_type Field

Value

Type

Description

0

Automatic refund

Automatically calculates refund quantities based on fulfillment status.

*Priority**: Refunds unfulfilled items first, then refunds fulfilled items if needed.

1

Refund Shipped items

Refunds only items that have been shipped.

2

Refund unfulfilled items

Refunds only items that are waiting to ship

Usage Rules

Automatic Mode: Use only 0(automatic refund) for automatic handling for the same line item. System will first deduct from unfulfilled quantities.
Manual Mode: Can combine 1 (shipped) and 2 (waiting ship) within a single line item.
Invalid Combinations: Cannot mix 0(automatic refund) with other types for the same line item.

Response Explanation

Public Response Parameters

📘
Public Response Parameters

Successful Response

Parameter	Type	Example	Description
`code`	string	`"success"`	API response status code
`message`	string	`"Refund processed successfully"`	Operation result message
`data.refund_record_id`	string	`"ref_123456789"`	Unique refund transaction ID
`data.post_sale_id`	string	`"ps_123456789"`	After-sales service case ID

Error Response

Field	Type	Example	Description
`code`	string	`InvalidParameter`	Error http message
`message`	string		Error message

200OK