Skip to main content

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.

Anchor to RequirementsRequirements

Anchor to Step 1: Create a reverse delivery with shipping informationStep 1: Create a reverse delivery with shipping information

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.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation reverseDeliveryCreateWithShippingMutation {
reverseDeliveryCreateWithShipping(
# The ID of the reverse fulfillment order that's associated to the reverse delivery.
reverseFulfillmentOrderId: "gid://shopify/ReverseFulfillmentOrder/1",
# The reverse delivery line items to be created. If an empty array is provided, then this mutation will create a reverse delivery line item for each reverse fulfillment order line item. The quantity of the reverse delivery line items equals the quantity of the reverse fulfillment order line item total.
reverseDeliveryLineItems: [
{
# The ID of the reverse fulfillment order line item.
reverseFulfillmentOrderLineItemId: "gid://shopify/ReverseFulfillmentOrderLineItem/1",
# The quantity of items associated with the reverse fulfillment order line item.
quantity: 1
}
],
# For return label files, the `labelInput` can be used to pass in label file related attributes.
trackingInput: {
# The tracking number for the label.
number: "123456789",
# The tracking URL for the carrier. If a carrier that's not supported by Shopify is used, then you must provide the tracking URL of the delivery.
url: "https://example-carrier.com/123456789"
},
# Send an email notification to the customer with the reverse delivery instructions.
# The reverse delivery is associated to the `ReverseFulfillmentOrder` object, specified by the `reverseFulfillmentOrderId`.
# If `notifyCustomer` is set to `true`, then `ReverseFulfillmentOrder.order.email` is required.
notifyCustomer: true
) {
reverseDelivery {
id
reverseDeliveryLineItems(first: 10) {
edges {
node {
id
quantity
}
}
}
deliverable {
... on ReverseDeliveryShippingDeliverable {
tracking {
number
url
}
}
}
}
userErrors {
field
message
}
}
}

JSON response

{
"data": {
"reverseDeliveryCreateWithShipping": {
"reverseDelivery": {
"id": "gid://shopify/ReverseDelivery/1",
"reverseDeliveryLineItems": {
"edges": [
{
"node": {
"id": "gid://shopify/ReverseDeliveryLineItem/1",
"quantity": 1
}
}
]
},
"deliverable": {
"tracking": {
"number": "123456789",
"url": "https://example-carrier.com/123456789"
}
},
"userErrors": []
}
}
}
}

Anchor to Step 2: Query a reverse deliveryStep 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 query:

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL query

query reverseDeliveryQuery {
# The ID of the reverse delivery.
reverseDelivery(id: "gid://shopify/ReverseDelivery/1") {
id
status
# The deliverable associated with the reverse delivery.
deliverable {
... on ReverseDeliveryShippingDeliverable {
label {
publicFileUrl
}
tracking {
carrierName
number
}
}
}
# The reverse delivery line items attached to the reverse delivery.
reverseDeliveryLineItems(first: 10) {
nodes {
id
quantity
reverseFulfillmentOrderLineItem {
# Use this ID to dispose reverse delivery line items in Step 3.
id
quantity
}
}
}
}
}

JSON response

{
"data": {
"reverseDelivery": {
"id": "gid://shopify/ReverseDelivery/1",
"status": "INSPECTED",
"deliverable": {
"label": {
"publicFileUrl": "https://example.com/label/1"
},
"tracking": {
"carrierName": "USPS",
"number": "111111111"
}
},
"reverseDeliveryLineItems": {
"nodes": [
{
"id": "gid://shopify/ReverseDeliveryLineItem/1",
"quantity": 2,
"reverseFulfillmentOrderLineItem": {
"id": "gid://shopify/ReverseFulfillmentOrderLineItem/1",
"quantity": 3
}
}
]
}
}
}
}

Anchor to Step 3: Dispose reverse delivery line itemsStep 3: Dispose reverse delivery line items

Deprecated

reverseDeliveryDispose will be deprecated as of the 2025-01 Admin GraphQL API version. Please use the reverseFulfillmentOrderDispose 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 mutation to dispose reverse delivery line items. This mutation enhances the existing restocking capability for refunds.

Note

To dispose a reverse delivery line item using reverseFulfillmentOrderDispose, you need the reverse fulfillment order line item ID. Consult a sample query 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 enum.

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation reverseFulfillmentOrderDispose {
reverseFulfillmentOrderDispose (
# The input parameters required to dispose reverse fulfillment order line items.
dispositionInputs: [
{
# The ID of the reverse fulfillment order line item.
# Use the field `ReverseDeliveryLineItem.reverseFulfillmentOrderLineItem` to find
# the reverse fulfillment order line item ID of a reverse delivery line item.
reverseFulfillmentOrderLineItemId: "gid://shopify/ReverseFulfillmentOrderLineItem/1",
# The quantity of the reverse fulfillment order line item to dispose.
quantity: 2,
# The final arrangement for the reverse fulfillment order line item. A `dispositionType` of `RESTOCKED` means that the item was restocked. The quantity of available inventory is incremented, and the item can't be returned again.
dispositionType: RESTOCKED,
# The ID of the location where the reverse fulfillment order line item is to be disposed. This is required when the disposition type is `RESTOCKED`.
locationId: "gid://shopify/Location/1",
},
}
# The ID of the reverse fulfillment order line item.
# Use the field `ReverseDeliveryLineItem.reverseFulfillmentOrderLineItem` to find
# the reverse fulfillment order line item ID of a reverse delivery line item.
reverseFulfillmentOrderLineItemId: "gid://shopify/ReverseFulfillmentOrderLineItem/2",
# The quantity of the reverse fulfillment order line item to dispose.
quantity: 1,
# A `dispositionType` of `PROCESSING_REQUIRED` means that the merchant received an item that requires further processing before being restocked or discarded.
dispositionType: PROCESSING_REQUIRED,
}
]
) {
# The disposed reverse fulfillment order line items.
reverseFulfillmentOrderLineItems {
id
dispositions {
location {
id
name
}
quantity
type
}
totalQuantity
}
userErrors {
field
message
}
}
}

JSON response

{
"data": {
"reverseFulfillmentOrderDispose": {
"reverseFulfillmentOrderLineItems": [
{
"id": "gid://shopify/ReverseFulfillmentOrderLineItem/1",
"dispositions": [
{
"location": {
"id": "gid://shopify/Location/1",
"name": "Store warehouse"
},
"quantity": 2,
"type": "RESTOCKED"
}
],
"totalQuantity": 2
},
{
"id": "gid://shopify/ReverseFulfillmentOrderLineItem/2",
"dispositions": [
{
"location": null,
"quantity": 1,
"type": "PROCESSING_REQUIRED"
}
],
"totalQuantity": 1
}
],
"userErrors": []
}
}
}

Anchor to WebhooksWebhooks

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.

Note

Return webhooks are available only in the GraphQL Admin API.

reverse_deliveries/attach_deliverable webhook response

{
"id": 2,
"admin_graphql_api_id": "gid://shopify/ReverseDelivery/2",
"return": {
"id": 3,
"admin_graphql_api_id": "gid://shopify/Return/3"
},
// To consume the webhook data and display return labels to buyers, you need the following information for return labels:
// - Supported file type(s)
// - Supported file size
// - URL prefix (for URL allow lists)
"shipping_deliverable": {
"label": {
"public_file_url": "https://www.example-host.com/label/1",
"created_at": "2022-05-18T10:28:33-04:0"
},
"tracking": {
"carrierName": "EX",
"tracking_number": "ABC11111111",
"tracking_url": "https://www.example-carrier.com/track/ABC11111111"
}
}
}
Was this page helpful?