• Your app can make authenticated requests to the GraphQL Admin API.
• Your app has the read_returns and write_returns access scopes. Learn how to configure your access scopes using Shopify CLI.
• Your store has existing orders that have been fulfilled. You can return only items that have been fulfilled. If you need to make changes to an unfulfilled item, then you can edit an order.
• You're using API version 2024-07 or higher.
• You've met Shopify's protected customer data requirements.

Exchanges are applied to a returnable fulfillment. A returnable fulfillment is an order that has been delivered and is eligible to be returned to the merchant or third-party fulfillment service.

To retrieve the fulfillment line items that can be returned in an order, provide the ID of the order in the returnableFulfillments query. The response returns the fulfillment line item ID, which you'll use as input to create a return.

You can use the returnCalculate query to calculate financial data for an exchange with given inputs. The query doesn't create the return or the exchange. It only calculates the financial impact of a return if the return was created with the same inputs. Exchange line items are sent as input, alongside the return line items.

You can create a return from an existing order that has at least one fulfilled line item that hasn't yet been refunded. If you create a return on an archived order, then the order is automatically unarchived.

The returnCreate mutation with exchange line items input does the following:

• Creates a return in the OPEN state, and assumes that the return request from the customer has already been approved. You should only create a return if the merchant's intent is to approve a customer’s return request.
• Creates a reverse fulfillment order, and enables you to create a reverse delivery for the reverse fulfillment order
• Creates a sales agreement with a RETURN reason, which links to all sales created for the return or exchange
• Creates sales records that reverse the sales records for the items being returned
• Creates sales records for any exchange line items
• Places the fulfillment order with the exchange line items on hold

When a return is created with exchange items, the exchange items will create fulfillment orders with an ON_HOLD status and AWAITING_RETURN_ITEMS as the fulfillment hold reason. For more information on managing fulfillments, refer to build for fulfillments services.

If a balance is due on the exchange, then you can use the orderInvoiceSend mutation to send an updated invoice to the customer prior to releasing the hold on the exchange.

To fulfill the item for the exchange, you need to release the hold on the fulfillment order by querying for the ID of the fulfillment order that contains the hold.

To retrieve the fulfillment order ID, provide the ID of the order in the order query. The response returns the fulfillmentOrders which you can filter to locate the fulfillment order with a status of ON_HOLD and a fulfillmentHold with a reason of AWAITING_RETURN_ITEMS. You'll use the ID of that fulfillmentOrder to release the hold in the next step.

After a payment has been received, you can use the fulfillmentOrderReleaseHold mutation to release the item for the exchange so that it can be fulfilled.

After the hold has been released, you can fulfill the item using the fulfillmentOrderSubmitFulfillmentRequest or fulfillmentCreateV2 mutation mutation.

• Learn how to preview and refund duties with the GraphQL Admin API.
• Learn how to manage reverse fulfillment orders with the GraphQL Admin API.
• Learn how to manage reverse deliveries with the GraphQL Admin API.