Requires
read_orderaccess scope. More access scope
The Refund List by Order API retrieves all refund records associated with a specific order ID. This enables merchants to track refunds for individual orders and analyze refund details.
This API is especially useful for:
- Fetching refunds related to a specific order.
- Analyzing refund history and details for troubleshooting or reporting.
- Ensuring all refunds are accounted for at the order level.
Notice
The fields
refund_status,all_refunded,refund_total,refund_discount_total, andrefund_tax_totalin the interface response are deprecated. To ensure compatibility with the old versions, we will not delete it, only return default values。
Domain Object Map
Example
Tax-inclusive scenario(order.config.product_tax_included=true)
A customer placed an order for 2 iPhones, with the product's original price (product.price) being $50 (the $50 already includes tax).
The total tax for the order (total_tax) is $20 (this is independent of order.config.product_tax_included and is calculated by the tax service), so the total amount of the order excluding tax is $80.
The total discount (total_discount) is $40.
So, the order's subtotal (order.sub_total) is $100, which is the sum of the total price of each line item (sum(line_item.total_price) = sum(line_item.price * line_item.quantity)).
The actual payment (total_price) is $60 (2 iPhones at $50 each minus the $40 discount).
Now, for this order, a refund is being processed:
The refund amount (refund_price) is $40 (this is because the refund amount is something the buyer can input).
The total amount of the refund line item (RefundLineItem.total) is $40 (since there is only one product, there is no need to further apportion the refund).
The subtotal of the refund line item (RefundLineItem.SubTotal) is calculated as follows: ($50 * 2) - ($40 / $60).
The tax of the refund line item (RefundLineItem.tax) is calculated as: ($20 * $40) / $60.
Non tax-inclusive scenario(order.config.product_tax_included=false)
A customer placed an order for 2 iPhones, with the product's original price being $50 (the $50 is the price before tax).
The total tax for the order (total_tax) is $20 (this is independent of order.config.product_tax_included and is calculated by the tax service).
The total discount (total_discount) is $40.
So, the order's subtotal (order.sub_total) is $100 (calculated as the sum of the total price of each line item: sum(line_item.total_price) = sum(line_item.price * line_item.quantity)).
The actual payment (total_price) is $80 (calculated as 2 iPhones at $50 each, plus tax of $20, minus the $40 discount: 50*2 + 20 - 40 = 80).
Now, for this order, a refund is being processed:
The refund amount (refund_price) is $40 (the reason it's $40 is because the refund amount is something the buyer can input).
The total amount of the refund line item (RefundLineItem.total) is $40 (since there is only one type of product, there is no need to further apportion the refund).
The subtotal of the refund line item (RefundLineItem.SubTotal) should be calculated as follows: (50 * 2 - 40) / 80 = 50.
The tax of the refund line item (RefundLineItem.tax) should be calculated as: (20 * 40) / 80 = 10.
Request Parameters
Public Request Parameters
Path Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
id | string | Yes | The unique ID of the order. | 1232123 |
Response Description
Public Response Fields
Success Response
| Field | Type | Description | Example |
|---|---|---|---|
all_refunded | boolean | Indicates whether all items in the order have been refunded. | false |
order_financial_status | string | the payment status of order | partially_refunded |
order_status | string | the status of order | finished |
refund_discount_total | string | Total discount amount refunded. | @Deprecated. |
refund_status | string | Overall refund status for the order. | @Deprecated. |
refund_tax_total | string | Total tax amount refunded. | @Deprecated. |
refund_total | string | Total refund amount. | @Deprecated. |
refunds | array | Array of Refunds | |
refunds[].id | string | Unique ID for the refund record. | 402390816770768890 |
refunds[].created_at | string | Timestamp when the refund record was created (ISO 8601 format). | 2024-07-15T09:17:26Z |
refunds[].currency | string | Currency in which the refund was made. | USD |
refunds[].note | string | Additional note about the refund. | "" |
refunds[].order_id | string | Associated order ID. | 10234-00020257 |
refunds[].payment_details | array | Details of payments related to the refund. | |
refunds[].payment_details[].finished_at | string | Timestamp when the refund was completed. | 2024-07-15T09:17:28Z |
refunds[].payment_details[].payment_channel | string | Payment channel used for the refund. | stripe |
refunds[].payment_details[].payment_method | string | Payment method used for the refund. | credit_card |
refunds[].payment_details[].refund_price | string | Amount refunded via the payment method. | 14.83 |
refunds[].refund_line_items | array | Details of refund line items. | |
refunds[].refund_line_items[].discount | string | Discount applied to the line item. | 1.00 |
refunds[].refund_line_items[].line_item | object | Details of the refunded array of LineItem | |
refunds[].refund_line_items[].line_item.base_price | string | Base price of the product. | 0.00 |
refunds[].refund_line_items[].line_item.compare_at_price | string | Original price of the product before discount. | 15.99 |
refunds[].refund_line_items[].line_item.discount_applications | string | Discount applications associated with the line item. | JSON string describing discounts |
refunds[].refund_line_items[].line_item.fulfillment_status | string | Fulfillment status of the line item. | returned |
refunds[].refund_line_items[].line_item.id | string | Unique ID of the line item. | df111f19-b1f2-4ffc-b293-743a432f9f64 |
refunds[].refund_line_items[].line_item.price | string | Price of the line item after discounts. | 15.83 |
refunds[].refund_line_items[].line_item.product_title | string | Title of the refunded product. | (Counted/Stamped)(Big Size) 11CT Ginkgo biloba- Cross Stitch 60*60cm/23.62*23.62in |
refunds[].refund_line_items[].line_item.properties | array | Properties of the refunded product, such as size or style. | Array of property objects |
refunds[].refund_line_items[].refund_quantity | integer | Quantity refunded for the line item. | 1 |
refunds[].refund_line_items[].total | string | Total amount refunded for the line item. | 14.83 |
refunds[].refund_method | string | Method used for the refund. | general |
refunds[].refund_price | string | Total refund amount. | 14.83 |
refunds[].refund_shipping | string | Refund amount for shipping. | 0.00 |
refunds[].refund_shipping_tax | string | Refund amount for shipping tax. | 0.00 |
refunds[].refund_status | string | Refund status (pending, finished, failed). | finished |
refunds[].updated_at | string | Timestamp when the refund record was last updated (ISO 8601 format). | 2024-07-15T09:17:28Z |
| 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 | |
| 422 | Unprocessable Entity | ID is invalid or empty | "Invalid ID" |
| 404 | Not Found | The Id provided is not found | Unable to find resource |