Process return and create refund

Process a return and create a refund for the associated order. This endpoint finalizes the return flow by issuing a refund tied to an existing return.

Required fields:

  • order_id
  • return_id

A successful request that refunds money returns 201 with the created refund details for the specified order. When nothing is refunded, it
returns 200 with process_return_response instead.

For Shopify, what happens to the money is Shopify's suggested outcome for the whole order, the same as financial_outcome of the suggested
refund: the return line items, and the exchange items if any, are first netted against what the order already owes. So a return can refund
less than its items are worth, refund nothing, or leave the customer owing money, with or without exchange items.

Processing a return:

  • Send the exchange items in exchange_line_items, together with the return line items in refund_line_items, to process them in one request so
    that their prices are netted.
  • When money is refunded (REFUND), the response is 201 with the refund, return_id, return_status, financial_outcome and exchange_line_items:
    the exchange items of the return, with how much of each is processed so far.
  • When the customer owes money (INVOICE) or nothing is owed either way (EVEN), nothing is refunded and the response is 200 with
    process_return_response. For an INVOICE with notify set to true, Shopify's invoice for the order is emailed to the customer.
  • Shopify closes the return by itself a moment after everything in it is processed, so return_status can still read OPEN.
  • When money is refunded and transactions are omitted, the transactions Shopify suggests are used. When Shopify suggests one without a parent
    transaction, the request fails with 502 and nothing is processed; send the transactions instead.
  • Without exchange_line_items, refund_line_items is required and only the return line items are processed. A return that still has exchange
    items stays open, and they are listed in pending_exchange_line_items. Processing the exchange items in a later request does not net them with
    the return line items processed before: they are then charged in full.
  • Requests for Shopify are rejected with 400 when the return is not open or when a quantity is more than is left to process, with or without
    exchange_line_items, and when transactions are sent and no refund is due.
  • Custom integrations receive the request as is.
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

Scope

erc-ecommerce-return:write

Body Params

Process return refund request containing order ID, return ID, line items, and payment details.

The process return and refund request body.

string
required
length between 1 and 255

The order ID to create the refund for.

string
required
length between 1 and 255

The return ID to process and refund. This field is required.

string
length between 1 and 255

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

boolean

Whether to notify the customer about the refund. When it is true and the customer owes money (INVOICE), Shopify's invoice for the order is emailed instead.

string
length between 3 and 3

The currency code for the refund.

refund_line_items
array of objects

The line items to refund. Required when exchange_line_items is omitted or empty. For Shopify, the return must be open and no quantity can be more than is left to process. When exchange_line_items is not empty, an omitted or empty refund_line_items processes only the exchange items. A line item with restock_type RETURN and a location_id is restocked at that location.

refund_line_items
transactions
array of objects

The payment transactions for the refund. For Shopify, each needs a parent_id, and they are only used when money is refunded: their amounts must be positive and add up to no more than can be refunded, and when they are omitted, the transactions Shopify suggests are used. When no refund is due they must be omitted.

transactions
exchange_line_items
array of objects

The exchange items of the return to process together with the return line items, so that their prices are netted. The money outcome is Shopify's, for the whole order (see financial_outcome). When it is omitted or empty, only the return line items are processed, and a return that still has exchange items stays open. Processing the return line items and the exchange items in separate requests does not net their prices against each other: the exchange items are then charged in full. For Shopify, the return must be open and every quantity must be left to process. Custom integrations receive it as is.

exchange_line_items
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