BusinessEntityにlegalEntityId追加 — 複数店舗を法人単位で管理

8月 02, 2026

API CHANGE

BusinessEntity に `legalEntityId` が追加
— 複数店舗を法人単位で横断管理

API 2026-07 以降、GraphQL Admin API で組織レベルの安定した法人IDが取得可能に

2026年7月リリースのAPIバージョン 2026-07 より、GraphQL Admin API の BusinessEntity タイプに legalEntityId フィールドが追加されました。Shopify の Organizations Platform が発行する「Central Legal Entity ID」を返すもので、同一法人が複数のショップ・マーケット・販売チャネルを運営していても、単一の安定したIDで法人を識別できます。パートナー・開発者にとって、複数店舗の名寄せやシステム間のID連携が大幅に簡素化されます。

BACKGROUND

01これまでの課題と変更の背景

これまで BusinessEntity.id はショップごとにスコープされていたため、同じ法人が複数ショップを持っていても異なるIDが割り当てられていました。新しい legalEntityId は Organizations Platform が管理する組織レベルの安定した識別子で、ショップや市場をまたいで同一法人を確実に識別できます。

TECHNICAL DETAIL

02フィールド仕様と利用シーン

フィールド名
legalEntityId

型
BigInt（null許容）

利用可能バージョン
API 2026-07 および unstable

null が返る条件
Central Legal Entity 未設定 or 安定した外部IDなし

USE CASES

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

課題: グローバル展開するブランドが地域ごとに複数ショップを持ち、ERP・CRM側でショップごとに別法人として扱われてしまっている。
打ち手: legalEntityId を取得し、自社システムの「会社コード」と紐付けるマスターテーブルを構築する。同一IDを持つショップは同一法人として集約処理。
効果: 手動マッピング作業が不要になり、新規ショップが追加されても自動的に同一法人グループへ統合される。
技術メモ: クエリは businessEntity(id: ...){ legalEntityId } で取得。null チェックを必ず実装し、未設定法人はフォールバック処理を用意すること。

課題: 税務Webhookのペイロードに含まれる merchant_business_entity.legal_entity_id と Admin API のデータを突合する際、IDが一致せず手動での照合が発生していた。
打ち手: Admin API で取得した legalEntityId をキーとして使い、Webhookペイロードの legal_entity_id と直接照合するパイプラインを構築する。
効果: 税務処理フローの自動化精度が向上し、法人単位での税申告データ集計が信頼性高く行えるようになる。
技術メモ: 元記事によると、GraphQL Admin API の legalEntityId と税Webhook の legal_entity_id は同一の識別子とされている。

課題: マルチショップ向けアプリがショップごとにインストールされており、同一法人のショップ間でライセンスや設定を共有する仕組みがなかった。
打ち手: アプリインストール時に legalEntityId を取得・保存し、同じ legalEntityId を持つショップ同士を同一テナントとして扱うマルチショップアーキテクチャを設計する。
効果: 法人単位でのライセンス管理・設定共有・使用量集計が実現し、マーチャントのUXと運用効率が向上する。
技術メモ: 法人IDは BigInt 型のため、JavaScriptで扱う場合は BigInt または文字列として処理すること（数値精度の問題を避けるため）。

DEVELOPER NOTES

04技術者が押さえるべき5つのポイント

#	ポイント	詳細
API	対応バージョン	2026-07 および `unstable` で利用可能。それ以前のバージョンではフィールド自体が存在しない。
型	BigInt の扱い	GraphQL の `BigInt` スカラー型。JSONでは文字列として返される場合があるため、パース時に注意が必要。
NULL	null許容フィールド	Central Legal Entity が設定されていない、または安定した外部IDを持たない場合は `null` が返る。必ずnullガードを実装すること。
連携	Webhookとの照合	税Webhookペイロードの `merchant_business_entity.legal_entity_id` と同一識別子。API↔Webhookのクロスリファレンスが可能。
移行	既存コードへの影響	既存クエリへの破壊的変更はなし。`legalEntityId` は新規追加フィールドのため、取得したい場合はクエリに明示的に追加するだけでよい。