Shopify Customer APIの実務設計｜Admin API・Customer Account API・CRM/kintone同期の勘所

Shopifyの顧客情報をCRM、CDP、kintone、MA、CSツールへ連携したい場面は多くあります。購入回数でセグメントを作る、問い合わせ時に注文履歴を見せる、法人顧客を営業管理へつなぐ、といった用途です。

ただし、ShopifyのCustomer APIを「顧客一覧を取得するAPI」とだけ捉えると設計を誤ります。氏名、メール、電話、住所、購入履歴、マーケティング同意、タグ、metafieldsは便利ですが、同時に個人情報・同意・権限・削除要求の対象です。

この記事では、公式のGraphQL Admin API Customer object、Customer Account API、REST Admin Customer resource、Work with protected customer data、Privacy law compliance、Processing customer data requests、Webhooksを前提に、API選定とCRM/kintone同期の実務設計を整理します。

Shopify Customer API連携の目的は、外部に顧客名簿を複製することではありません。顧客本人、店舗運営、CRM施策、法務・監査のそれぞれに説明できる顧客データ基盤を作ることです。

先に結論：Customer API連携は顧客名簿ではなく同意と監査を含むCRM設計

設計テーマ	先に決めること	未設計時の問題
API選定	店舗管理者向け同期はGraphQL Admin API、顧客本人向け画面はCustomer Account APIに分ける	Customer Account APIで一括CRM同期を作ろうとして設計が破綻する
PII権限	氏名、住所、電話、メールを本当に保存するか	承認されないフィールド、redacted data、過剰保持に対応できない
同意状態	メール、SMS、データ販売オプトアウトなどの扱い	配信停止者へ外部MAから送ってしまう
監査ログ	誰が、どの顧客情報を、何の目的で同期・更新したか	問い合わせ、法務確認、障害復旧で説明できない

実装方針は明確です。今後の新規実装はGraphQL Admin API中心にします。REST Admin Customer resourceは既存連携の保守、移行調査、旧系参照として扱います。Shopify公式はREST Admin APIを2024年10月1日からlegacy APIと位置づけ、2025年4月1日以降の新規public appはGraphQL Admin APIで構築する前提を示しています。

一方で、Customer Account APIは別物です。これはログイン済み顧客本人が、自分のプロフィール、住所、注文、ストアクレジットなどを確認・操作するための顧客スコープAPIです。店舗管理者が全顧客をCRMへ一括同期する用途とは切り分けます。

Admin APIとCustomer Account APIの違い

観点	GraphQL Admin API Customer	Customer Account API	REST Admin Customer resource
主な利用者	店舗、管理者、業務システム、アプリ	ログイン済みの顧客本人	既存REST実装、旧系保守
向く用途	CRM/CDP/kintone同期、顧客台帳、購入履歴分析、CS参照	マイページ、本人プロフィール確認、本人の注文確認	既存連携の棚卸し、短期保守、移行元調査
データ範囲	scopeと保護された顧客データの承認に応じた店舗顧客データ	認証された顧客本人にスコープされたデータ	endpointごとのscopeと保護された顧客データ
同期設計	Webhook、差分取得、Bulk処理、外部ID対応表と組み合わせる	OAuth/OIDC、PKCE、顧客ログイン体験と組み合わせる	新規主軸にはしない
注意点	read_customers scopeが必要。保護された顧客データは承認されたフィールドだけ返る前提で設計する	店舗全体の顧客一括取得や管理者CRM同期には使わない	RESTのサンプルに引きずられて新規設計しない

GraphQL Admin APIのCustomer objectは、Shopifyが「ショップの顧客に関する情報」として、連絡先、購入履歴、マーケティング設定などを扱うオブジェクトです。公式リファレンスではCustomer objectにread_customers access scopeが必要とされ、氏名、住所、電話、メールなどの保護された顧客データを扱う場合は、承認されたフィールドだけが返る前提で設計する必要があります。

Customer Account APIは、公式説明どおり「personalized, customer authenticated experiences」を作るAPIです。顧客本人のプロフィール・注文確認には向きますが、CRM夜間同期、kintone顧客台帳、CDP投入はAdmin API側で設計します。

顧客データで扱える項目とPII権限

データ分類	例	CRM/kintoneでの用途	設計方針
識別子	Shopify Customer ID、legacy resource ID、外部CRM ID、kintone record ID	名寄せ、同期、再実行、削除要求	原則保存する。メールアドレスを主キーにしない
基本プロフィール	display name、first name、last name、locale、state	CS検索、営業管理、顧客表示	表示に必要な最小範囲に絞る
連絡先PII	email、phone、住所	配送、問い合わせ、本人確認、連絡	利用目的ごとに保存先を分け、不要なシステムへ送らない
購入サマリー	amount spent、number of orders、last order	LTV、優良顧客抽出、休眠判定	CRM分析には便利だが、再計算元と更新時刻を残す
注文履歴	orders、lastOrder、返金、返品	CS対応、購買分析、会計照合	詳細履歴はOrder側台帳と分ける
マーケティング同意	email/SMS同意、opt out、購読状態	配信可否、セグメント	外部MA/CDPの同意状態と双方向に矛盾しないようにする
tags/metafields	会員区分、営業担当、連携制御、独自属性	セグメント、業務フラグ、外部連携	自由入力のタグを基幹ロジックの唯一条件にしない

PII設計で重要なのは、全システムに同じ顧客情報を持たせないことです。配送には住所が必要でも、広告分析や会計には顧客IDだけで足りる場合があります。

保護された顧客データでは、顧客データを扱わない設計、氏名・住所・電話・メールを除く設計、これらのPIIを含む設計で承認・説明責任が変わります。承認されていないフィールドが返らない、エラーになる、またはredacted dataになる前提で、外部同期処理を保留・警告・再設定へ回せるようにします。

タグ/metafields/同意状態の設計

項目	向いている使い方	向かない使い方	CRM/kintone連携の勘所
tags	簡易セグメント、キャンペーン対象、運用フラグ	厳密な同意状態、長期の顧客属性正本	人が付け替える前提で変更履歴を別に持つ
metafields	会員ランク、外部ID、独自属性、業務定義済みフィールド	都度変わる作業メモ、未定義の自由入力	namespace/key/typeを決め、データ辞書で管理する
email marketing consent	メール配信可否、購読状態	CRM側の営業接触許可の代替	外部MAの購読解除と同期方針を決める
SMS consent	SMS配信可否	電話連絡全般の許可扱い	国・チャネルごとの同意要件を分ける
dataSaleOptOutなど	データ販売・共有に関する意思表示	通常のメール配信停止フラグ	用途を誤解せず、プライバシー関連フラグとして扱う

タグは便利ですが、厳密なマスタではありません。タグを使うなら、許可タグ一覧、付与権限、削除ルール、外部反映のタイミングを決めます。

metafieldsは、構造化された独自属性に向いています。たとえば、crm.external_customer_id、crm.account_owner、loyalty.rank、integration.sync_statusのようにnamespace/keyを分けると、CRMやkintoneとの対応が明確になります。metafieldsのデータモデル設計は、Shopify metafieldのデータモデル設計も参照してください。

同意状態はさらに慎重に扱います。Shopify上のメール同意、外部MAの購読解除、LINE連携の友だち状態、kintone上の営業接触可否は、同じ意味ではありません。Shopify LINE連携の運用設計のように、チャネルごとに同意と到達可能性を分ける方が安全です。

注文履歴と顧客IDの紐付け

ただし、CRM/kintone同期では「顧客に注文一覧をぶら下げる」だけでは足りません。注文は受注・決済・配送・返金・返品・会計の正本と関係します。詳細な注文連携はShopify Order APIで受注データ連携を設計するのようにOrder側台帳で設計し、Customer側にはサマリーと参照キーを持たせる方が運用しやすくなります。

紐付け対象	持つべきキー	CRM/kintoneでの見せ方	注意点
顧客	Shopify Customer ID、CRM ID、kintone record ID	顧客基本情報、同意状態、セグメント	メールアドレス変更で別人扱いしない
注文	Shopify Order ID、注文名、顧客ID	最新注文、購入回数、LTV、問い合わせ履歴	ゲスト購入、統合顧客、削除要求を考慮する
注文明細	line item ID、SKU、商品名	購入カテゴリ、嗜好分析	商品名やSKU変更後も注文時点情報を残す
返金・返品	refund ID、return ID、order ID	CS対応、LTV補正、クレーム傾向	返金後のLTVと注文時売上を混ぜない
顧客統合	surviving customer ID、merged customer ID	名寄せ履歴、外部ID移行	統合前IDで届くWebhookや古い外部リンクを扱う

顧客IDの扱いで特に危険なのは、メールアドレスを主キーにすることです。メールは変更され、共有され、外部CRMの見込み客とも衝突します。主キーはShopify Customer IDと外部ID対応表にし、メールは照合候補として扱います。

CRM/CDP/kintone同期の構成

連携先	主な役割	渡すデータ	渡さない/絞るデータ	設計ポイント
CRM	営業・CSの顧客対応	顧客ID、氏名、連絡先、購入サマリー、対応履歴	不要な配送先履歴、全注文明細	担当者、商談、問い合わせ履歴と分ける
CDP	セグメント、分析、広告・MA連携	顧客ID、購買イベント、同意状態、属性	住所、電話、過剰なメモ	匿名ID、同意、削除要求の連鎖を設計する
kintone	人が見る台帳、例外処理、再実行画面	顧客台帳、同期状態、要確認フラグ、エラー	全payload、不要なPII	業務画面として、再同期・保留・承認を持たせる
MA/BI	配信・集計	同意状態、セグメント、匿名化ID	購読停止者、住所、電話	解除同期と仮名化を明確にする

kintoneを使う場合は、Shopify Customerを1アプリに丸ごと入れるより、「顧客台帳」「外部ID対応表」「同意・連絡可否」「同期ログ」「削除要求対応」「重複候補」を分けます。これで、kintoneは単なる顧客コピーではなく、同期状態を見て直せる運用画面になります。API連携全体の正本と外部システム境界は、Shopify API連携の設計方法の考え方と同じです。

webhook・polling・重複統合・削除要求の運用

運用テーマ	使う仕組み	何を残すか	失敗時の対応
顧客作成・更新	customers/create、customers/update、Admin API再取得	webhook ID、event ID、顧客ID、payload hash	冪等にupsertし、必要なら最新状態を取り直す
差分確認	updatedAtベースのpolling、夜間照合	最終同期時刻、取得件数、未反映件数	Webhook欠損や長時間障害の穴埋め
重複統合	候補抽出、人間承認、外部ID移行	統合前後ID、根拠、承認者	自動統合しすぎず、注文履歴と外部IDを確認する
削除要求	customers/redact、shop/redact、管理画面要求	request ID、対象ID、処理期限、完了ログ	外部CRM/CDP/kintoneからPIIを削除・匿名化する
データ開示要求	customers/data_request、管理画面のデータ要求	受付日時、対象顧客、抽出範囲	自社が保持する外部データも説明できるようにする
連携停止	app uninstall、権限変更、shop/redact	shop ID、停止日時、削除範囲	保持義務のある集計以外のPIIを消す

Shopifyのprivacy law complianceでは、App Storeで配布するアプリはmandatory compliance webhooksとしてcustomers/data_request、customers/redact、shop/redactに対応する必要があります。Shopify Helpでも、加盟店が顧客データのコピー要求や削除要求を処理する流れが説明されています。外部CRMやkintoneに同期した時点で、Shopifyの中だけ消せばよい話ではなくなります。

顧客削除要求は、Shopify上の顧客を消す操作では終わりません。CRM、CDP、kintone、MA、ログ、バックアップ、再同期ジョブまで、PIIが残る場所を台帳化しておく必要があります。

Webhook設計の詳細は、Shopify Webhookの実装設計も参照してください。顧客Webhookも注文Webhookと同じく、HMAC検証、即時ACK、キュー、重複排除、DLQ、reconciliation jobが必要です。

セキュリティと監査ログ

顧客データ連携では、セキュリティは後付けできません。API scope、保護された顧客データ、保存先、ログ、再実行、手動補正を最初から監査可能にします。

領域	設計方針	監査ログに残すこと
API scope	read_customersなど必要最小限にする。書き込みが必要な場合だけ追加scopeを検討する	申請scope、利用目的、承認日、変更履歴
フィールド制御	承認されたPIIフィールドだけを取得・保存する	取得フィールド一覧、同期先別の保存可否
Webhook検証	HMAC検証、raw body、topic、shopを確認する	webhook ID、event ID、検証結果、payload hash
外部同期	CRM/kintone/CDPへのupsertを冪等にする	外部ID、処理者、処理結果、再実行回数
PIIログ	payload全文保存を避け、保存する場合は期限とアクセス制限を設ける	保存場所、保持期限、削除日時
削除要求	redact webhookと社内対応をつなぐ	要求受信、各システム処理、完了確認

監査ログで避けるべきなのは、便利だからといって顧客payload全文を長期保存することです。保存期限、暗号化、閲覧権限、マスキング、削除要求時の扱いを決めないログ基盤は、最大のPIIリスクになります。CRM/kintone側の手動編集も、Shopify正本、CRM正本、kintone補正可の項目を分けておきます。

まとめ

Shopify Customer API連携は便利ですが、顧客データはPII権限、同意状態、削除要求、監査ログを避けて通れません。新規実装ではREST Admin Customer resourceを主軸にせず、GraphQL Admin API中心で設計します。Customer objectにはread_customers scopeが必要で、保護された顧客データは承認されたフィールドだけ返る前提です。

Customer Account APIは、ログイン済み顧客本人のプロフィール確認、注文確認、顧客アカウント体験に向くAPIです。店舗管理者向けの一括CRM同期、CDP投入、kintone顧客台帳更新とは切り分けます。

実務では、Customer IDと外部ID対応表を中心に、タグ、metafields、同意状態、注文サマリー、注文履歴参照、Webhook、polling、重複統合、削除要求を組み合わせます。特にcustomers/redact、customers/data_request、shop/redact、PII最小化、監査ログは、後から追加するのではなく、最初のデータモデルに入れておくべきです。

Shopify Customer APIは顧客名簿を作るためのAPIではありません。便利な同期ほど、どのデータを持たないか、どのログを残すか、削除要求でどこまで消すかを先に決める必要があります。