Manage reverse deliveries

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

Creating a return or approving a return creates a reverse fulfillment order, and enables you to create a reverse delivery for it.

You can use the reverseDeliveryCreateWithShipping mutation to create a new reverse delivery with associated external shipping information.

This mutation supports temporary URLs generated by the stagedUploadsCreate mutation. The file asset is uploaded when you call the reverseDeliveryCreateWithShipping mutation with the staged upload target URL. For examples of how to use the stageddUploadsCreate mutation, refer to Upload media to Shopify.

A reverse delivery contains the context of the items sent back, and how they're being sent back. For example, items might be sent back with a shipping label and tracking information.

A reverse delivery doesn't include package tracking information. For example, an app can't query if an item is in transit, if a shipping label has been scanned, or if the item has been delivered to a third-party fulfillment service or merchant.

You can have more than one reverse delivery for a single return. For example, if a couch is being returned but it needs to be put into several boxes for shipping, then it's one return with multiple return deliveries.

To retrieve a reverse delivery, pass the ID of the reverse delivery to the reverseDelivery query:

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.

You can use the reverseFulfillmentOrderDispose mutation to dispose reverse delivery line items. This mutation enhances the existing restocking capability for refunds.

You can only dispose reverse deliveries 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.

As of GraphQL Admin API version 2023-01 and higher, your app can subscribe to the reverse_deliveries/attach_deliverable to get notified when a deliverable is attached to a reverse delivery. A deliverable can be attached when a reverse delivery is created or updated with delivery metadata. Metadata includes the delivery method, label, and tracking information that's associated with a reverse delivery.

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