shippingLabelPurchase 配送ラベルの「購入」を GraphQL Admin API から実行できる

図解 ： Buy Shipping Labels with the GraphQL Admin API（shippingLabelPurchase ミューテーション） Admin GraphQL API / 新ミューテーション shippingLabelPurchase 配送ラベルの「購入」を GraphQL Admin API から実行できる 対象のフルフィルメントオーダーに対して、アプリから Shopify Shipping のラベルを購入できる新ミューテーション。購入は非同期で走り、結果をポーリングしてステータスを追跡する。 このページの構成 そもそも何ができるようになったのか（30秒で理解） 仕組み図解 ： 購入リクエストからラベル取得までの流れ ミューテーションに渡す入力 非同期で返る3つのステータス 利用条件（スコープ・権限・規約） 実装の流れ（3ステップ） 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 そもそも何ができるようになったのか GraphQL Admin API に shippingLabelPurchase ミューテーションが追加された。 これにより、アプリから 対象のフルフィルメントオーダーに対して Shopify Shipping のラベルを購入 できるようになった。 従来 ： 管理画面で手作業 ラベルの購入は基本的に Shopify 管理画面の操作が中心。アプリ側から API で「ラベルを買う」一連の処理は組み込みにくかった。 これから ： API でラベル購入 shippingLabelPurchase で、フルフィルメントオーダー・出荷日時・荷姿・重量・通知設定などを渡してラベルを購入。アプリのフローに組み込める。 2 仕組み図解 ： 購入リクエストからラベル取得までの流れ ポイントは「非同期 ＋ ポーリング」 。ミューテーションは即座にラベルを返すのではなく ShippingLabelPurchaseResult を返し、アプリ側はその status を見て購入が完了したか追跡する設計。 希望レート（preferred carrier / service）を渡さなかった場合、Shopify が利用可能な中から 最安のレート を自動選択する。 3 ミューテーションに渡す入力（ShippingLabelPurchaseInput） フルフィルメントオーダー どの注文の出荷に対してラベルを買うか。購入対象（eligible）であることが前提。 出荷日時 いつ発送するか（shipping date and time）。 荷姿（package details） パッケージの詳細。箱種別・寸法など出荷物の情報。 総重量 出荷物の total weight。レート算定に効く。 顧客通知の希望 顧客に出荷通知を送るかどうかの設定（customer notification preference）。 希望キャリア／サービス 任意 優先したいキャリアやサービスを指定可能。未指定なら Shopify が最安レートを選ぶ。 4 非同期で返る3つのステータス ラベル購入は非同期で実行され、 ShippingLabelPurchaseResult の status を poll して進行を追う。 PENDING_PURCHASE 処理中 購入がまだ処理中の状態。完了するまでポーリングを続ける。 PURCHASED 購入成功 ラベルの購入に成功。購入済みラベルは shippingLabels から取得できる。 PURCHASE_FAILED 購入失敗 購入に失敗。詳細は errors から確認できる。 5 利用条件（スコープ・権限・規約） アクセススコープ write_orders アクセススコープが必要。 ユーザー権限 操作するユーザーが buy_shipping_labels 権限を持っている必要がある。 規約への同意 API でラベルを購入する前に、ストアが Shopify Shipping の利用規約（terms of service）に同意している必要がある。 対応国・対応プラン・レート上限などの細かい適用条件は本チェンジログには記載なし。導入前に実ストアで購入対象（eligible）になるか、規約同意状態かを確認すること。 6 実装の流れ（3ステップ） 1 入力を組み立てて mutation 実行 フルフィルメントオーダー・出荷日時・荷姿・重量・通知設定（必要なら希望レート）を渡す。 2 Result を poll する ShippingLabelPurchaseResult の status が PENDING_PURCHASE の間はポーリングを継続。 3 結果を分岐処理 PURCHASED なら shippingLabels からラベル取得、 PURCHASE_FAILED なら errors を見てリトライ／通知。 非同期前提でジョブを設計する のがコツ。mutation 即時応答に依存せず、ステータス遷移（PENDING → PURCHASED / FAILED）をワーカーやキューで監視する形に落とし込むと安定する。 7 技術者が押さえるべき5つのポイント 1. 完全に非同期 ＝ ポーリング必須 ミューテーションはラベルを直接返さず ShippingLabelPurchaseResult を返す。完了監視は status を poll する前提で実装する。同期完了を期待しないこと。 2. レート選択は「省略＝最安」 希望キャリア／サービスを渡さなければ Shopify が利用可能な最安レートを自動選択。コスト最適化なら省略、特定キャリア要件があるなら明示指定、と設計を分ける。 3. スコープと「ユーザー権限」は別物 アプリの write_orders スコープだけでなく、実行ユーザーに buy_shipping_labels 権限が要る。権限不足のユーザーでは購入できない点を UI/エラー設計に織り込む。 4. 失敗は errors で握る PURCHASE_FAILED 時は errors に詳細が入る。重複購入や課金事故を避けるため、失敗ハンドリングと冪等性（同一オーダーへの再実行）を必ず設計する。 5. 規約同意は「前提条件」としてチェックする ストアが Shopify Shipping の利用規約に同意していないと API 経由の購入はできない。導入時のオンボーディングで規約同意状態を確認し、未同意ストア向けの導線（管理画面で同意してもらう案内）を用意しておくと運用で詰まらない。 8 業務に活かせる3つのユースケース USE CASE 1 出荷オペレーションの「ラベル一括購入」自動化 課題 日々大量の注文を出荷する EC で、ラベル購入を管理画面から1件ずつ手作業していて時間がかかる。 打ち手 対象フルフィルメントオーダーを抽出し shippingLabelPurchase をバッチ実行。希望レート未指定で最安を採用し、結果を poll してまとめてラベル化。 効果 出荷準備の工数を大幅削減。発送リードタイム短縮とラベルコスト最適化を同時に実現。 技術メモ 非同期前提でキュー＋ワーカーを構成し、 PENDING→PURCHASED/FAILED をステータス管理。失敗分だけ再投入する冪等設計にする。 USE CASE 2 自社 OMS / WMS とラベル発行を直結 課題 受注・在庫を自社 OMS で管理しているのに、配送ラベルだけ Shopify 管理画面に切り替えて発行しており、二重オペになっている。 打ち手 OMS 側のピッキング完了イベントをトリガに shippingLabelPurchase を実行。荷姿・重量・出荷日時を OMS のデータから渡し、購入済みラベルを shippingLabels から取り込む。 効果 システム間の手作業を排除し、出荷情報を一元管理。顧客通知設定も API 側で制御できる。 技術メモ 実行ユーザーに buy_shipping_labels 権限、アプリに write_orders スコープが必要。導入前に対象ストアの規約同意状態をチェックする。 USE CASE 3 配送コストの可視化・最安ルーティング 課題 どのキャリア・サービスでいくら配送費がかかっているか把握できず、コスト最適化の打ち手がない。 打ち手 原則は希望レート未指定（＝最安採用）で購入しつつ、要件のある注文だけ希望キャリアを明示。購入結果のラベル／レート情報を蓄積して配送費を分析。 効果 配送費の実数値を継続収集でき、キャリア交渉や送料設定の根拠データになる。最安採用でコスト圧縮。 技術メモ 希望レートの有無で挙動が変わる仕様を活かし、ルール（地域・重量・SLA）で「最安 or 指定」を分岐させる設計にする。 9 提案で使える1行サマリ 「 GraphQL Admin API の shippingLabelPurchase で、配送ラベルの購入をアプリから自動化できる。 非同期＋ポーリング前提・希望レート省略で最安自動選択・ write_orders ＋ buy_shipping_labels ＋規約同意が条件。 出荷オペや自社 OMS と直結させ、ラベル発行の二重作業をなくす一手。」 source ： shopify.dev / changelog / label-purchase-mutation Shopify Developer Changelog ・ 2026-06-17 公開