ShippingLabelPurchaseUserError

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.</p> <p>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.