A new mutation that lets your app buy Shopify Shipping labels for a given fulfillment order. The purchase runs asynchronously, so you poll the result to track its status.
shippingLabelPurchase mutation has beenBuying labels was basically centered on actions in the Shopify admin. It was hard to build the full "buy a label" process into your app via the API.
shippingLabelPurchase buy a label by passing the fulfillment order, ship date, packaging, weight, notification settings, and more. You can build it into your app's flow.
ShippingLabelPurchaseResult and your app watches its status to track whether the purchase has completed.Which order's shipment the label is purchased for. It must be eligible for purchase.
When the shipment goes out (shipping date and time).
Details of the package. Information about the shipment such as box type and dimensions.
The total weight of the shipment. It affects rate calculation.
The setting for whether to send a shipment notification to the customer (customer notification preference).
You can specify a preferred carrier or service. If left unspecified, Shopify picks the cheapest rate.
Label purchase runs asynchronously,ShippingLabelPurchaseResult so poll the status to track its progress.
The purchase is still being processed. Keep polling until it completes.
The label was purchased successfully. The purchased label can be retrieved from shippingLabels you can retrieve it.
The purchase failed. Details can be checked from errors you can check the details.
write_orders An access scope is required.
The user performing the operation buy_shipping_labels must have this permission.
Before purchasing a label via the API, the store must have agreed to the Shopify Shipping terms of service.
Pass the fulfillment order, ship date and time, package details, weight, and notification setting (and a preferred rate if needed).
ShippingLabelPurchaseResult the status of PENDING_PURCHASE while it is, keep polling.
PURCHASED if it's shippingLabels fetch the label, andPURCHASE_FAILED if it's errors check it and retry / notify.
The mutation doesn't return the label directly; it returns ShippingLabelPurchaseResult Implement on the assumption that you poll the status to monitor completion. Don't expect synchronous completion.
If you don't pass a preferred carrier / service, Shopify automatically selects the cheapest available rate. Split the design: omit it for cost optimization, specify it explicitly when you have specific carrier requirements.
The app's write_orders Beyond the scope, the executing user needs the buy_shipping_labels permission. Factor into your UI/error design that users without sufficient permissions can't make a purchase.
errors to handle themPURCHASE_FAILED when it fails, errors contains the details. To avoid duplicate purchases and billing accidents, always design failure handling and idempotency (re-running against the same order).
If the store hasn't agreed to the Shopify Shipping terms of service, purchases via the API aren't possible. Check the terms-agreement status during onboarding at adoption time, and prepare a path for stores that haven't agreed (guidance to agree from the admin) so you don't get stuck in operations.
shippingLabelPurchase run as a batch. Adopt the cheapest rate by leaving the preferred rate unspecified, then poll the results to generate labels all at once.PENDING→PURCHASED/FAILED manage by status. Make it idempotent so only the failed ones are re-enqueued.shippingLabelPurchase run it. Pass package format, weight, and ship date/time from the OMS data, and pull the purchased label shippingLabels in.buy_shipping_labels permission, and the app needs the write_orders scope. Check the target store's terms-acceptance status before rolling out.shippingLabelPurchase , you can automate shipping-label purchases from your app.write_orders+buy_shipping_labels+ terms acceptance.