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.
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_statusfield indicates whether the program isUNDER_REVIEW,APPROVED, orREJECTED. 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
regionCodesmust be a subset of theactiveRegionCodesofaccounts/{ACCOUNT_ID}/programs/loyalty. Otherwise, create, update, and delete requests fail with aLOYALTY_PROGRAM_DISABLEDerror. Google activates a supported country when the Loyalty program add-on is enabled and the account meets the eligibility requirements 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 theFREE_LISTINGSdestination. To find out why a country isn't active, see Check 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 in Merchant Center Help.
- Programs sub-API: Enable the program programmatically as
described in
Enable programs in Programs sub-API.
The
accounts.programs.enablemethod requires administrator access.
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.
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
Check active regions
After you enable the Loyalty program add-on, call the
accounts.programs.get method
for accounts/{ACCOUNT_ID}/programs/loyalty. The response
shows where you can use loyalty programs and why other supported countries are
inactive.
Here's a sample request:
HTTP
GET https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/programs/loyalty
cURL
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 {ACCOUNT_ID} 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:
{
"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 theregionCodesof your loyalty program. In the preceding sample, onlyUSis active.unmetRequirements: The reason other supported countries are inactive. For loyalty programs, this is theIS_ELIGIBLE_FOR_LOYALTYrequirement.affectedRegionCodes: The supported countries where the account isn't eligible.documentationUri: A link to the eligibility requirements.
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:
- 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_LISTINGSdestination. For all the ways to become eligible, see the eligibility requirements. - Call
accounts.programs.getagain, and check that the country is inactiveRegionCodes.
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.createloyaltyPrograms.getloyaltyPrograms.listloyaltyPrograms.updateloyaltyPrograms.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.
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.
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. Each successful update triggers a new
editorial review, so send an update only when a value
changes.
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.