フルフィルメント先に州コード取得が可能に

11月 07, 2026

FULFILLMENT API

FulfillmentOrderDestinationに
provinceCodeフィールドが追加

州・省コードを直接取得可能に — 名称マッピングの手間を解消

GraphQL Admin API バージョン 2027-01 から、FulfillmentOrderDestination オブジェクトに provinceCode フィールドが追加されました。配送先の州・省をアルファベットコード（例：「ON」）で直接取得できるようになり、アプリ側で省名→コードの変換テーブルを自前で持つ必要がなくなります。追加スコープは不要で、既存のアクセス要件のまま利用可能です。

1変更内容の図解：Before / After

2業務に活かせる具体ユースケース

課題: ロジスティクス連携アプリが配送ラベルを生成する際、3PLシステムはISOコード形式（例：「ON」）しか受け付けないが、取得できるのは省名（「Ontario」）のみだった。
打ち手: provinceCode フィールドを直接クエリし、取得した値をそのまま3PLシステムのAPIパラメータに渡す。
効果: 独自マッピングテーブルのメンテナンスコストがゼロになり、表記ゆれによる配送エラーを防止できる。
技術メモ: APIバージョン 2027-01 以上を指定すること。フィールドは String 型で返却。省情報が存在しない、または認識できない場合は null が返る点に要注意。

課題: 国内税務レポートシステムへの連携時に、州コードで売上を集計したいが、省名の揺らぎ（例：英語・現地語混在）で集計が崩れるケースがあった。
打ち手: フルフィルメント注文の取得クエリに provinceCode を追加し、コードを集計キーとして使用する。
効果: 集計ロジックが安定し、レポートの精度が向上。名称の正規化処理が不要になる。
技術メモ: 既存の province フィールドとの併用も可能。省が存在しない国（例：日本など都道府県コードが認識されない場合）では null となる可能性があるため、null チェックを実装すること。

課題: マルチリージョン対応の在庫・出荷管理アプリで、フルフィルメントロケーションをカナダ・米国・オーストラリアの州単位で振り分けるルールを実装したかったが、コード取得に工数がかかっていた。
打ち手: フルフィルメント注文作成時に provinceCode を取得し、ルーティングロジックの分岐条件に直接利用する。
効果: 実装がシンプルになり、新しい国・州の追加対応も容易になる。
技術メモ: 新規の OAuth スコープ追加は不要。FulfillmentOrderDestination の既存アクセス要件（read_merchant_managed_fulfillment_orders 等）をそのまま引き継ぐ。

3技術者向けポイント

項目	内容
対象APIバージョン	GraphQL Admin API 2027-01 以降
フィールド名	`FulfillmentOrderDestination.provinceCode`
型	`String`（nullableあり）
nullになるケース	配送先に省・州情報がない場合、またはその国で認識されない場合
既存フィールドとの関係	既存の `province`（名称）・`countryCode` と共存。破壊的変更なし
必要スコープ	追加不要。`FulfillmentOrderDestination` の既存アクセス要件と同じ
参照ドキュメント	FulfillmentOrderDestination reference（Shopify公式）

実装時の注意点： APIバージョンを 2027-01 未満のまま使用している場合、provinceCode フィールドはクエリに含めてもエラーとなります。バージョンアップのタイミングでフィールドを追加するよう計画してください。また、null 返却時のフォールバック処理（例：province 名称を使う）を検討しておくと安全です。

配送先の州・省コードをAPIから直接取得できるようになり、独自マッピング実装の排除とフルフィルメント連携の信頼性向上が同時に実現できます。

Source: https://shopify.dev/changelog/fulfillment-order-destination-province-code | 公開日: 2026年10月29日