Manage reverse fulfillment orders

A reverse fulfillment order represents the work that's required to process a return. It includes one or more items in a return that will be processed by the merchant or third-party fulfillment service.

This guide shows you how to manage reverse fulfillment orders with the GraphQL Admin API.

Requirements

Anchor link to section titled "Requirements"

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.
You're familiar with creating and managing returns.

Step 1: Query a reverse fulfillment order

Anchor link to section titled "Step 1: Query a reverse fulfillment order"

A reverse fulfillment order is a group of one or more items in a return that will be processed by a merchant or a third-party fulfillment service. Creating a return or approving a return creates a reverse fulfillment order. There can be more than one reverse fulfillment order for a return at a given location.

To retrieve the details associated with a reverse fulfillment order, provide the ID of the reverse fulfillment order in the reverseFulfillmentOrder query. The response returns the IDs of the reverse fulfillment order line items, which you'll use as input in the next step.

Step 2: Dispose a reverse fulfillment order's line items

Anchor link to section titled "Step 2: Dispose a reverse fulfillment order's line items"

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.

If you want to dispose items with no deliveries involved, then you can use the reverseFulfillmentOrderDispose mutation. The reverseFulfillmentOrderDispose mutation enables you to dispose reverse fulfillment order line items for a reverse fulfillment order on the same shop. This mutation enhances the existing restocking capability for refunds.

You can only dispose reverse fulfillment orders once on every unit of each item. For example, if there's a hat with a quantity of four, then you can do four dispositions at most, not one disposition for all four items.

After a disposition is made, your app can't update the disposition. To learn about the available disposition types, refer to the reverseFulfillmentOrderDispositionType enum.

Webhooks

Anchor link to section titled "Webhooks"

As of GraphQL Admin API version 2023-01 and higher, your app can subscribe to the reverse_fulfillment_orders/dispose webhook to get notified when a disposition has been made on a reverse fulfillment order. This includes dispositions made on reverse deliveries that are associated with the reverse fulfillment order.

The following example shows the JSON response for the reverse_fulfillment_orders/dispose webhook. To learn how to set up and consume webhooks, refer to Webhooks configuration overview.

Next steps

Anchor link to section titled "Next steps"

Learn how to manage reverse deliveries with the GraphQL Admin API.