API to purchase return labels via Shopify

Technical Q&A
1

I want to automate return-label purchase via API — equivalent to what “Create a return label in Shopify” does manually in admin today.

reverseDeliveryCreateWithShipping only accepts a pre-bought label URL, and I can’t find a shippingLabelCreate or buyShipping mutation in the Admin API. How do I purchase a return label programmatically?

2

Hi @gunner52

This is Vineet from Identixweb, a Shopify Development Agency.

You can’t currently purchase a Shopify Shipping return label programmatically through the Admin API.

The “create a return label in shopify” option in the admin is still an admin-side shopify Shipping flow. Shopify has return APIs, but they don’t expose a shippingLabelCreate, buyShipping, or equivalent mutation to buy postage/return labels directly through shopify Shipping. Shopify’s docs only show return label creation from the order page in admin or the Shopify app.

reverseDeliveryCreateWithShipping is not a label-purchase API. It lets you attach external shipping information to a reverse delivery, including tracking details and a label file URL. Shopify’s developer docs describe it as creating a reverse delivery with associated external shipping information, and the mutation accepts trackingInput and labelInput.fileUrl.

So the practical workflow is:

Create or approve the return in Shopify.
Get the reverseFulfillmentOrderId.
Buy the return label from a carrier/label API like Shippo, EasyPost, ShipStation, your 3PL, or your carrier account.
Upload or host the label PDF.
Call reverseDeliveryCreateWithShipping with the tracking number, tracking URL, and label file URL.
Set notifyCustomer: true if you want Shopify to email the customer return instructions.

Example structure:

</>Graph QL

mutation reverseDeliveryCreateWithShipping(
$reverseFulfillmentOrderId: ID!,
$reverseDeliveryLineItems: [ReverseDeliveryLineItemInput!]!,
$trackingInput: ReverseDeliveryTrackingInput,
$labelInput: ReverseDeliveryLabelInput,
$notifyCustomer: Boolean
) {
reverseDeliveryCreateWithShipping(
reverseFulfillmentOrderId: $reverseFulfillmentOrderId,
reverseDeliveryLineItems: $reverseDeliveryLineItems,
trackingInput: $trackingInput,
labelInput: $labelInput,
notifyCustomer: $notifyCustomer
) {
reverseDelivery {
id
}
userErrors {
field
message
}
}
}

Variables:

{
“reverseFulfillmentOrderId”: “gid://shopify/ReverseFulfillmentOrder/123”,
“reverseDeliveryLineItems”: [ ],
“trackingInput”: {
“number”: “TRACKING123”,
“url”: “https://carrier-tracking-url.com/TRACKING123”
},
“labelInput”: {
“fileUrl”: “https://your-label-url.com/return-label.pdf”
},
“notifyCustomer”: true
}

3

Thank you for the reponse

4

Shopify does not expose a native API to purchase return labels programmatically, there is no shippingLabelCreate or buyShipping mutation available. The admin UI flow for buying return labels is not replicated in the API yet.

Your only option right now is to buy the label externally through EasyPost, Shippo, or your carrier directly, then attach it to the return using reverseDeliveryCreateWithShipping with the label URL and tracking details.