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`.
- **Supported regions:** Merchant loyalty programs are available in supported countries, including Australia, Brazil, Canada, France, Germany, India, Italy, Mexico, Netherlands, South Korea, Spain, the United Kingdom, and the United States.
- **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#enable).

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

### HTTP

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

### cURL

    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

## Methods

Manage loyalty programs using the following methods:

- [`loyaltyPrograms.create`](https://developers.google.com/merchant/api/guides/loyalty/loyalty-programs#create)
- [`loyaltyPrograms.get`](https://developers.google.com/merchant/api/guides/loyalty/loyalty-programs#get)
- [`loyaltyPrograms.list`](https://developers.google.com/merchant/api/guides/loyalty/loyalty-programs#list)
- [`loyaltyPrograms.update`](https://developers.google.com/merchant/api/guides/loyalty/loyalty-programs#update)
- [`loyaltyPrograms.delete`](https://developers.google.com/merchant/api/guides/loyalty/loyalty-programs#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

    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:

    {
      "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

    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:

    {
      "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

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

Here's a sample response of a successful request:

    {
      "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.

> [!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.

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

### HTTP

    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:

    {
      "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

    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:

    {
      "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

    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).
- To enable or disable shopping programs for your account, see the [Programs sub-API guide](https://developers.google.com/merchant/api/guides/programs/overview).
- 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).