Skip to main content
Anchor to shippingLabelPurchase

shippingLabelPurchase

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.

Anchor to Arguments

Arguments

Anchor to shippingLabelPurchaseshippingLabelPurchase
•ShippingLabelPurchaseInput!
required

The shipment, package, and rate preferences for the label purchase.

Was this section helpful?

Anchor to ShippingLabelPurchasePayload returnsShippingLabelPurchasePayload returns

Anchor to shippingLabelPurchaseResultshippingLabelPurchaseResult
•ShippingLabelPurchaseResult

The asynchronous purchase result. Query this object to track purchase status, retrieve purchased shipping labels, or inspect purchase-processing errors.

Anchor to userErrorsuserErrors
•[ShippingLabelPurchaseUserError!]!
non-null

The list of errors that occurred from executing the mutation.

Was this section helpful?