--- title: shippingLabelPurchase - GraphQL Admin description: >- Purchases a shipping label for a fulfillment order. The `shippingLabelPurchase` mutation buys one shipping label for one fulfillment order using Shopify Shipping. The mutation validates the fulfillment order, shipment details, package information, and available rates before it starts an asynchronous label purchase. > Note: > The shop must have accepted the Shopify Shipping terms of service before an app can purchase labels. > > FedEx label purchases are not supported. After validation, the mutation builds the shipment details, fetches available rates, selects a rate, and enqueues the label purchase. If you provide `preferredRateSelection`, the mutation attempts to purchase the matching carrier and service. If you don't provide `preferredRateSelection`, the mutation uses Shopify Shipping's default rate selection. Default rate selection first tries to keep the fulfillment order's buyer-selected delivery method when available. If no buyer-selected rate matches, the mutation uses the shop's preferred carrier and service when configured. Otherwise, it uses Shopify's recommended rate for the shipment destination. For Merchant of Record (MoR) and Markets Pro orders, the mutation first removes rates from carriers that don't support Markets Pro. A shipping label can be purchased only when the fulfillment order meets the following criteria: - The fulfillment order is fulfillable and requires shipping. - The order has a destination shipping address. - The fulfillment order has an assigned location that can be used as the origin address. - The shipment has a valid shipping date, package, weight, and required customs information. - At least one shipping rate is available for the shipment. The mutation can return errors in two places: - Synchronous validation errors are returned in the mutation's `userErrors` field. For example, invalid fulfillment orders, invalid package dimensions, missing customs information, or unavailable rates. - Asynchronous purchase-processing errors are returned in the `ShippingLabelPurchaseResult.errors` field after the purchase starts. For example, carrier availability, connection, billing, or other purchase-processing failures. Use the returned `ShippingLabelPurchaseResult.id` to poll the purchase status with the `node` query. The result starts with a status of `PENDING_PURCHASE` and ends with `PURCHASED` or `PURCHASE_FAILED`. When the purchase succeeds, `shippingLabels` contains the purchased label. api_version: 2026-10 source_url: html: >- https://shopify.dev/docs/api/admin-graphql/latest/mutations/shippingLabelPurchase md: >- https://shopify.dev/docs/api/admin-graphql/latest/mutations/shippingLabelPurchase.md api_name: admin api_type: graphql type: mutation --- # shipping​Label​Purchase mutation Requires `write_orders` access scope. Also: An applicable fulfillment order write access scope is required: `write_merchant_managed_fulfillment_orders` for fulfillment orders assigned to merchant-managed locations, `write_assigned_fulfillment_orders` for fulfillment orders assigned to a fulfillment service owned by the app, or `write_third_party_fulfillment_orders` for fulfillment orders assigned to another fulfillment service. The user must also have the `buy_shipping_labels` permission. Purchases a shipping label for a fulfillment order. The `shippingLabelPurchase` mutation buys one shipping label for one fulfillment order using Shopify Shipping. The mutation validates the fulfillment order, shipment details, package information, and available rates before it starts an asynchronous label purchase. *** **Note:** The shop must have accepted the Shopify Shipping terms of service before an app can purchase labels.\

\

FedEx label purchases are not supported. *** After validation, the mutation builds the shipment details, fetches available rates, selects a rate, and enqueues the label purchase. If you provide `preferredRateSelection`, the mutation attempts to purchase the matching carrier and service. If you don't provide `preferredRateSelection`, the mutation uses Shopify Shipping's default rate selection. Default rate selection first tries to keep the fulfillment order's buyer-selected delivery method when available. If no buyer-selected rate matches, the mutation uses the shop's preferred carrier and service when configured. Otherwise, it uses Shopify's recommended rate for the shipment destination. For Merchant of Record (MoR) and Markets Pro orders, the mutation first removes rates from carriers that don't support Markets Pro. A shipping label can be purchased only when the fulfillment order meets the following criteria: * The fulfillment order is fulfillable and requires shipping. * The order has a destination shipping address. * The fulfillment order has an assigned location that can be used as the origin address. * The shipment has a valid shipping date, package, weight, and required customs information. * At least one shipping rate is available for the shipment. The mutation can return errors in two places: * Synchronous validation errors are returned in the mutation's `userErrors` field. For example, invalid fulfillment orders, invalid package dimensions, missing customs information, or unavailable rates. * Asynchronous purchase-processing errors are returned in the `ShippingLabelPurchaseResult.errors` field after the purchase starts. For example, carrier availability, connection, billing, or other purchase-processing failures. Use the returned `ShippingLabelPurchaseResult.id` to poll the purchase status with the `node` query. The result starts with a status of `PENDING_PURCHASE` and ends with `PURCHASED` or `PURCHASE_FAILED`. When the purchase succeeds, `shippingLabels` contains the purchased label. ## Arguments * shipping​Label​Purchase [Shipping​Label​Purchase​Input!](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/ShippingLabelPurchaseInput) required The shipment, package, and rate preferences for the label purchase. *** ## Shipping​Label​Purchase​Payload returns * shipping​Label​Purchase​Result [Shipping​Label​Purchase​Result](https://shopify.dev/docs/api/admin-graphql/latest/objects/ShippingLabelPurchaseResult) The asynchronous purchase result. Query this object to track purchase status, retrieve purchased shipping labels, or inspect purchase-processing errors. * user​Errors [\[Shipping​Label​Purchase​User​Error!\]!](https://shopify.dev/docs/api/admin-graphql/latest/objects/ShippingLabelPurchaseUserError) non-null The list of errors that occurred from executing the mutation. *** ## Examples * ### shippingLabelPurchase reference