---
title: Buy Shipping Labels with the GraphQL Admin API - Shopify developer changelog
description: >-
  Shopify’s developer changelog documents all changes to Shopify’s platform.
  Find the latest news and learn about new platform opportunities.
source_url:
  html: 'https://shopify.dev/changelog/label-purchase-mutation'
  md: 'https://shopify.dev/changelog/label-purchase-mutation.md'
metadata:
  effectiveApiVersion: 2026-07
  affectedApi:
    - displayName: Admin GraphQL API
      handle: admin-graphql
  primaryTag:
    displayName: API
    handle: api
  secondaryTag:
    displayName: New
    handle: new
  indicatesActionRequired: false
  createdAt: '2026-02-11T15:57:49-05:00'
  postedAt: '2026-06-17T11:45:00-04:00'
  updatedAt: '2026-06-16T18:00:00-04:00'
  effectiveAt: '2026-02-23T09:00:00-05:00'
---

June 17, 2026

Tags:

* Admin GraphQL API
* 2026-07

# Buy Shipping Labels with the GraphQL Admin API

## New `shippingLabelPurchase` mutation in the GraphQL Admin API

The GraphQL Admin API now includes the `shippingLabelPurchase` mutation, which lets apps purchase Shopify Shipping labels for eligible fulfillment orders.

Apps can provide the fulfillment order, shipping date and time, package details, total weight, customer notification preference, and optional preferred carrier/service selection. If a preferred rate isn't provided, Shopify selects the cheapest available rate.

Label purchase runs asynchronously. The mutation returns a `ShippingLabelPurchaseResult`, which apps can poll to track the request status:

* `PENDING_PURCHASE`: the purchase is still processing.
* `PURCHASED`: the label was purchased successfully, and the purchased labels are available on `shippingLabels`.
* `PURCHASE_FAILED`: the purchase failed, and details are available on `errors`.

## Requirements

The mutation requires the `write_orders` access scope and a user with the `buy_shipping_labels` permission. Shops must also accept the Shopify Shipping terms of service before purchasing labels through the API.

## Related documentation

* [`shippingLabelPurchase` mutation](https://shopify.dev/docs/api/admin-graphql/unstable/mutations/shippingLabelPurchase)
* [`ShippingLabelPurchaseInput`](https://shopify.dev/docs/api/admin-graphql/unstable/input-objects/ShippingLabelPurchaseInput)
* [`ShippingLabelPurchaseResult`](https://shopify.dev/docs/api/admin-graphql/unstable/objects/ShippingLabelPurchaseResult)
* [`ShippingLabelPurchaseResultStatus`](https://shopify.dev/docs/api/admin-graphql/unstable/enums/ShippingLabelPurchaseResultStatus)