重要: Content API for Shopping は 2026 年 8 月 18 日 に提供を終了しました。

2026 年 9 月 1 日より、Content API for Shopping のリクエストでエラーが段階的に発生するようになります。詳しくは、 Content API の提供終了に関するガイドをご覧ください。

Merchant API への移行に時間がかかる場合は、 Content API for Shopping へのアクセス期間の延長を申請してください。

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

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

このガイドでは、Merchant API でポイントプログラムの顧客マッチングサービスを使用する方法について説明します。このサービスを使用すると、販売者と販売者の代理を務めるサードパーティのポイントプログラムプロバイダは、Google 検索でのオーガニックなパーソナライズのために、ユーザー識別子やランク情報などの顧客ポイントプログラムデータを管理できます。有効な Google 広告アカウントは必要ありません。

概要

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

主なコンセプト

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

前提条件

ポイントプログラムのカスタマーマッチサービスを使用するには、次の要件を満たす必要があります。

アカウントの設定: 有効な Merchant Center アカウント（サードパーティのポイントプログラムプロバイダの場合は、販売者のアカウントへのアクセス権限）があることを確認します。ロイヤリティカスタマーマッチサービスを使用するために Google 広告アカウントを作成する必要はありません。
ポイントプログラムの設定: Merchant Center アカウントでポイントプログラムを有効にし、ポイントステータスを定義していることを確認します。
ポイントランクの順序を意識する: Merchant Center の管理画面でポイントランクが定義されている順序を意識してください。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 の管理画面で割り当てたカスタム名（「ゴールド特典」など）やカスタムラベル（「gold_tier」など）は使用されません。代わりに、Merchant Center のポイントプログラム設定で階層を定義した順序に厳密にマッピングされます。

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

例:

Merchant Center のポイントプログラムで、次の順序で階層が定義されているとします。

会員ステータス名: "Silver Status"、会員ステータスラベル: "silver"
会員ステータス名: "Gold Member"、会員ステータスラベル: "gold"
会員ステータス名: "Platinum Elite"、会員ステータスラベル: "platinum"

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

顧客を "Silver Status" に割り当てるには、loyaltyTier: TIER1 を使用する必要があります。
顧客を "Gold Member" に割り当てるには、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
  }
}

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

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

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

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

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

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

{}

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

例

TIER1 は、最初に定義された階層（'Basic' など）に対応し、TIER2 は 2 番目の階層（'Premium' など）に対応します。

メールアドレスを使用して、お客様を 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 がないか、識別子が空です。
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 は、識別子の基本的な形式チェック（メールの構造、アドレス内の postalCode の有無など）を行います。
ただし、最初のチェックに合格した識別子の一部が、Google ユーザーアカウントと一致しない場合や、バックエンドのマッチングシステムで認識される形式でない場合があります。このような場合、HTTP ステータス 200 OK のサイレント成功の空のレスポンス {} が返されます。

ベストプラクティス

統合を最適化するには、次のベストプラクティスを実践してください。

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

Manage loyalty programs

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

概要

主なコンセプト

前提条件

メソッド: ManageLoyaltyCustomerMatch

loyaltyTier マッピングについて

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

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

例

エラー処理

エラーの例

ベスト プラクティス

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

メソッド: `ManageLoyaltyCustomerMatch`

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

ベストプラクティス