Build for return management

• 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.

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 in the next step.

You can use the returnRequest mutation to create a return with its status set to REQUESTED. This mutation should be used to create returns that need to be approved by the merchant. If you create a return on an archived order, then the order is automatically unarchived.

To request a return, provide the ID of the order and the return line items as input to the mutation. The response returns the return ID and the return's status.

You can use the returnApproveRequest mutation to approve a single requested return. This changes the return's status from REQUESTED to OPEN. Approving the return creates a reverse fulfillment order, and enables you to create a reverse delivery for the reverse fulfillment order.

To approve a request, provide the ID of the return to be approved. The response returns the return ID and the return's status.

You can use the returnDeclineRequest mutation to decline a single requested return. This changes the return's status from REQUESTED to DECLINED. A declined return doesn't have reverse fulfillment orders. As a result, shipping can't be added to the declined return.

You can only decline a return if the return meets the following criteria:

• It must be in a REQUESTED state.
• It can't have been refunded.

To decline a request, provide the ID of the return to be declined. The response returns the return ID and the return's status.

If your workflow involves approving or declining requested returns outside of the Shopify platform, then you should create a return using the returnCreate mutation.

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 does the following:

• It 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.
• It creates a reverse fulfillment order, and enables you to create a reverse delivery for the reverse fulfillment order.
• It creates a sales agreement with a RETURN reason, which links to all sales created for the return/exchange
• It creates sales records that reverse the sales records for the items being returned
• It creates sales records for any exchange line items

The created return is marked as Return in progress in the order details view in the Shopify admin:

When a return is created with exchange items, those 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 see manage fulfillments.

After you've created a return, you can use the return query to retrieve the return by its ID. The response returns the order ID associated with the return and the return's status.

If a customer changes their mind about returning an item, you can remove that item from the return. Removing a return line item will revert that order line item back to being fulfilled and may change the order balance. If you remove the only return line item in the return, the return status will automatically change to CLOSED.

If you create a return by mistake, have an error in the created return, or a customer has changed their mind about wanting to return an item, then you can cancel the return that you've created. Canceling a return restores an order's line items back to being fulfilled. To cancel a return, provide the ID of the return as input to the returnCancel mutation.

You can only cancel a return if the return meets the following criteria:

• It must be in an OPEN state.
• It can't have cancelled fulfillments.
• It can't have been refunded.
• It can't have dispositions.
• It can't have Shopify Shipping return label. Returns with manually-uploaded return labels and manually-provided tracking information (not PDFs) can be canceled.

Returns to Shopify Fulfillment Network (SFN) might be cancelable. If SFN rejects the cancelation request, then a "return failed" description displays in the Shopify admin.

When cancelling a return, you can expect that all sales records generated from the creation of a return will be reversed, nullifying the financial impact of the return on the order. Note: This will not affect the sales generated for exchange line items, nor will it cancel the fulfillments for any exchange line items.

Canceling a return removes it from the order details view in the Shopify admin:

A suggested refund represents a refund that Shopify suggests based on the items being reimbursed. In your query, provide the ID of the return, the ID of the return line item, and the quantity of the line item.

When you refund an order, you send payment back to the customer. Using the returnRefund mutation, you can issue a refund and associated it with the related return. You can refund an entire order or only part of an order.

The refunding behavior of this mutation is similar to the refundCreate mutation. The main difference is that the returnRefund mutation doesn't involve restocking input.

When a merchant or third-party fulfillment service receives a returned item, they can inspect the product to determine whether it's in sellable condition. For example, the product might be stained or missing components.

For health and safety reasons, some products can only be restocked if they are in unopened or brand new condition. If the products are returned in an opened or used condition, then the products are disposed of during inspection.

Depending on your use case, you can do the following:

• If you require a delivery to dispose items, then refer to Manage reverse deliveries.
• If you want to dispose items with no deliveries involved, then refer to Manage reverse fulfillment orders.

You can use the returnClose mutation to close a return at any time. For example, you might want to close a return when a refund has been made and items are restocked, or when items have been marked as returned.

A closed return is marked as Returned in the Shopify admin:

If you need to reopen a closed return, then you can use the returnReopen mutation. You can reopen a return only if it was closed.

As of GraphQL Admin API version 2023-01 and higher, your app can subscribe to webhooks for event notifications related to returns, refunds, reverse fulfillment orders, and reverse deliveries. The following examples show the JSON responses from each of the available webhooks.

To learn how to set up and consume webhooks, refer to Webhooks configuration overview.

• Learn how to manage exchanges with the GraphQL Admin API.
• 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.