Overview of Merchant Promotions API

Use promotions to showcase special offers for products you sell on Google. Promotions display across different Google properties, including Google Search, Shopping, and Chrome. Promotions must meet certain criteria to be approved. For more information, see Promotion criteria.

When you add a promotion to your products, shoppers see a special offer link. For example, "15% off" or "Free shipping". Offer links can increase the appeal of your products and encourage shoppers to make a purchase. All promotions are applied at checkout or point of sale.

For more information, see Promotion basics.

Prerequisites

Google needs you to provide specific information about your business and products prior to displaying your promotions. You must have the following:

In addition, you must enroll your merchant account in the Promotions program. If you are unsure whether you are already enrolled, check the Merchant Center.

If you are not enrolled, complete the request form. The promotions team will let you know when you are ready to start implementation.

For more information, see Participation criteria and policies.

Create a data source

You can use the accounts.dataSources.create method to create a promotion data source. If an existing promotion data source is available, use the accounts.dataSources.list method to retrieve all the data sources. You can then use the name field of the promotion data source to create promotions.

The following request shows how to create a data source for adding promotions:

POST https://merchantapi.googleapis.com/datasources/v1beta/accounts/{ACCOUNT_ID}/dataSources

{
  "displayName": "{DISPLAY_NAME}",
  "promotionDataSource": {
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "targetCountry": "{TARGET_COUNTRY}"
  }
}

Replace the following:

  • {ACCOUNT_ID}: The unique identifier of your account as it appears in the Merchant Center UI.
  • {DISPLAY_NAME}: The display name of the data source.
  • {CONTENT_LANGUAGE}: The two-letter ISO 639-1 language code of the products in the data source.
  • {TARGET_COUNTRY}: The CLDR territory code of the target country where you want the promotions to be visible.

After the request runs successfully, you see the following response that contains details about the newly created promotions data source:

{
  "name": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}",
  "dataSourceId": "{DATASOURCE_ID}",
  "displayName": "{DISPLAY_NAME}",
  "promotionDataSource": {
    "targetCountry": "{TARGET_COUNTRY}",
    "contentLanguage": "{CONTENT_LANGUAGE}"
  },
  "input": "API"
}

Create promotions

You can use the accounts.promotions.insert method to create or update a promotion. The accounts.promotions.insert method takes a promotions resource and a data source name as input. It returns the new or updated promotion, if successful.

Creating a promotion requires the name of the data source. You must also provide values for the following fields in your request:

  • contentLanguage
  • redemptionChannel
  • promotionId
  • targetCountry
  • attributes.offerType
  • attributes.genericRedemptionCode
  • attributes.couponValueType
  • attributes.productApplicability
  • attributes.promotionEffectiveTimePeriod.endTime
  • attributes.promotionEffectiveTimePeriod.startTime
  • attributes.longTitle

Google reviews and approves your promotions before distributing them. For more information, see Promotion approval process.

We recommend that you go through the Promotions policies to make sure that the promotions you create add value and adhere to Shopping ads policies.

The following request demonstrates how to create an online promotion:

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
  "promotion": {
    "name": "{PROMOTION_NAME}",
    "promotionId": "{PROMOTION_ID}",
    "targetCountry": "{TARGET_COUNTRY}",
    "redemptionChannel": [
      "ONLINE"
    ],
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "attributes": {
      "promotionDisplayTimePeriod": {
        "endTime": "{PROMOTION_END_TIME}",
        "startTime": "{PROMOTION_START_TIME}"
      },
      "offerType": "{OFFER_TYPE}",
      "longTitle": "{LONG_TITLE}"
    }
  },
  "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
}

For information about the rules applicable to setting your promotion ID, see Minimum requirements for promotion ID attribute.

The valid values for the mandatory offerType field are NO_CODE and GENERIC_CODE. If you don't provide one of these values, the API request fails with the HTTP 400 response [offer_type] validation/missing_required: Invalid or missing required attribute: offer_type. A similar error message is returned if you don't provide any of the mandatory fields.

If you don't provide a value for the attributes.genericRedemptionCode field, the request fails with the HTTP 400 response [genericRedemptionCode] No redemption code provided.

The values for the promotion.attributes.promotionDisplayTimePeriod.startTime and promotion.attributes.promotionDisplayTimePeriod.endTime fields must be in the format yyyy-mm-ddThh:mm:ssZ. Make sure to replace the values for these fields with dates that are in the future.

For more information, see Promotions data specification.

For best practices about creating a promotion, see Promotions best practices.

For a list of promotions-related attributes, see Add structured data attributes.

After promotion creation request runs successfully, it can take a few minutes for the promotion to be retrievable using the API or to appear in the Merchant Center.

The following are some sample promotions that you can use to get started.

A local promotion applicable for all products and all stores

The following sample request shows how to create a local promotion that is applicable for all the products in your Merchant Center account and all the stores added in your linked Business Profile account.

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
  "promotion": {
    "promotionId": "buy_2_get_10_off",
    "contentLanguage": "en",
    "targetCountry": "US",
    "redemptionChannel": [
      "IN_STORE"
    ],
    "attributes": {
      "longTitle": "Buy 2 and get 10$ OFF purchase",
      "productApplicability": "ALL_PRODUCTS",
      "offerType": "NO_CODE",
      "couponValueType": "BUY_M_GET_MONEY_OFF",
      "promotionDisplayTimePeriod": {
        "startTime": "2024-2-06T00:47:44Z",
        "endTime": "2024-5-06T00:47:44Z"
      },
      "promotionEffectiveTimePeriod": {
        "startTime": "2024-2-06T00:47:44Z",
        "endTime": "2024-5-06T00:47:44Z"
      },
      "moneyOffAmount": {
        "amountMicros": "1000000",
        "currencyCode": "USD"
      },
      "minimumPurchaseQuantity": 2,
      "storeApplicability": "ALL_STORES",
      "promotionUrl": "http://promotionnew4url.com/",
      "promotionDestinations": [
        "LOCAL_INVENTORY_ADS"
      ],
    }
  },
  "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}"
}

The productApplicability field is required. It signals the applicability of the promotion to either all products or only specific ones. The supported values are ALL_PRODUCTS and SPECIFIC_PRODUCTS. For more information, see Choose products for your promotion.

The couponValueType field is required. It signals the type of promotion that you are running. For the list of support values, see Coupon value type. Depending on the type of coupon value you selected, some attributes are required.

The minimumPurchaseQuantity field lets you set the value for the minimum purchase quantity that is required to redeem the promotion offering. For more information, see Minimum purchase quantity for promotion.

Similarly, you can use the minimumPurchaseAmount field to set the minimum purchase amount that is required to redeem the promotion. For more information, see Minimum purchase amount.

For more information about the values you need to provide for creating a local promotion, see Data source specifications for local promotions.

An online promotion applying to selected products with a redemption code

The following sample request shows how to create an online promotion that applies to selected products with a redemption code.

POST https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions:insert

{
 "promotion": {
   "promotionId": "25_pct_off",
   "contentLanguage": "en",
   "targetCountry": "US",
   "redemptionChannel": [
     "ONLINE"
   ],
   "attributes": {
     "longTitle": "10% off on selected items",
     "productApplicability": "SPECIFIC_PRODUCTS",
     "offerType": "GENERIC_CODE",
     "genericRedemptionCode": "SPRINGSALE",
     "couponValueType": "PERCENT_OFF",
     "promotionDisplayTimePeriod": {
       "startTime": "2024-2-06T00:47:44Z",
       "endTime": "2024-5-06T00:47:44Z"
     },
     "promotionEffectiveTimePeriod": {
       "startTime": "2024-2-06T00:47:44Z",
       "endTime": "2024-5-06T00:47:44Z"
     },
     "percentOff": 25,
     "promotionDestinations": [
       "FREE_LISTINGS"
     ],
     "itemIdInclusion": [
       "1499860100",
       "1499860101",
       "1499860102",
       "1499860103",
       "1499860104"
     ],
   }
 },
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/1000000573361824"
}

View promotions

To view a promotion, use accounts.promotions.get. This GET request is read-only. It requires your merchantId and the ID of the promotion. The GET method returns the corresponding promotions resource.

For example:

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/{PROMOTION_ID}

Replace the following:

  • {ACCOUNT_ID}: The unique identifier of your Merchant Center account.
  • {PROMOTION_ID}: The unique identifier of the promotion you want to retrieve. The format is {CHANNEL}~{CONTENT_LANGUAGE}~{TARGET_COUNTRY}~{PROMOTION_ID}.

Note that it takes a few minutes for a newly created promotion to be retrievable using the API.

View a local promotion

The following sample request retrieves a local promotion whose promotion ID is in_store~en~US~buy_2_get_10_off.

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/in_store~en~US~buy_2_get_10_off

After the request is successful, you see the following response:

{
 "name": "accounts/{ACCOUNT_ID}/promotions/in_store~en~US~buy_2_get_10_off",
 "promotionId": "buy_2_get_10_off",
 "contentLanguage": "en",
 "targetCountry": "US",
 "redemptionChannel": [
   "IN_STORE"
 ],
 "attributes": {
   "longTitle": "Buy 2 and get 10$ OFF purchase",
   "productApplicability": "ALL_PRODUCTS",
   "offerType": "NO_CODE",
   "couponValueType": "BUY_M_GET_MONEY_OFF",
   "promotionDisplayTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "promotionEffectiveTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "moneyOffAmount": {
     "amountMicros": "1000000",
     "currencyCode": "USD"
   },
   "minimumPurchaseQuantity": 2,
   "storeApplicability": "ALL_STORES",
   "promotionUrl": "http://promotionnew4url.com/",
   "promotionDestinations": [
     "LOCAL_INVENTORY_ADS"
   ],
 }
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/1000000573361824"
}

The moneyOffAmount field in this sample provides the discount that is offered in the promotion. For more information, see Monetary discount amount of a promotion.

The promotionUrl field in this sample provides the link to the store's website where shoppers can find more information about the promotion. Local inventory ads promotions return an error if you don't include the promotionUrl field.

View an online promotion

The following sample request retrieves an online promotion whose promotion ID is online~en~US~25_pct_off.

GET https://merchantapi.googleapis.com/promotions/v1beta/accounts/{ACCOUNT_ID}/promotions/online~en~US~25_pct_off
{
 "name": "accounts/{ACCOUNT_ID}/promotions/online~en~US~25_pct_off",
 "promotionId": "25_pct_off",
 "contentLanguage": "en",
 "targetCountry": "US",
 "redemptionChannel": [
   "ONLINE"
 ],
 "attributes": {
   "longTitle": "10% off on selected items",
   "productApplicability": "SPECIFIC_PRODUCTS",
   "offerType": "GENERIC_CODE",
   "genericRedemptionCode": "WINTERGIFT",
   "couponValueType": "PERCENT_OFF",
   "promotionDisplayTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "promotionEffectiveTimePeriod": {
     "startTime": "2024-2-06T00:47:44Z",
     "endTime": "2024-5-06T00:47:44Z"
   },
   "percentOff": 25,
   "promotionDestinations": [
     "FREE_LISTINGS"
   ],
   "itemIdInclusion": [
     "1499860100",
     "1499860101",
     "1499860102",
     "1499860103",
     "1499860104"
   ],
 }
 "dataSource": "accounts/{ACCOUNT_ID}/dataSources/{dataSource}"
}

The itemIdInclusion field used in this sample mentions the products that are eligible for the promotion. For more information, see Product ID for promotion.

List promotions

You can use the promotions.list method to view all the created promotions.

GET https://merchantapi.googleapis.com/promotions/v1beta/{ACCOUNT_ID}/promotions

The response contains the list of all the promotions in your account. For each promotion, you can see details like the promotionId, redemptionChannel, dataSource, promotionStatus, and more.

View the status of a promotion

To see a promotion's status, see the promotionStatus attribute returned by the promotions.get or promotions.list method.

The promotionStatus field can have the following values:

  • IN_REVIEW: The promotion is still in review.
  • REJECTED: The promotion is disapproved.
  • LIVE: The promotion is approved and active.
  • STOPPED: The promotion is stopped by the account.
  • EXPIRED: The promotion is no longer active.
  • PENDING: The promotion is not stopped, and all reviews are approved, but the active date is in the future.
  • STATE_UNSPECIFIED: Unknown promotion state.

To understand the approval process for a promotion that you created, see Promotion approval process.

Sample promotion status

The following samples demonstrate the difference between successful and failing requests.

Missing product mapping

The following response body shows an online promotion that is disapproved due to missing product mapping.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "REJECTED"
      }
    ],
    "itemLevelIssues": [
      {
        "code": "promotion_sku_unmapped",
        "severity": "DISAPPROVED",
        "resolution": "merchant_action",
        "reportingContext": "FREE_LISTINGS",
        "description": "Unmapped",
        "detail": "This promotion couldn't be tested during review because it doesn't apply to any products that are currently in your Products feed",
        "documentation": "https://support.google.com/merchants/answer/2906014",
        "applicableCountries": [
          "US"
        ]
      },
      {
        "code": "promotion_sku_additional_requirements",
        "severity": "DISAPPROVED",
        "resolution": "merchant_action",
        "reportingContext": "FREE_LISTINGS",
        "description": "Promotion conditions not allowed",
        "detail": "This promotion has additional requirements that are not allowed such as requiring customers to verify additional details like phone number or ID before showing the promotion details",
        "documentation": "https://support.google.com/merchants/answer/2906014",
        "applicableCountries": [
          "US"
        ]
      }
    ]
  }

For troubleshooting disapproved promotions and to learn how to avoid future disapprovals, see Fix issues with disapproved promotions.

If a promotion you created isn't approved, you receive an email mentioning the reason of rejection and instructions to fix the issues.

Promotion under evaluation

The following response body shows a promotion that is still being evaluated.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "PENDING"
      },
      {
        "destination": "SHOPPING_ADS",
        "status": "PENDING"
      }
    ],
    "itemLevelIssues": []
  }

An approved and live promotion

The following response body shows a promotion that is visible to shoppers.

  "promotionStatus": {
    "destinationStatuses": [
      {
        "reportingContext": "FREE_LISTINGS",
        "status": "LIVE"
      },
      {
        "destination": "SHOPPING_ADS",
        "status": "LIVE"
 }  ],
    "itemLevelIssues": []
  }

For more information, see Promotion status FAQs.

Learn more