GraphQL APIで配送ラベルを購入する新Mutation
shippingLabelPurchase Mutationで出荷業務をフルオートメーション化
2026年6月17日、GraphQL Admin APIにshippingLabelPurchase Mutationが追加されました。
対象フルフィルメントオーダーに対してShopify Shippingの配送ラベルをアプリから直接購入でき、非同期ステータスポーリングで処理完了を確認する仕組みです。
write_ordersスコープとbuy_shipping_labelsパーミッションが必要で、Shopify Shippingの利用規約への同意も前提条件となります。
01非同期ラベル購入の仕組み
USE CASES02業務に活かせる3つのユースケース
- 課題
- 受注後の配送ラベル発行を手動で行っており、オペレーション担当者がShopify管理画面で毎回操作する必要がある
- 打ち手
- OMS/WMSシステムからshippingLabelPurchase Mutationを呼び出し、フルフィルメントオーダー確定と同時にラベルを自動発行する
- 効果
- 人手介入ゼロで配送ラベルが生成され、出荷リードタイムを短縮。ピーク期でもスケール可能な出荷フローを実現
- 技術メモ
- write_ordersスコープとbuy_shipping_labelsパーミッションが必要。ステータスをPURCHASEDになるまでポーリングしてからラベルURLを取得する実装が推奨
- 課題
- 複数の配送会社レートを都度比較する作業コストが高く、担当者のスキルによって選択結果にばらつきが出る
- 打ち手
- Mutationに優先キャリア・サービスを指定しないオプションを活用し、Shopifyが自動で最安値レートを選択する機能を利用する
- 効果
- 運用ルールの統一と送料コストの最適化を同時に達成。レート比較のためのロジックを自前実装する必要がない
- 技術メモ
- ShippingLabelPurchaseInputのキャリア/サービス指定フィールドはオプション。未指定時はShopifyが最安レートを自動選択する仕様
- 課題
- 購入者への配送通知タイミングが揃わず、カスタマーサポートへの問い合わせが発生している
- 打ち手
- Mutationの顧客通知設定(customerNotificationPreference)を活用し、ラベル購入と同時に通知送信可否をコード側で統制する
- 効果
- 通知タイミングの一貫性が保たれ、購入者体験の品質が向上。通知ロジックを外部ツールに依存せずAPI単体で完結できる
- 技術メモ
- 元記事ではcustomerNotificationPreferenceフィールドの詳細仕様はShippingLabelPurchaseInputのドキュメントを参照するよう案内されている
03開発者が押さえるべき5つのポイント
権限要件
Mutationの実行にはwrite_ordersアクセススコープと、ユーザーレベルのbuy_shipping_labelsパーミッションの両方が必要です。どちらか一方が欠けても実行できません。
利用規約の同意
APIでラベルを購入する前に、対象ショップがShopify Shippingの利用規約に同意している必要があります。管理画面での事前手続きが必要で、プログラムからは変更できません。
非同期処理
ラベル購入は非同期で実行されます。Mutationは即座にShippingLabelPurchaseResultを返しますが、完了までポーリングでステータスを確認するフローが必要です。
ステータス3種
結果ステータスはPENDING_PURCHASE（処理中）・PURCHASED（成功、shippingLabelsでラベル取得可）・PURCHASE_FAILED（失敗、errorsで詳細確認）の3種類です。
対象オーダー
「eligible fulfillment orders（対象フルフィルメントオーダー）」に限定されます。すべてのオーダーが対象になるわけではなく、Shopify Shippingが利用可能な条件を満たす必要があります。
「shippingLabelPurchase Mutationを活用することで、受注から配送ラベル発行までをノータッチで自動化し、ピーク時でも崩れない出荷オペレーションを構築できます。」
Source: https://shopify.dev/changelog/label-purchase-mutation | 公開日: 2026年6月17日
Share:
テーマ×アプリの新標準通信層：ストアフロントイベント＆アクション
Shopify 2026-07 新コレクションモデル完全解説