I am excited about the ability to purchase a shipping label from Shopify - this allows our app to ship orders while sidestepping a lot of complexities and integrations. However, there’s no query to get shipping rates, carriers, etc - this mutation appears almost stranded as I can’t imagine the use case, currently. Who wants to buy a shipping label without knowing the service or cost ahead of time?
From the docs:
Hey @Ariel_Lezen - thanks for raising this.
I did some digging here, and you’re right. There isn’t a public Admin API query today to fetch available shipping label rates, carriers, or service options before calling shippingLabelPurchase.
With the current API, the use for the mutation is to omit preferredRateSelection and let Shopify select the cheapest available rate and corresponding carrier/service at purchase time. If a preferred carrier/service is provided, it has to match a valid carrierCode/serviceCode pair for that shipment, but there isn’t a companion public discovery endpoint for those values today. I’ve made sure to raise this internally and this has sparked a useful discussion.
We would definitely be open to hearing for detailed feedback about your use case. Could you share a bit more about what your app is looking for to assist in making a decision before purchase? For example, are you trying to show the merchant a choice, apply a carrier/service policy, avoid labels above a price threshold, support batch fulfilment, or handle something else?
For the time being, merchants who need to compare live label rates before purchase need to use the Shopify admin label purchase flow/rates calculator, while API-based automation is best suited to workflows where Shopify choosing the cheapest available rate is acceptable.
I hope this helps a little and looking forward to hearing back from you!
Thanks for the prompt response, Wes!
Our app helps users verify order contents, select packaging and ship the order. We implement an industry-specific workflow that is much more efficient, and we also provide user-level traceability on who picked and who verified and who shipped an order as it progresses throughout the warehouse.
The missing piece in our workflow, which we are implementing with the Shipstation API, is to actually purchase a shipping label. After we have made any modifications to an order’s fulfillment, selected a packaging (Or multiple!) and set a weight, we need to show a list of rates and allow the user to purchase a shipping label - after which we create a fulfillment against that Fulfillment Order.
With the Shipstation API, we simply send packaging, ship from and ship to and retrieve a list of rates. We’d love to have a simple query and mutation; it might look like:
Query:
ShippingLabelServiceRates
Inputs:
We’d absolutely love first class shipping label support, as well as for our app’s shipping to integrate with existing shopify analytics, and for shipping labels to be stored along w/ an order. That would give our app a much better experience to merchants.
Is there any updates on this, @Wes-Dev-Shopify ?
We’re hitting a wall with shippingLabelPurchase (2026-07) from a Dev Dashboard custom app using a client credentials token, and we’ve isolated it away from our input entirely. Full input validates cleanly (fulfillmentOrderId, future shippingDatetime, notifyCustomer, totalWeight, customPackage with dimensions/weight/type, explicit originAddress). Omitting preferredRateSelection per your earlier guidance returns PURCHASE_FAILED: “A non-recoverable error occurred while purchasing the label. Review the shipment details and try again.” Supplying a preferredRateSelection instead returns “Rate was not found for the selected delivery method for the fulfillment order” for every carrier/service code we try. A minimal input of only the two required fields fails identically. Buying labels for the same fulfillment orders through admin works normally, same shop, same packages, so the shop, addresses, and billing are all fine. Is this mutation supported for tokens without user context, given the buy_shipping_labels user permission listed in the requirements? If not, what’s the supported auth path for a private merchant app? And where are valid carrierCode/serviceCode values documented?
Thanks for following up here @Ariel_Lezen 
While this is a use case we would definitely like to support in the future if possible, this isn’t something that can be accommodated currently and there isn’t a guarantee or timeline I’m able to share. As of right now, there isn’t any way to query a list of carrierCode/serviceCode options in our API and the shippingLabelPurchase mutation’s primary use case is to purchase the cheapest possible label by omitting peferredRateSelection.
Thank your for surfacing this feedback. It has definitely been heard and is for a valid use case. You can keep an eye on the changelog and I’ll let you know if I hear anything new in this thread as well.
Hi @Coty_Smith 
- thanks for reaching out.
Can you please share an x-request-id value from the headers of the failed request? This will allow me to trace the exact cause of the error.
The failure appears to occur during label processing rather than authentication, so the client-credentials token and lack of user context don’t look to be the cause.
There currently isn’t a public way to query valid carrierCode/serviceCode combinations. For now, I recommend omitting preferredRateSelection and allowing Shopify to select the cheapest rate automatically, or buying a label through alternative means if this doesn’t fit your use case.
Once I have the request ID, I can investigate why the request is returning PURCHASE_FAILED.
Thanks!
Thanks Wes. Fresh failing attempt with our full input (custom package with dimensions/weight/type, explicit originAddress, future shippingDatetime, no preferredRateSelection so Shopify selects cheapest):
Mutation x-request-id: 3c0974eb-ffcc-47d1-96bf-ffbe26dc262e-1783705312
Result poll x-request-id: 760d237e-e8ad-45f0-83c5-79c664aa2ded-1783705318
Job: gid://shopify/ShippingLabelPurchaseResult/32004210897
API version 2026-07, shop: good-taste-records.myshopify.com
The poll returned done with status PURCHASE_FAILED and the error message “A non-recoverable error occurred while purchasing the label. Review the shipment details and try again.”
For completeness: the same fulfillment order purchases fine through admin (same package dimensions and weight), and we reproduced the identical PURCHASE_FAILED with a minimal input of only fulfillmentOrderId and shippingDatetime, so it does not appear input-dependent on our side. Happy to run any traced variation you’d like.
Hey @Coty_Smith - thanks for bearing with me while I traced the requests you shared. Thanks for the detail as well.
After digging into this deeper, it appears the error appears because the mutation actually requires both write_orders and the applicable fulfilment-order write access scope based on the order’s assignment. In your case, the order is assigned to a merchant-managed location, so the additional required scope is write_merchant_managed_fulfillment_orders.
The current shippingLabelPurchase documentation is missing this requirement, and the generic PURCHASE_FAILED error didn’t surface. We’re working on both clearer error messaging for this case and clarifying the scope requirements in the documentation.
Thanks for bringing this to our attention and I hope this helps!
Hi Wes,
That was exactly it, thank you. Adding write_merchant_managed_fulfillment_orders alongside write_orders fixed it and we bought our first real label the same day.
One more on the same mutation. Any purchase including preferredRateSelection fails with:
▎ Rate was not found for the selected delivery method for the fulfillment order.
▎ x-request-id: db5e66b3-0ef4-449f-b14c-e993d70b8cb6-1783981333
Omitting it entirely works every time.
I don’t think this is a shipment problem. On order gid://shopify/FulfillmentOrder/6456042488017, omitting preferredRateSelection successfully bought a USPS Ground Advantage label. So that rate clearly exists for that fulfillment order. But asking for the same service explicitly:
“preferredRateSelection”: { “carrierCode”: “usps”, “serviceCode”: “usps-ground-advantage” }
…returns “Rate was not found.” A rate Shopify just purchased can’t be missing, so I suspect our carrierCode/serviceCode values are simply in the wrong format.
What are the valid carrierCode and serviceCode values for USPS via Shopify Shipping? I can’t find them anywhere: PreferredRateSelectionInput is two free-form strings with no enum, the shippingLabelPurchase reference doesn’t list accepted values, and I can’t find any query that enumerates available rates for a fulfillment order. The only hint is that FulfillmentOrder.deliveryMethod.serviceCode reads “Media Mail” on that order, a human-readable title rather than a slug. I haven’t guessed further, since a wrong code is a failed purchase and a lucky guess buys a real label.
This is blocking us on Media Mail specifically, which is most of what a record shop ships.
Store: good-taste-records.myshopify.com, Admin API 2026-07.
Thanks,
Coty
Hey @Coty_Smith - thanks for the detailed follow-up.
Shopify doesn’t currently expose a public API or supported list containing the valid carrierCode and serviceCode combinations for preferredRateSelection. This is something we’re aware of and I’ll update this thread if anything changes.
One important distinction is that FulfillmentOrder.deliveryMethod.serviceCode represents the buyer’s chosen delivery method and can contain a display value such as Media Mail as you noticed. It isn’t the carrier-rate serviceCode expected by preferredRateSelection, so it shouldn’t be passed into that input.
For now, the public API path is to omit preferredRateSelection and allow shippingLabelPurchase to use Shopify Shipping’s default rate selection. If you’re looking to specify the carrier/service of your label specifically, this mutation may not be a good fit for you currently as there isn’t currently a public discovery flow for purchasing a label for a specific service such as Media Mail.
Thank you for sharing your feedback and I hope this helps!
Thanks Wes — that settles it, and I appreciate the straight answer.
For anyone landing here from the same errors, the summary of the full thread: shippingLabelPurchase requires write_orders plus the fulfillment-order write scope matching the order’s assignment (write_merchant_managed_fulfillment_orders for merchant-managed locations), and preferredRateSelection is currently unusable through the public API — there’s no supported list of carrierCode/serviceCode values and no rate-discovery flow, so omitting it (default rate) is the only working path.
One data point for the team as you consider changes: we’re a record & music shop, so most of our orders ship USPS Media Mail — the customer selects and pays for it at checkout — but since Media Mail is content-restricted it’s never the default rate, which means the API cannot buy the service our customers already paid for. We’ve had to route those parcels back to the admin UI. A rate-discovery query on the fulfillment order (even just the handles that preferredRateSelection would accept) would let us close that gap.
I’ll watch this thread for updates. Thanks again for chasing down both issues.
Wes, do you have any update on this? Is this feature coming anytime soon?
Hey @SYegor - thanks for following up.
I don’t have an update on availability or timing to share, but I’ve passed your feedback along to the team as well. I’ll follow up here if anything changes on that front.