Manage reverse deliveries
A reverse delivery is a set of items to be packaged together and sent back to the merchant or third-party fulfillment service. This guide shows you how to manage reverse deliveries with the GraphQL Admin API.
RequirementsAnchor link to section titled "Requirements"
- Your app can make authenticated requests to the GraphQL Admin API.
- Your app has the
write_returnsaccess scopes. For more information on requesting access scopes when your app is installed, refer to Getting started with OAuth.
- 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 2023-01 or higher.
You've met Shopify's protected customer data requirements.
You're familiar with creating and managing returns.
Step 1: Create a reverse delivery with shipping informationAnchor link to section titled "Step 1: Create a reverse delivery with shipping information"
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.
Step 2: Query a reverse deliveryAnchor link to section titled "Step 2: Query a reverse delivery"
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
Step 3: Dispose reverse delivery line itemsAnchor link to section titled "Step 3: Dispose reverse delivery 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.
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
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.