Merchant API v1beta was discontinued and shut down on February 28, 2026. For steps to transition to the latest stable version, see Migrate from v1beta to v1.

Overview of the Loyalty Customer Match Service

This guide describes how to use the Loyalty Customer Match Service in the Merchant API. This service enables merchants to manage customer loyalty data, such as user identifiers and tier information, for organic personalization on Google Search, without requiring an active Google Ads account.

Overview

Use the Loyalty Customer Match Service to upload loyalty data, which is then used to provide organic loyalty personalization features on Google Search, such as displaying member-specific pricing. You use the ManageLoyaltyCustomerMatch custom method to associate your customers with loyalty program tiers, enabling you to insert, update, or remove their loyalty status based on user identifiers.

Key concepts

Unified interface: A unique endpoint to add, update, or remove customer loyalty tier details.
Privacy-first design: To protect user privacy and prevent unauthorized account probing, the API does not support GET or LIST operations, ensuring that data is managed without retrieval or auditing.
Flexible identification: Match users using at least one valid identifier, such as an email address, physical address, or phone number.
Consent-based processing: The service stores and uses customer data only when the end-user has granted the necessary consent to Google. To protect and prevent account existence probing or consent status, the service returns a silent success if a match is not made or consent is not granted.

Prerequisites

Follow these requirements to use the Loyalty Customer Match Service:

Account setup: Ensure you have an active Merchant Center account. You don't need to create a Google Ads account to use the Loyalty Customer Match Service.
Loyalty program configuration: Enable the loyalty program in your Merchant Center account, and make sure you have defined loyalty tiers.
Tier order awareness: Be aware of the order in which your loyalty tiers are defined in the Merchant Center UI. The API uses this exact sequence for its enum mapping.

Method: `ManageLoyaltyCustomerMatch`

The ManageLoyaltyCustomerMatch method serves as the central interface for managing customer loyalty associations. Based on the input provided, the service automatically determines whether to insert, update, or remove the loyalty tier status of a customer. The operation is idempotent: repeated identical requests have the same effect as a single request.

The following request demonstrates how to manage customer loyalty associations through the API:

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

This request defines the following required path parameters:

api_version: The API version such as v1.
account_id: The Merchant Center account ID.

Include a loyaltyCustomer object in the request body.

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

loyaltyCustomer fields

userIdentifier: The set of identifiers used to match the customer. At least one field within userIdentifier must be provided and valid.
loyaltyTier: The loyalty tier to associate with the customer. Maps to the order of the tier in the Merchant Center setup. For details, see Understanding loyaltyTier mapping. Use NON_MEMBER to remove an existing association.
pointBalance: The customer's current points balance.

userIdentifier fields

At least one of the following fields must be provided:

emailAddress: The customer's email address.
address: The customer's physical address. PostalCode is required.
phoneNumber: The customer's phone number. E.164 format is recommended.

Understand `loyaltyTier` mapping

The API does not use the custom names. The loyaltyTier enum values (TIER1 to TIER7) are semantic labels. They don't use the custom names (for example, "Gold Rewards") or custom labels (for example, "gold_tier") you assigned in your Merchant Center UI. Instead, they map strictly to the order in which you defined your tiers in the loyalty program settings in the Merchant Center:

TIER1: Corresponds to the first tier listed in your Merchant Center loyalty program configuration.
TIER2: Corresponds to the second tier listed in your Merchant Center loyalty program configuration.
TIER3 through TIER7: Correspond to the third through seventh tiers listed in your Merchant Center loyalty program configuration.

Example:

If your Merchant Center loyalty program has tiers defined in this order:

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

Then, in accounts.loyaltyCustomers.manage API calls:

To assign a customer to "Silver Status", you must use loyaltyTier: TIER1.
To assign a customer to "Gold Member", you must use loyaltyTier: TIER2.
To assign a customer to "Platinum Elite", you must use loyaltyTier: TIER3.

LoyaltyTier enum values

TIER1
TIER2
TIER3
TIER4
TIER5
TIER6
TIER7
NON_MEMBER (Used to signal removal of the customer's loyalty association)

Understand the ManageLoyaltyCustomerMatch response body

The ManageLoyaltyCustomerMatch method returns a ManageLoyaltyCustomerMatchResponse object:

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

Important considerations on possible responses:

Successful upsert (data stored): To successfully store or update a customer's loyalty tier association, meet the following conditions:
- you match a Google user with the provided userIdentifier
- you set the loyaltyTier in the request to a valid value other than NON_MEMBER
- the matched user has consented to loyalty data usage

The response contains the loyaltyCustomer object from your request, indicating the data is successfully processed and stored:

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

Successful deletion: To successfully remove any existing loyalty association for the customer with this merchant, the following conditions must be fulfilled:
- you match a Google user with the provided userIdentifier
- you set the loyaltyTier in the request to NON_MEMBER

The response is an empty JSON object:

{}

No match / no consent (silent success): If the provided userIdentifier does not match a Google Account, or if the matched user has not consented to loyalty data usage, the API returns an HTTP 200 OK status with an empty JSON object: {}. This happens for both upsert and removal attempts.

Examples

TIER1 corresponds to the first defined tier of the merchant, the one called "Basic", and TIER2 to their second - "Premium"

To add a customer to TIER2 or update their status using an email address, send the following request:

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

When a user is successfully matched and has consented, the API returns the following response:

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

When there is no match or the user hasn't consented, the API returns the following response:

{}

To remove a customer's loyalty association using a phone number, send the following request:

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

Regardless of whether a record existed, the API returns the following success response:

{}

To add or update a customer using multiple identifiers, send the following request:

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

Response is similar to the first example, depending on match and consent.

Error handling

The API uses standard HTTP codes. Common error strings include:

HTTP code	Error String	Description
400	INVALID_ARGUMENT	Missing user_identifier or loyalty_tier, or identifier is empty.
401	UNAUTHENTICATED	Invalid or missing credentials.
403	PERMISSION_DENIED	The authenticated user does not have access to the specified Merchant Center account.
404	NOT_FOUND	The specified loyalty tier label does not exist in your configuration.
412	FAILED_PRECONDITION	You have not configured a loyalty program in your account.
429	RESOURCE_EXHAUSTED	Quota limit reached.