Showcase your store benefits on Google using loyalty programs. You can submit a
range of benefits, such as free shipping, redeemable points, and
member-exclusive pricing. Your loyalty program benefits can appear in free
listings, Shopping ads, and local inventory ads across Google surfaces,
including Google Search, the Shopping tab, and Google Wallet.

With Merchant API, merchants and third-party loyalty providers acting on behalf
of merchants can configure and maintain loyalty programs programmatically using
the `LoyaltyProgramService`. This service lets you create, retrieve, list,
update, and delete loyalty programs.

> [!IMPORTANT]
> **Important:** The service is only available to selected merchants. Contact the support team to express interest for participation by submitting an allowlist request in the [Shopping API Support Form](https://support.google.com/merchants/contact/shopping_api_support_form) under **What is the issue/question? \> Allowlist request \> Other**.

For more information about business requirements and policy guidelines, see
[About merchant loyalty program](https://support.google.com/merchants/answer/12827255)
in the Merchant Center Help Center.

## Key concepts

Keep the following concepts and limitations in mind when working with loyalty
programs:

- **Account-level identifier:** The Merchant API identifies loyalty
  programs by the owning Merchant Center account ID.

- **Single program limit:** Merchant API supports only one loyalty program
  per merchant account.

- **Direct account ownership:** Loyalty programs must be configured directly
  on the target merchant account (`accounts/{ACCOUNT_ID}`).
  The service does not support managing loyalty programs at an advanced
  account level for sub-accounts. Third-party loyalty providers with
  authorized access to a merchant's account can manage the program on the
  merchant's behalf.

- **Editorial review:** After creating or updating a loyalty program, the
  program undergoes review. The `review_result.review_status` field indicates
  whether the program is `UNDER_REVIEW`, `APPROVED`, or `REJECTED`. Every
  successful update sends the program back to the review queue, even if the
  update doesn't change anything major. **Google hides the program from
  shoppers during the review process.** Review can take up to 48 hours.

- **Supported regions:** Merchant loyalty programs are available in
  supported countries, including Australia, Brazil, Canada, France, Germany,
  India, Italy, Japan, Mexico, Netherlands, South Korea, Spain, the United
  Kingdom, and the United States.

- **Active regions:** A loyalty program's `regionCodes` must be a subset of
  the `activeRegionCodes` of
  `accounts/{ACCOUNT_ID}/programs/loyalty`. Otherwise,
  create, update, and delete requests fail with a `LOYALTY_PROGRAM_DISABLED`
  error. Google activates a supported country when the Loyalty program add-on is
  enabled and the account meets the
  [eligibility requirements](https://support.google.com/merchants/answer/12827255#Eligibility)
  in that country. For example, the account is eligible if the
  Free Listings program is enabled and a primary product data source
  targets the country for the `FREE_LISTINGS` destination. To find out why a
  country isn't active, see [Check active regions](https://developers.google.com/merchant/api/guides/loyalty/loyalty-programs.md.txt#active-regions).

- **Tier requirements:** Tiers can have no cost to join, require a
  membership fee, require a spending threshold, or require a merchant-branded
  credit card. Occupation-based tiers (such as student or military tiers)
  aren't supported.

- **Perks and benefits:** Programs support free shipping, redeemable points,
  and member pricing. In ads, member pricing requires a discount of at least
  5% or 5 currency units below the regular or sale price.

## Prerequisites

Before managing loyalty programs with Merchant API, ensure you meet the
following requirements:

- You must have an active Merchant Center account (or authorized access to the merchant's account if you are a third-party loyalty provider).
- Enable the **Loyalty** program add-on for your account. You can enable the
  add-on using either of the following options:

  - **Merchant Center UI:** Follow the instructions in [Set up a loyalty program](https://support.google.com/merchants/answer/16455621) in Merchant Center Help.
  - **Programs sub-API:** Enable the program programmatically as described in [Enable programs in Programs sub-API](https://developers.google.com/merchant/api/guides/programs/overview.md.txt#enable). The `accounts.programs.enable` method requires [administrator access](https://developers.google.com/merchant/api/guides/accounts/control-access.md.txt).
- The countries where you want to offer your loyalty program must be active
  for your account. To find out which countries are active, see
  [Check active regions](https://developers.google.com/merchant/api/guides/loyalty/loyalty-programs.md.txt#active-regions).

Here is a sample request to enable the Loyalty program add-on using
Programs sub-API:

### HTTP

```console
POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty:enable
```

### cURL

```console
curl --request POST \
  'https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty:enable?key={YOUR_API_KEY}' \
  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{}' \
  --compressed
```

## Check active regions

After you enable the Loyalty program add-on, call the
[`accounts.programs.get`](https://developers.google.com/merchant/api/guides/programs/overview.md.txt#get) method
for `accounts/{ACCOUNT_ID}/programs/loyalty`. The response
shows where you can use loyalty programs and why other supported countries are
inactive.

> [!NOTE]
> **Note:** The Merchant API uses the term *region* because these fields contain [CLDR](https://cldr.unicode.org/) region codes. Other programs can use the region code `001` for the whole world. For loyalty programs, every region code is a country code, such as `US` or `JP`.

Here's a sample request:

### HTTP

```console
GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty
```

### cURL

```console
curl --request GET \
  'https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty?key={YOUR_API_KEY}' \
  --header 'Authorization: Bearer {YOUR_ACCESS_TOKEN}' \
  --header 'Accept: application/json' \
  --compressed
```

Replace <var translate="no">{ACCOUNT_ID}</var> with the unique identifier of your
Merchant Center account.

Here's a sample response for an account that enabled the add-on and is
eligible only in the United States:

```json
{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty",
  "documentationUri": "https://support.google.com/merchants/answer/12827255",
  "state": "ENABLED",
  "activeRegionCodes": [
    "US"
  ],
  "unmetRequirements": [
    {
      "title": "IS_ELIGIBLE_FOR_LOYALTY",
      "documentationUri": "https://support.google.com/merchants/answer/12827255#Eligibility",
      "affectedRegionCodes": [
        "AU",
        "BR",
        "CA",
        "DE",
        "ES",
        "FR",
        "GB",
        "IN",
        "IT",
        "JP",
        "KR",
        "MX",
        "NL"
      ]
    }
  ]
}
```

In this response, observe the following fields:

- `activeRegionCodes`: The countries that you can use in the `regionCodes` of your loyalty program. In the preceding sample, only `US` is active.
- `unmetRequirements`: The reason other supported countries are inactive. For loyalty programs, this is the `IS_ELIGIBLE_FOR_LOYALTY` requirement.
  - `affectedRegionCodes`: The supported countries where the account isn't eligible.
  - `documentationUri`: A link to the [eligibility requirements](https://support.google.com/merchants/answer/12827255#Eligibility).

In the preceding sample, you can't use the countries in `affectedRegionCodes`
yet. If your loyalty program's `regionCodes` includes one of them, create,
update, and delete requests fail with a `LOYALTY_PROGRAM_DISABLED` error. To
activate a country, do the following:

1. Make the account eligible in that country. For example, enable the Free Listings program and set a primary product data source to target the country for the `FREE_LISTINGS` destination. For all the ways to become eligible, see the [eligibility requirements](https://support.google.com/merchants/answer/12827255#Eligibility).
2. Call `accounts.programs.get` again, and check that the country is in `activeRegionCodes`.

`affectedRegionCodes` can include countries where you do not sell. You do not
need to take any action for these countries. They do not affect the countries in
`activeRegionCodes`.

## Methods

Manage loyalty programs using the following methods:

- [`loyaltyPrograms.create`](https://developers.google.com/merchant/api/guides/loyalty/loyalty-programs.md.txt#create)
- [`loyaltyPrograms.get`](https://developers.google.com/merchant/api/guides/loyalty/loyalty-programs.md.txt#get)
- [`loyaltyPrograms.list`](https://developers.google.com/merchant/api/guides/loyalty/loyalty-programs.md.txt#list)
- [`loyaltyPrograms.update`](https://developers.google.com/merchant/api/guides/loyalty/loyalty-programs.md.txt#update)
- [`loyaltyPrograms.delete`](https://developers.google.com/merchant/api/guides/loyalty/loyalty-programs.md.txt#delete)

### Create a loyalty program

To create a new loyalty program for an account, use the
`loyaltyPrograms.create` method. Specify details such as program descriptions,
the signup URL, and program tiers with their unique benefits and requirements.

The required `program_label` sets the unique identifier for the loyalty
program. For example, providing the label `my-rewards` results in a resource
`name` of `accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards`.

Here's a sample request:

### HTTP

```console
POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms

{
  "programLabel": "my-rewards",
  "loyaltyProgram": {
    "programName": "my rewards",
    "tiers": [
      {
        "tierName": "gold",
        "tierLabel": "gold",
        "tierBenefits": [
          {
            "otherBenefit": "free gift on your birthday"
          },
          {
            "structuredBenefit": {
              "pointsEarningBenefit": {
                "minimumMoneySpent": {
                  "currencyCode": "USD",
                  "units": "25"
                },
                "pointsEarningBenefitAnnotation": {
                  "pointsEarned": 1.0,
                  "amountSpent": {
                    "currencyCode": "USD",
                    "units": "1"
                  }
                }
              }
            }
          }
        ],
        "requirements": {
          "freeToJoin": true
        }
      }
    ],
    "programDescriptions": [
      "earn rewards buying products you love"
    ],
    "signupUrl": "https://www.example.com/my_rewards_signup",
    "regionCodes": [
      "US"
    ]
  }
}
```

Replace <var translate="no">{ACCOUNT_ID}</var> with the unique identifier of your
Merchant Center account.

Here's a sample response of a successful request:

```json
{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "earn rewards buying products you love"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}
```

### Retrieve a loyalty program

To retrieve the details of a specific self-owned loyalty program, use the
`loyaltyPrograms.get` method.

> [!NOTE]
> **Note:** Even if the Loyalty program add-on has not been enabled, this endpoint still responds with a matching loyalty program without returning an error.

Here's a sample request:

### HTTP

```console
GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}
```

Replace <var translate="no">{ACCOUNT_ID}</var> with your account ID and
<var translate="no">{PROGRAM_LABEL}</var> with the unique label of the loyalty program
(for example, `my-rewards`).

Here's a sample response of a successful request:

```json
{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "earn rewards buying products you love"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}
```

### List loyalty programs

To list all self-owned loyalty programs associated with your account, use the
`loyaltyPrograms.list` method.

> [!NOTE]
> **Note:** This method lists only loyalty programs owned directly by the specified account, not programs associated with sub-accounts. Even if the Loyalty program add-on is disabled, this endpoint responds with existing programs without returning an error.

Here's a sample request:

### HTTP

```console
GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms
```

Here's a sample response of a successful request:

```json
{
  "loyaltyPrograms": [
    {
      "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
      "programName": "my rewards",
      "tiers": [
        {
          "tierName": "gold",
          "tierLabel": "gold",
          "tierBenefits": [
            {
              "otherBenefit": "free gift on your birthday"
            },
            {
              "structuredBenefit": {
                "pointsEarningBenefit": {
                  "minimumMoneySpent": {
                    "currencyCode": "USD",
                    "units": "25"
                  },
                  "pointsEarningBenefitAnnotation": {
                    "pointsEarned": 1.0,
                    "amountSpent": {
                      "currencyCode": "USD",
                      "units": "1"
                    }
                  }
                }
              }
            }
          ],
          "requirements": {
            "freeToJoin": true
          },
          "signupUrl": "https://www.example.com/my-rewards/gold"
        }
      ],
      "programDescriptions": [
        "earn rewards buying products you love"
      ],
      "signupUrl": "https://www.example.com/my_rewards_signup",
      "reviewResult": {
        "reviewStatus": "UNDER_REVIEW"
      },
      "regionCodes": [
        "US"
      ]
    }
  ]
}
```

### Update a loyalty program

To update an existing loyalty program, use the `loyaltyPrograms.update`
method. Perform a partial update using an `update_mask`, or perform a full
replacement by omitting the mask. Each successful update triggers a new
[editorial review](https://developers.google.com/merchant/api/guides/loyalty/loyalty-programs.md.txt#key-concepts), so send an update only when a value
changes.

> [!IMPORTANT]
> **Important:** When updating a loyalty program, repeated fields (such as `programDescriptions` and `tiers`) cannot be updated in place. Any repeated field included in an update replaces the entire existing list. To avoid unintended data loss, send a `get` request first to retrieve current values before updating repeated fields.

#### Partial update with update mask

An `update_mask` lets you specify the exact fields to update. Only the fields
listed in the mask are modified, while unlisted fields remain unchanged. Any
field omitted from the update mask is ignored, even if provided in the request
body.

> [!NOTE]
> **Note:** Even if `regionCodes` isn't in the `updateMask`, the service checks the program's current `regionCodes` against `activeRegionCodes`. If a current country is no longer active, the update fails with a `LOYALTY_PROGRAM_DISABLED` error. To update the program, include `region_codes` in the `update_mask` and include only active countries in the request.

The following sample request updates only `programDescriptions` and
`advancedSettings`:

### HTTP

```console
PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}?update_mask=program_descriptions,advanced_settings

{
  "programDescriptions": [
    "a new description of the program"
  ],
  "advancedSettings": {
    "hideDisplayFromNonMembers": true
  },
  "signupUrl": "https://www.example.com"
}
```

In this example, the service ignores `signupUrl` because it is not included in
the `update_mask`. The `programDescriptions` field completely replaces any
previously configured descriptions.

Here's a sample response from a successful request:

```json
{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "my rewards",
  "tiers": [
    {
      "tierName": "gold",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "free gift on your birthday"
        },
        {
          "structuredBenefit": {
            "pointsEarningBenefit": {
              "minimumMoneySpent": {
                "currencyCode": "USD",
                "units": "25"
              },
              "pointsEarningBenefitAnnotation": {
                "pointsEarned": 1.0,
                "amountSpent": {
                  "currencyCode": "USD",
                  "units": "1"
                }
              }
            }
          }
        }
      ],
      "requirements": {
        "freeToJoin": true
      },
      "signupUrl": "https://www.example.com/my-rewards/gold"
    }
  ],
  "programDescriptions": [
    "a new description of the program"
  ],
  "signupUrl": "https://www.example.com/my_rewards_signup",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ],
  "advancedSettings": {
    "hideDisplayFromNonMembers": true
  }
}
```

#### Full replacement without update mask

When you omit the `update_mask` parameter, the request performs a complete
replacement of the loyalty program configuration.

Here's a sample request:

### HTTP

```console
PATCH https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}

{
  "programName": "Updated Program",
  "signupUrl": "https://example.com/updated",
  "programDescriptions": [
    "Updated description"
  ],
  "regionCodes": [
    "US"
  ],
  "tiers": [
    {
      "tierName": "Gold Tier",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "Free shipping"
        }
      ],
      "requirements": {
        "freeToJoin": true
      }
    }
  ]
}
```

Here's a sample response from a successful request:

```json
{
  "name": "accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/my-rewards",
  "programName": "Updated Program",
  "tiers": [
    {
      "tierName": "Gold Tier",
      "tierLabel": "gold",
      "tierBenefits": [
        {
          "otherBenefit": "Free shipping"
        }
      ],
      "requirements": {
        "freeToJoin": true
      }
    }
  ],
  "programDescriptions": [
    "Updated description"
  ],
  "signupUrl": "https://example.com/updated",
  "reviewResult": {
    "reviewStatus": "UNDER_REVIEW"
  },
  "regionCodes": [
    "US"
  ]
}
```

### Delete a loyalty program

To delete a loyalty program from your account, use the
`loyaltyPrograms.delete` method.

Here's a sample request:

### HTTP

```console
DELETE https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty/loyaltyPrograms/{PROGRAM_LABEL}
```

If successful, the response body is empty.

## Next steps

- To associate individual shoppers with your loyalty program tiers for organic personalization on Google Search, see the [Loyalty Customer Match Service guide](https://developers.google.com/merchant/api/guides/loyalty/customer-match-service.md.txt).
- To enable or disable shopping programs for your account, see the [Programs sub-API guide](https://developers.google.com/merchant/api/guides/programs/overview.md.txt).
- For business setup details, editorial policies, and reporting, see [About merchant loyalty program](https://support.google.com/merchants/answer/12827255) in Merchant Center Help.
- To explore API methods and resource definitions, see the [Merchant API reference](https://developers.google.com/merchant/api/reference/rest.md.txt).