Get Suggested Refund

Calculate the suggested refund for an order or return. Supports two workflows: (1) direct refund from an order with specified line items, or (2) refund after a return where line items and totals are pre-calculated from the return.

Required fields:

  • order_id or return_id (one must be provided)

A successful request returns the suggested refund details for the specified order or return.

For Shopify:

  • With a return_id, the amounts are Shopify's suggested outcome for the whole order (financial_outcome), with or without exchange items. As in
    the Shopify admin, the items are first netted against what the order already owes.
  • With only an order_id, the amounts are the full value of the selected items. They are not netted against what the order owes.

Returns with exchange items (return_id only):

  • Send the exchange items in exchange_line_items, together with the return line items in refund_line_items, to see what processing them together
    would do. Their prices are netted, and financial_outcome tells whether money is refunded (REFUND), the customer owes money (INVOICE), or nothing
    is owed either way (EVEN).
  • financial_outcome is for the whole order: the items are first netted against what the order already owes. The restocking fees and the return
    shipping fees are already taken out of it.
  • Without exchange_line_items, only the return line items are calculated, and return_context.exchange_line_items still lists the exchange
    items left to process. A return line item quantity above what is left to process makes the request fail with 400 while
    the return still has exchange items to process; for a return without them, the quantity is lowered to what is left instead.
  • The display data of the exchange items (title, variant_title, sku, image_url, unit_price) comes from the synced product catalog.
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

Scope

erc-ecommerce-return:read

Body Params

Suggested refund request containing either an order ID with line items, or a return ID.

The suggested refund request body.

string
length between 1 and 255

The order ID to calculate the suggested refund for. Either order_id or return_id must be provided.

string
length between 1 and 255

The return ID to calculate the suggested refund for. Either order_id or return_id must be provided.

string
length between 1 and 255

The brand identifier. If the account is multi-brand, this parameter is required.

refund_line_items
array of objects

The line items to include in the suggested refund calculation. With a return_id and no exchange_line_items, an omitted or empty refund_line_items includes every return line item with a quantity left to process. When exchange_line_items is not empty, an omitted or empty refund_line_items includes no return line items, so that only the exchange items are calculated. A requested quantity above what is left to process is lowered to what is left, and line items with nothing left are left out, unless the return still has exchange items to process: then the request is rejected with 400.

refund_line_items
exchange_line_items
array of objects

The exchange items of the return to calculate together with the return line items, so that their prices are netted. Only with a return_id; a request with only an order_id and exchange items is rejected. When it is omitted or empty, no exchange item is included. For Shopify, every item must be an exchange item of the return with a quantity left to process. Custom integrations receive it as is.

exchange_line_items
number
> 0

The shipping amount to refund. Must be positive.

boolean

Whether to include shipping in the refund.

refund_duties
array of objects

The duties to include in the refund.

refund_duties
boolean

Whether to suggest a full refund for the order.

Responses

Language
Credentials
OAuth2
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json