Merchant API v1beta は 2026 年 2 月 28 日に廃止され、シャットダウンされました。最新の安定版に移行する手順については、v1beta から v1 に移行するをご覧ください。

Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

ロイヤリティカスタマーマッチサービスの概要

このガイドでは、Merchant API でポイントプログラムの顧客照合サービスを使用する方法について説明します。このサービスを使用すると、販売者は有効な Google 広告アカウントがなくても、Google 検索でのオーガニック検索結果のパーソナライズに使用するユーザー ID や会員ランク情報などの顧客ロイヤリティデータを管理できます。

概要

ポイントプログラムのカスタマーマッチサービスを使用してポイントプログラムのデータをアップロードします。このデータは、Google 検索でポイントプログラムのパーソナライズ機能（会員限定の価格表示など）を提供するために使用されます。ManageLoyaltyCustomerMatch カスタムメソッドを使用して、顧客をポイントプログラムのティアに関連付けます。これにより、ユーザー ID に基づいてポイントステータスを挿入、更新、削除できます。

主なコンセプト

統合インターフェース: 顧客のロイヤルティティアの詳細を追加、更新、削除するための独自のエンドポイント。
プライバシー重視の設計: ユーザーのプライバシーを保護し、不正なアカウントプロービングを防ぐため、この API は GET オペレーションと LIST オペレーションをサポートしていません。これにより、データの取得や監査なしでデータが管理されます。
柔軟な識別: メールアドレス、住所、電話番号などの有効な識別子を 1 つ以上使用してユーザーを照合します。
同意に基づく処理: エンドユーザーがGoogle に必要な同意を与えた場合にのみ、サービスは顧客データを保存して使用します。アカウントの存在のプロービングや同意ステータスを保護し、それらを防ぐため、一致が見つからない場合や同意が得られない場合、サービスはサイレント成功を返します。

前提条件

ロイヤリティカスタマーマッチサービスを使用するには、次の要件を満たす必要があります。

アカウントの設定: 有効な Merchant Center アカウントがあることを確認します。ロイヤリティカスタマーマッチサービスを使用するために Google 広告アカウントを作成する必要はありません。
ポイントプログラムの設定: Merchant Center アカウントでポイントプログラムを有効にし、ポイントステータスが定義されていることを確認します。
階層の順序: Merchant Center の UI でポイントプログラムの階層が定義されている順序を把握します。API はこのシーケンスを列挙型マッピングに使用します。

メソッド: `ManageLoyaltyCustomerMatch`

ManageLoyaltyCustomerMatch メソッドは、顧客ロイヤルティの関連付けを管理するための中心的なインターフェースとして機能します。提供された入力に基づいて、顧客のロイヤリティティアステータスを挿入、更新、削除するかどうかが自動的に決定されます。オペレーションはべき等です。同じリクエストを繰り返しても、1 回のリクエストと同じ効果があります。

次のリクエストは、API を使用して顧客ロイヤリティの関連付けを管理する方法を示しています。

POST https://merchantapi.googleapis.com/{api_version}/accounts/{account_id}/loyaltyCustomers:manage

このリクエストでは、次の必須パスパラメータを定義します。

api_version: API バージョン（v1 など）。
account_id: Merchant Center アカウント ID。

リクエスト本文に loyaltyCustomer オブジェクトを含めます。

{
    "userIdentifier": {
      "emailAddress": "string",
      "address": {
        "addressLines": ["string"],
        "locality": "string",
        "administrativeArea": "string",
        "postalCode": "string",
        "regionCode": "string"
      },
      "phoneNumber": "string"
    },
    "loyaltyTier": "LoyaltyTier",
    "pointBalance": "integer"
  }

loyaltyCustomer フィールド

userIdentifier: 顧客の照合に使用される識別子のセット。userIdentifier 内の少なくとも 1 つのフィールドが指定され、有効である必要があります。
loyaltyTier: お客様に関連付けるロイヤルティティア。Merchant Center の設定における階層の順序にマッピングされます。詳細については、loyaltyTier マッピングについてをご覧ください。既存の関連付けを削除するには、NON_MEMBER を使用します。
pointBalance: お客様の現在のポイント残高。

userIdentifier フィールド

以下のフィールドのうち少なくとも 1 つを指定する必要があります。

emailAddress: お客様のメールアドレス。
address: お客様の住所。PostalCode は必須です。
phoneNumber: お客様の電話番号。E.164 形式が推奨されます。

`loyaltyTier` マッピングについて

API ではカスタム名が使用されません。loyaltyTier 列挙値（TIER1～TIER7）はセマンティックラベルです。Merchant Center の UI で割り当てたカスタム名（「ゴールド特典」など）やカスタムラベル（「gold_tier」など）は使用されません。代わりに、Merchant Center のポイントプログラム設定で階層を定義した順序に厳密にマッピングされます。

TIER1: Merchant Center のポイントプログラム構成に記載されている最初の会員ステータスに対応します。
TIER2: Merchant Center のポイントプログラム設定に登録されている 2 番目の会員ステータスに対応します。
TIER3～TIER7: Merchant Center のポイントプログラム設定に記載されている 3 番目から 7 番目の会員ステータスに対応します。

例:

Merchant Center のポイントプログラムで階層が次の順序で定義されている場合:

Tier Name: "Silver Status"、Tier Label: "silver"
Tier Name: "Gold Member"、Tier Label: "gold"
Tier Name: "Platinum Elite"、Tier Label: "platinum"

次に、accounts.loyaltyCustomers.manage API 呼び出しで、次の操作を行います。

お客様を 「Silver Status」に割り当てるには、loyaltyTier: TIER1 を使用する必要があります。
お客様を 「ゴールドメンバー」に割り当てるには、loyaltyTier: TIER2 を使用する必要があります。
お客様を 「Platinum Elite」に割り当てるには、loyaltyTier: TIER3 を使用する必要があります。

LoyaltyTier 列挙値

TIER1
TIER2
TIER3
TIER4
TIER5
TIER6
TIER7
NON_MEMBER（お客様のロイヤリティ関連付けの削除を示すために使用）

ManageLoyaltyCustomerMatch レスポンスの本文について

ManageLoyaltyCustomerMatch メソッドは ManageLoyaltyCustomerMatchResponse オブジェクトを返します。

{
  "loyaltyCustomer": {
    // loyaltyCustomer object from the request
  }
}

回答例に関する重要な考慮事項:

アップサートの成功（データが保存された）: お客様のロイヤルティティアの関連付けを正常に保存または更新するには、次の条件を満たす必要があります。
- 指定された userIdentifier と Google ユーザーを照合する
- リクエストで loyaltyTier を NON_MEMBER 以外の有効な値に設定している
- 照合されたユーザーがポイントプログラムデータの使用に同意している

レスポンスには、リクエストの loyaltyCustomer オブジェクトが含まれています。これは、データが正常に処理されて保存されたことを示しています。

{
  "loyaltyCustomer": {
    "userIdentifier": {
     "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
    }
}

削除の成功: お客様とこの販売者との既存のポイントプログラムの関連付けを正常に削除するには、次の条件を満たす必要があります。
- 指定された userIdentifier と Google ユーザーを照合する
- リクエストで loyaltyTier を NON_MEMBER に設定している。

レスポンスは空の JSON オブジェクトです。

{}

一致なし / 同意なし（サイレント成功）: 指定された userIdentifier が Google アカウントと一致しない場合、または一致したユーザーがポイントプログラムデータの使用に同意していない場合、API は空の JSON オブジェクト {} を含む HTTP 200 OK ステータスを返します。これは、挿入更新と削除の両方の試行で発生します。

例

TIER1 は、販売者の最初の定義済み階層（「ベーシック」）に対応し、TIER2 は 2 番目の階層（「プレミアム」）に対応します。

メールアドレスを使用してお客様を TIER2 に追加するか、ステータスを更新するには、次のリクエストを送信します。

POST
"https://merchantapi.googleapis.com/v1/accounts/{account_id}/loyaltyCustomers:manage"
  -d '{
      "userIdentifier": {
        "emailAddress": "customer@example.com"
      },
      "loyaltyTier": "TIER2",
      "pointBalance": 1500
  }'

ユーザーが正常に照合され、同意している場合、API は次のレスポンスを返します。

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 1500
  }
}

一致するものがない場合や、ユーザーが同意していない場合、API は次のレスポンスを返します。

{}

電話番号を使用してお客様のポイントプログラムの関連付けを削除するには、次のリクエストを送信します。

POST
"https://merchantapi.googleapis.com/v1/accounts/{account_id}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "phoneNumber": "+18005550132"
      },
      "loyaltyTier": "NON_MEMBER"
  }'

レコードが存在するかどうかに関係なく、API は次の成功レスポンスを返します。

{}

複数の識別子を使用して顧客を追加または更新するには、次のリクエストを送信します。

POST
"https://merchantapi.googleapis.com/v1/accounts/{account_id}/loyaltyCustomers:manage" \
  -d '{
      "userIdentifier": {
        "emailAddress": "user@example.com",
        "address": {
          "postalCode": "94043",
          "regionCode": "US"
        }
      },
      "loyaltyTier": "TIER1"
  }'

レスポンスは、一致と同意に応じて最初の例のようになります。

エラー処理

この API は標準の HTTP コードを使用します。一般的なエラー文字列には、次のようなものがあります。

HTTP コード	エラー文字列	説明
400	INVALID_ARGUMENT	user_identifier または loyalty_tier がないか、ID が空です。
401	UNAUTHENTICATED	認証情報が無効であるか存在しません。
403	PERMISSION_DENIED	認証されたユーザーに、指定された Merchant Center アカウントへのアクセス権がありません。
404	NOT_FOUND	指定されたポイントプログラム会員ステータスラベルが構成に存在しません。
412	FAILED_PRECONDITION	アカウントでポイントプログラムが設定されていません。
429	RESOURCE_EXHAUSTED	割り当ての上限に達しました。

エラーの例

404 NOT_FOUND の例:

ポイントプログラムが設定されていないアカウント ID への有効なリクエスト。

API は次のエラーレスポンスを返します。

{
  "error": {
    "code": 404,
    "message": "The loyalty program is not found for account: {account_id}.",
    "status": "NOT_FOUND",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "notFound",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "ACCOUNT_ID": "{account_id}",
          "REASON": "NOT_FOUND_LOYALTY_PROGRAM"
        }
      }
    ]
  }
}

理由: パス内の販売アカウントに有効なポイントプログラムがありません。

400 INVALID_ARGUMENT の例:

リクエストに loyaltyTier フィールドの無効な値が含まれている場合は、エラーが発生します。

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER11",
    "pointBalance": 100
  }
}

API は次のエラーレスポンスを返します。

{
  "error": {
    "code": 400,
    "message": "Invalid value at 'loyalty_customer.loyalty_tier' (type.googleapis.com/google.shopping.merchant.loyaltycustomers.v1.LoyaltyCustomer.LoyaltyTier), \"TIER11\"",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "loyalty_customer.loyalty_tier",
            "description": "Invalid value at 'loyalty_customer.loyalty_tier' (type.googleapis.com/google.shopping.merchant.loyaltycustomers.v1.LoyaltyCustomer.LoyaltyTier), \"TIER11\""
          }
        ]
      }
    ]
  }
}

理由: TIER11 は loyaltyTier の有効な列挙値ではありません。使用可能な階層が 1 つしかない場合に TIER2 を指定しようとすると、同じエラーが発生する可能性があります。

リクエスト本文に必須の loyaltyTier フィールドがない場合、エラーが発生します。

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "pointBalance": 100
  }
}

API は次のエラーレスポンスを返します。

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.loyalty_tier] Required field not provided: loyalty_customer.loyalty_tier",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "required",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_LOCATION": "loyalty_customer.loyalty_tier",
          "REASON": "MISSING_REQUIRED_FIELD"
        }
      }
    ]
  }
}

理由: loyaltyTier フィールドは必須です。

postalCode フィールドが欠落しているなど、アドレス識別子が不完全な場合はエラーが発生します。

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "address": {
        "locality": "Sunnyvale",
        "administrativeArea": "CA",
        "regionCode": "US"
      }
    },
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

API は次のエラーレスポンスを返します。

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] The format of loyalty_customer.user_identifier does not match the expected format ... Value: at least one valid user identifier should be provided.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.user_identifier",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

理由: 住所は指定されていますが、必須の postalCode フィールドがないため、有効な識別子と見なされません。

構成されたプログラムの範囲外のティアインデックスをリクエストすると、エラーが発生します。

シナリオ: Merchant Center で 1 つの階層のみが設定されている。

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@example.com"
    },
    "loyaltyTier": "TIER2",
    "pointBalance": 100
  }
}

API は次のエラーレスポンスを返します。

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.loyalty_tier] The format of loyalty_customer.loyalty_tier does not match the expected format `valid LoyaltyTier`. Value: TIER2.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.loyalty_tier",
          "PATTERN": "valid LoyaltyTier",
          "FIELD_VALUE": "TIER2",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

理由: TIER2 がリクエストされましたが、アカウントにリンクされているポイントプログラムには第 2 階層が定義されていません。

リクエストに形式が正しくない emailAddress が含まれている場合、エラーが発生します。

{
  "loyaltyCustomer": {
    "userIdentifier": {
      "emailAddress": "customer@google"
    },
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

API は次のエラーレスポンスを返します。

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] The format of loyalty_customer.user_identifier does not match the expected format `email_address: \t \"customer@google\"\n`. Value: at least one valid user identifier should be provided.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "invalid",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_NAME": "loyalty_customer.user_identifier",
          "REASON": "INVALID_VALUE"
        }
      }
    ]
  }
}

理由: メールアドレスの形式が無効です。

userIdentifier オブジェクトが空の場合、エラーが発生します。

{
  "loyaltyCustomer": {
    "userIdentifier": {},
    "loyaltyTier": "TIER1",
    "pointBalance": 100
  }
}

API は次のエラーレスポンスを返します。

{
  "error": {
    "code": 400,
    "message": "[loyalty_customer.user_identifier] Required field not provided: loyalty_customer.user_identifier",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "required",
        "domain": "merchantapi.googleapis.com",
        "metadata": {
          "FIELD_LOCATION": "loyalty_customer.user_identifier",
          "REASON": "MISSING_REQUIRED_FIELD"
        }
      }
    ]
  }
}

理由: userIdentifier オブジェクトは存在するが、実際の識別子フィールドが含まれていない。

識別子の検証に関する注意事項:

API は、ID の基本的な形式チェック（メール構造、アドレス内の postalCode の有無など）を行います。
ただし、初期チェックに合格した識別子の中には、Google ユーザーアカウントと一致しないものや、バックエンドのマッチングシステムで認識される形式ではないものがあります。このような場合、HTTP ステータス 200 OK の空のレスポンス {} が返されます。

ベストプラクティス

統合を最適化するには、以下のベストプラクティスを参考にしてください。

大規模な統合の場合: API はリクエストごとに動作するため、大規模なデータセットに必要なスループットを実現するには、クライアントサイドの並列処理が必要です。複数の同時リクエストを管理するように統合を設計する必要があります。並列化によって大量のデータを処理するように実装を構成する方法については、複数のリクエストを送信する方法に関するガイドをご覧ください。
割り当て管理: デフォルトの割り当ては、1 日あたり 1,000,000 件のリクエストと 1 分あたり 10,000 件のリクエストです。割り当てをモニタリングして確認する方法については、割り当てと上限をご覧ください。
メールアドレスを優先する: 可能な限り、お客様の emailAddress を userIdentifier に含めます。通常、メールアドレスはユーザーを Google アカウントに照合するうえで最も正確で信頼性の高い識別子です。
空のレスポンスを処理する: プライバシー上の理由（一致なしまたは同意なし）でデータが保存されなかったことを意味する空の {} レスポンスを成功として正しく解釈するように、アプリケーションを設計します。リクエストを再試行しないでください。
階層の順序を確認する: Merchant Center の UI でロイヤリティプログラムの階層の順序を常に確認し、API 呼び出しで正しい TIER1～TIER7 列挙値を使用していることを確認します。このマッピングは、名前ではなく、UI で定義された順序に基づいています。
エラーをモニタリングする: API レスポンスをログに記録してモニタリングし、4xx エラーに注意して、インテグレーションの問題を把握します。特に、ティアの認識の不一致を示す可能性がある 404 エラーに注意してください。

ロイヤリティ カスタマー マッチ サービスの概要 コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

概要

主なコンセプト

前提条件

メソッド: ManageLoyaltyCustomerMatch

loyaltyTier マッピングについて

ManageLoyaltyCustomerMatch レスポンスの本文について

回答例に関する重要な考慮事項:

例

エラー処理

エラーの例

ベスト プラクティス

ロイヤリティカスタマーマッチサービスの概要

メソッド: `ManageLoyaltyCustomerMatch`

`loyaltyTier` マッピングについて

ベストプラクティス