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. ## Requirements - Your app can make [authenticated requests](/docs/api/admin-graphql#authentication) to the GraphQL Admin API. - Your app has the `read_returns` and `write_returns` [access scopes](/docs/api/usage/access-scopes). Learn how to [configure your access scopes using Shopify CLI](/docs/apps/build/cli-for-apps/app-configuration). - Your store has existing [orders](/docs/api/admin-graphql/latest/objects/Order) 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](/docs/apps/build/orders-fulfillment/order-management-apps/edit-orders). - You're using API version `2024-07` or higher. - You've met Shopify's [protected customer data requirements](/docs/apps/launch/protected-customer-data). - You're familiar with [creating and managing returns](/docs/apps/build/orders-fulfillment/returns-apps/build-return-management). ## Step 1: Create a reverse delivery with shipping information [Creating a return](/docs/apps/build/orders-fulfillment/returns-apps/build-return-management#step-4-optional-create-a-return) or [approving a return](/docs/apps/build/orders-fulfillment/returns-apps/build-return-management#approve-a-request) creates a [reverse fulfillment order](/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-fulfillment-orders), and enables you to create a reverse delivery for it. You can use the [`reverseDeliveryCreateWithShipping`](/docs/api/admin-graphql/latest/mutations/reverseDeliveryCreateWithShipping) mutation to create a new reverse delivery with associated external shipping information. This mutation supports temporary URLs generated by the [`stagedUploadsCreate`](/docs/api/admin-graphql/latest/mutations/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](/docs/apps/build/online-store/product-media#step-1-upload-media-to-shopify).

## 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 [`reverseDelivery`](/docs/api/admin-graphql/latest/queries/reverseDelivery) query:

## Step 3: Dispose reverse delivery line items > Deprecated: > `reverseDeliveryDispose` will be deprecated as of the 2025-01 Admin GraphQL API version. Please use the [`reverseFulfillmentOrderDispose`](/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-fulfillment-orders#step-2-dispose-a-reverse-fulfillment-orders-line-items) mutation instead. 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`](/docs/api/admin-graphql/latest/mutations/reverseFulfillmentOrderDispose) mutation to dispose reverse delivery line items. This mutation enhances the [existing restocking capability for refunds](/docs/api/admin-graphql/latest/objects/RefundLineItem). > Note: > To dispose a reverse delivery line item using [`reverseFulfillmentOrderDispose`](/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-fulfillment-orders#step-2-dispose-a-reverse-fulfillment-orders-line-items), you need the reverse fulfillment order line item ID. [Consult a sample query](/docs/apps/build/orders-fulfillment/returns-apps/manage-reverse-deliveries#step-2-query-a-reverse-delivery) to learn how. 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`](/docs/api/admin-graphql/latest/enums/ReverseFulfillmentOrderDispositionType) enum.

## Webhooks 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](/docs/apps/build/webhooks/subscribe). > Note: > Return webhooks are available only in the GraphQL Admin API.