Refund List By Order

🔒

Requires read_order access 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:

  1. Fetching refunds related to a specific order.
  2. Analyzing refund history and details for troubleshooting or reporting.
  3. Ensuring all refunds are accounted for at the order level.

🚧

Notice

The fields refund_status, all_refunded, refund_total, refund_discount_total, and refund_tax_total in 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

📘

Public Request Parameters

Path Parameters

ParameterTypeRequiredDescriptionExample
idstringYesThe unique ID of the order.1232123

Response Description

📘

The relationships between entities.

Public Response Fields

📘

Public Response Parameters

Success Response

Field Type Description Example
all_refundedbooleanIndicates whether all items in the order have been refunded.false
order_financial_statusstringthe payment status of orderpartially_refunded
order_statusstringthe status of orderfinished
refund_discount_totalstringTotal discount amount refunded.@Deprecated.
refund_statusstringOverall refund status for the order.@Deprecated.
refund_tax_totalstringTotal tax amount refunded.@Deprecated.
refund_totalstringTotal refund amount.@Deprecated.
refundsarrayArray of Refunds
refunds[].
id
stringUnique ID for the refund record.402390816770768890
refunds[].
created_at
stringTimestamp when the refund record was created (ISO 8601 format).2024-07-15T09:17:26Z
refunds[].
currency
stringCurrency in which the refund was made.USD
refunds[].
note
stringAdditional note about the refund.""
refunds[].
order_id
stringAssociated order ID.10234-00020257
refunds[].
payment_details
arrayDetails of payments related to the refund.
refunds[].
payment_details[].
finished_at
stringTimestamp when the refund was completed.2024-07-15T09:17:28Z
refunds[].
payment_details[].
payment_channel
stringPayment channel used for the refund.stripe
refunds[].
payment_details[].
payment_method
stringPayment method used for the refund.credit_card
refunds[].
payment_details[].
refund_price
stringAmount refunded via the payment method.14.83
refunds[].
refund_line_items
arrayDetails of refund line items.
refunds[].
refund_line_items[].
discount
stringDiscount applied to the line item.1.00
refunds[].
refund_line_items[].
line_item
objectDetails of the refunded array of LineItem
refunds[].
refund_line_items[].
line_item.base_price
stringBase price of the product.0.00
refunds[].
refund_line_items[].
line_item.compare_at_price
stringOriginal price of the product before discount.15.99
refunds[].
refund_line_items[].
line_item.discount_applications
stringDiscount applications associated with the line item.JSON string describing discounts
refunds[].
refund_line_items[].
line_item.fulfillment_status
stringFulfillment status of the line item.returned
refunds[].
refund_line_items[].
line_item.id
stringUnique ID of the line item.df111f19-b1f2-4ffc-b293-743a432f9f64
refunds[].
refund_line_items[].
line_item.price
stringPrice of the line item after discounts.15.83
refunds[].
refund_line_items[].
line_item.product_title
stringTitle 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
arrayProperties of the refunded product, such as size or style.Array of property objects
refunds[].
refund_line_items[].
refund_quantity
integerQuantity refunded for the line item.1
refunds[].
refund_line_items[].total
stringTotal amount refunded for the line item.14.83
refunds[].
refund_method
stringMethod used for the refund.general
refunds[].
refund_price
stringTotal refund amount.14.83
refunds[].
refund_shipping
stringRefund amount for shipping.0.00
refunds[].
refund_shipping_tax
stringRefund amount for shipping tax.0.00
refunds[].
refund_status
stringRefund status (pending, finished, failed).finished
refunds[].
updated_at
stringTimestamp when the refund record was last updated (ISO 8601 format).2024-07-15T09:17:28Z

Status CodeMessagePossible ReasonExample Response
400Bad RequestInvalid input format or request structure (e.g., missing required fields or incorrect data types).Bad Request
UnauthorizedThe request is missing valid authentication credentials or the credentials provided are invalid.Unauthorized
422Unprocessable EntityID is invalid or empty"Invalid ID"
404Not FoundThe Id provided is not foundUnable to find resource

API Details

Language
Credentials
Header
URL
Click Try It! to start a request and see the response here!