Overview of loyalty programs

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: 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 under What is the issue/question? > Allowlist request > Other.

For more information about business requirements and policy guidelines, see About merchant loyalty program 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 in Merchant Center Help.
  • Programs sub-API: Enable the program programmatically as described in Enable programs in Programs sub-API.

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
• loyaltyPrograms.get
• loyaltyPrograms.list
• loyaltyPrograms.update
• loyaltyPrograms.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 {ACCOUNT_ID} 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: 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 {ACCOUNT_ID} with your account ID and {PROGRAM_LABEL} 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: 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: 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.
• To enable or disable shopping programs for your account, see the Programs sub-API guide.
• For business setup details, editorial policies, and reporting, see About merchant loyalty program in Merchant Center Help.
• To explore API methods and resource definitions, see the Merchant API reference.