This article lists all of the attributes that you can provide in your promotions data source.
To use promotions, you can submit your product data to Google through a data source. The information within your data source is then distributed across different Google properties, including Google Search, the Shopping tab, Chrome and more. Promotions will display for customers on desktop and mobile devices in Australia, Brazil, Canada, France, Germany, India, Italy, Japan, South Korea, Spain, the Netherlands, the United Kingdom and the United States.
Submit a promotions data source
File type: You can use either an XML file, tab-delimited file or Google spreadsheet. View an example data source template
Registering and uploading a new data source: Follow the steps to register and upload a new promotions data source. Upload your promotions source to the same Merchant Center account that you use for your online product data source.
Create promotions to target specific products
You can create promotions for specific products in the following ways:
- Apply product filter attributes in your promotions data source: If a promotion applies to specific products in your product data source, you may use product filter attributes. View Product filters.
- Map the promotion ID to products in your product data source: For Google to recognise the products included in your promotion, submit a value for the promotion ID
[promotion ID]attribute and map that to the eligible products in your product data source. For more information about mapping, view How to create a promotion for specific products.
If you set product filters on the promotions data sources and explicit promotion IDs in the product data source, then the promotion applies to products selected by both applying product filter attributes and mapping the promotion ID to your products.
Basic promotions data
Include the following attributes in your data source to define how your promotions will display:
| Attribute | Minimum requirements at a glance |
|---|---|
Promotion ID [promotion_id]
Syntax
|
This attribute is the unique ID of a promotion. The promotion ID |
|
Products eligible for promotion
Supported values
|
This attribute specifies if the promotion applies to all products or only to specific products.
|
|
Coupon code required
Supported values
If the value for this attribute is
|
This attribute indicates whether or not a coupon code is required for customers to redeem the offer. Note: All delivery promotions must include a valid redemption code.
Learn more about how to include redemption codes for delivery promotions in the promotions programme policies. |
Promotion title [long_title]
Syntax
Example
|
This attribute specifies the full title of the promotion. Important: Follow our editorial requirements closely. They outline title requirements and provide helpful examples of acceptable and unacceptable titles. The title should describe the promotion completely and accurately. |
Promotion start date [promotion_effective_dates]
Syntax
Example If your promotion is valid from 3.00 a.m. on 19 July 2009 to 9.00 p.m. on 26 July 2009 EST (Eastern Standard Time), you would submit:
If your promotion is valid from 3.00 a.m. on 19 July 2009 to 9.00 p.m. on 26 July 2009 GMT (Greenwich Mean Time), you would submit:
|
Important:
If you use the promotion builder, it will only support the promotion start date Tip: You can validate your promotion before it starts by using the promotion display dates |
|
Eligible channel for promotion Note: This attribute is only available in the classic Merchant Center experience.
Supported values
Important:
|
This attribute indicates that the promotion is valid online, in store or both. |
|
Promotion destination
Supported values
Add a supported value to your data source. To submit your promotion to one or more destination, submit each destination value as a separate column:
Important: If you use the promotion destination |
Important: These are repeated fields, and values are supported simultaneously. Values indicated in this field will overwrite any product defaults. For more details on repeated fields, view About attributes with repeated fields. Note:
|
|
Shop applicability
Supported values
|
This attribute indicates whether your promotion is applicable to all shops or only specific shops. Important:
|
|
Shop codes inclusion
|
This attribute indicates the specific shops to which your promotion applies. Important:
|
|
Shop codes exclusion
|
This attribute indicates the specific shops from which your promotion is excluded. Important:
|
|
|
The promotion URL must be a link pointing to the page on your website where customers can find the promotion details. The information present on the page with your promotion’s details must match the promotion data submitted. |
Shopping Actions, Surfaces across Google, Local surfaces across Google. These values will still be accepted, but we recommend that you update your products to include the new values for these destinations: Free_listings, Free_local_listings.Product filters
If you create a promotion that only applies to specific products in your product data source, use the product filter in your promotion source. The product filter attributes only apply when the products eligible for promotion [product_applicability] attribute is set to specific_products. All the attributes under this section are repeated fields with a limit up to 1,000 in XML/CSV.
The product filter attributes in the table below determine the products that apply for a promotion. When the same attribute is used more than once, the product must match at least one of the attributes for the filter to apply. When there are multiple filters, only the products that pass all filters are selected for the promotion. If a filter excludes a product and another filter includes the same product, the product will be excluded from the promotion.
Example:
For example, if you create a promotion for brand = "example1" and product_type = “Tshirt”, the promotion will apply only to those products in the product data source that have brand =“example1” and product_type = “Tshirt”.
Alternatively, you can also link a product to a specific promotion by setting the promotion ID [promotion_id] attribute in the product data source.
| Attribute | Description |
|---|---|
|
Product ID for promotion Syntax
|
The promotion only applies to products that match the product ID for promotion Note: The product ID for promotion |
|
Product type Syntax
|
The promotion only applies to products that match the product type specified in this attribute. |
|
Brand Syntax
|
The promotion only applies to products that match the brand specified in this attribute. |
|
Item group ID
Syntax
|
This promotion applies to products that match the item group ID |
|
Excluded item ID
Syntax
|
Products with one of these item IDs are excluded from the promotion. |
|
Excluded product types
Syntax
Example Rings |
Products with one of these product types are excluded from the promotion. |
|
Excluded brands Syntax
Example Acme products |
Products with one of these brands are excluded from the promotion. |
|
Excluded item group ID Syntax
|
Products with an excluded item group ID are excluded from the promotion. |
|
Custom label 0–4
Syntax
|
The promotion only applies to products that match the specific custom labels specified in this attribute. |
|
Excluded custom label 0–4
Syntax
|
Products with one of these custom labels are excluded from the promotion. |
Promotion details
The following sections describe the different attributes that you can use to create structured promotions, such as 'Buy N, get M'.
- Preconditions are used to set up the requirements that must be met for the customer to redeem the promotion
- Promotion categories determine the type of promotion
- Limits determine the restrictions that you can apply to your promotions. For example, you can set a limit on the minimum price or quantity of eligible purchases required for a customer to receive a promotion.
Preconditions
This attribute communicates the precondition or a minimum purchase amount that a customer needs to meet to redeem a promotion. It does not filter the products that are eligible for a promotion. To filter, use product filters.
For example, if you want to create:
- A 'Free-of-charge delivery with £50 purchase' promotion, set the minimum purchase amount
[minimum_purchase_amount]attribute to 50 GBP. - A 'Free-of-charge tote bag with £100 purchase' promotion, set the minimum purchase amount
[minimum_purchase_amount]attribute to 100 GBP.
| Attribute | Description |
|---|---|
Minimum purchase amount [minimum_purchase_amount]
Syntax Promotions sources only support currencies of the specified locales. Example 20 GBP |
This attribute sets the minimum purchase amount for the promotion to be redeemed. For example, for X amount of purchases of the same product or a combination of products, the customer will receive promotion Y. |
|
Minimum purchase quantity for promotion
Syntax Must be an integer Example
|
The attribute specifies the number of items needed to buy to qualify for the promotion. |
|
Redemption restriction
Example Enum |
List of values:
|
|
Custom redemption condition
Syntax
|
This attribute sets the custom redemption condition if the redemption_restriction is custom. |
Promotion categories
The table below shows the types of promotion categories. Specify a promotion category to create a structured promotion, such as a 'Buy one, get one free of charge' promotion. Learn more about structured data attributes
You can associate only one promotion category with a promotion ID [promotion_id]. You can further restrict a promotion category with limits. View Limits.
| Attribute | Description |
|---|---|
|
Percentage discount amount
Syntax Must be an integer Example 10 |
This attribute specifies the percentage discount offered in the promotion. For example, 10% off. |
|
Monetary discount amount of a promotion
Syntax Must be a number and the currency Example 20.00 GBP |
This attribute specifies the discount amount. For example, 20.00 GBP off. |
|
Quantity eligible for promotion
Syntax Must be an integer Example 2 |
This attribute specifies the number of items to which the promotion or discount applies and when the promotion type is For example, set this attribute to 1 for a 'Buy two, get one free of charge' (100% off) promotion. |
|
Free-of-charge delivery
Supported values
Note: This attribute is not supported for local promotions |
This attribute specifies the type of free-of-charge delivery offered in the promotion. |
|
Free-of-charge gift of monetary value
Syntax Must be a number and specify currency Example 400.00 GBP |
This attribute specifies the monetary value of the free-of-charge gift offered in the promotion. |
|
Free-of-charge gift description
Syntax String should not exceed 100 characters Example Free-of-charge tote bag with 100.00 GBP purchase. |
This attribute is the description, but not the value, of any free-of-charge gift offered in the promotion. Use the free-of-charge gift item ID |
|
Free-of-charge gift item ID
Syntax
|
This attribute specifies a free-of-charge gift if it's an item in your product data source. The product ID for promotion The product ID for promotion |
|
Coupon value type
Supported values:
|
This attribute signals the type of promotion that you’re running, allowing Google to perform a more automated review process, which can expedite promotion approval. When you use the optional coupon value type For example, if you set the coupon value type Note: The attributes [coupon_value_type] attribute. |
|
Minimum money off amount
Syntax Must be a number and specify currency. Example 50.00 GBP |
Set if the If the
|
|
Maximum money-off amount
Syntax Must be a number and specify currency. Example 50.00 GBP |
Set if the If the
money_off_range is not specified. |
|
Minimum percent off |
Set if the If the
|
|
Maximum percent off |
This attribute is a number between 1 and 99 and should be larger than Set if the If the
percent_off_range is not specified. |
Attributes to use with coupon_value_type in your promotions source
The following list of supported coupon value type [coupon_value_type] values shows the required and optional data source attributes for each.
No structured data [no_structured_data]
- Required: None
- Optional: Minimum purchase amount
[minimum_purchase_amount], minimum purchase quantity for promotion[buy_this_quantity], maximum purchase quantity for promotion[limit_quantity], maximum product price for promotion[limit_value], price for promotion[promotion_price], monetary discount amount of a promotion[money_off_amount], percentage discount amount[percent_off], quantity eligible for promotion[get_this_quantity_discounted], free-of-charge gift monetary value [free_gift_value], free-of-charge gift item ID[free_gift_item_id], free-of-charge gift description[free_gift_description]
Cashback [cash_back]
- Required: Cashback amount
[cash_back_amount] - Optional: None
Percentage cashback [percentage_cash_back]
- Required: Cashback percentage
[cash_back_percentage] - Optional: None
Money off [money_off]
- Required: Monetary discount amount of a promotion
[money_off_amount] - Optional: Minimum purchase amount
[minimum_purchase_amount]
Money-off range [money_off_range]
- Required: Either minimum monetary discount amount of a promotion
[min_money_off_amount]or maximum monetary discount amount of a promotion[max_money_off_amount]should be set, or both should be set. - Optional: None
Percentage off [percent_off] 'range'
- Required: Either minimum percentage discount amount
[min_percent_off_amount]or maximum percentage discount amount[max_percent_off_amount]should be set, or both should be set. - Optional: None
Percentage discount amount [percent_off]
- Required: Percentage discount amount
[percent_off] - Optional: Minimum purchase amount
[minimum_purchase_amount]
Buy M, get N money off [buy_m_get_n_money off]
- Required: Monetary discount amount of a promotion
[money_off_amount], minimum purchase quantity for promotion[buy_this_quantity], quantity eligible for promotion[get_this_quantity_discounted] - Optional: None
Buy M, get N percent off [buy_m_get_n_percent_off]
- Required: Percentage discount amount
[percent_off], minimum purchase quantity for promotion[buy_this_quantity], quantity eligible for promotion[get_this_quantity_discounted] - Optional: None
Buy M, get money off [buy_m_get_money_off]
- Required: Monetary discount amount of a promotion
[money_off_amount], minimum purchase quantity for promotion[buy_this_quantity] - Optional: None
Buy M, get percent off [buy_m_get_percent_off]
- Required: Percentage discount amount
[percent_off], minimum purchase quantity for promotion[buy_this_quantity] - Optional: None
Free-of-charge gift [free_gift]
- Required: Free-of-charge gift description
[free_gift_description] - Optional: Minimum purchase amount
[minimum_purchase_amount], minimum purchase quantity for promotion[buy_this_quantity]
Free-of-charge gift monetary value [free_gift_with_value]
- Required: Free-of-charge gift monetary value
[free_gift_value] - Optional: Minimum purchase amount
[minimum_purchase_amount], minimum purchase quantity for promotion[buy_this_quantity]
Free-of-charge gift item ID [free_gift_with_id]
- Required: Free-of-charge gift item ID
[free_gift_item_id] - Optional: Minimum purchase amount
[minimum_purchase_amount], minimum purchase quantity for promotion[buy_this_quantity]
Free-of-charge delivery standard [free_shipping_standard]
- Required: None
- Optional: Free-of-charge delivery type
[free_shipping_type], minimum purchase amount[minimum_purchase_amount], minimum purchase quantity for promotion[buy_this_quantity]
Free-of-charge delivery overnight [free_shipping_overnight]
- Required: None
- Optional: Free-of-charge delivery type
[free_shipping_type], minimum purchase amount[minimum_purchase_amount], minimum purchase quantity for promotion[buy_this_quantity]
Free-of-charge delivery two day [free_shipping_two_day]
- Required: None
- Optional: Free-of-charge delivery type
[free_shipping_type], minimum purchase amount[minimum_purchase_amount], minimum purchase quantity for promotion[buy_this_quantity]
Free-of-charge delivery with delivery config [free_shipping_with_shipping_config]
- Required: None
- Optional: None
Limits
These attributes communicate the limits that a customer needs to meet to redeem a promotion. Limits don't filter the products that are eligible for a promotion. To filter, use Product filters.
For example:
- 'Buy one, get one free of charge, up to 10 items' set maximum purchase quantity for promotion
[limit_quantity]to 10. - '10% off, up to order value £100', set maximum product price for promotion
[limit_value]to £100.
| Attribute | Description |
|---|---|
|
Maximum purchase quantity for promotion
Syntax Must be an integer Example 5 |
This attribute is used to communicate the maximum number of items that can be bought using this promotion. |
|
Maximum discount amount limit
Syntax Must be a number and specify currency. Example 50.00 GBP |
This attribute communicates the maximum discount value of this promotion. This is used for |
Additional attributes
| Attribute | Description |
|---|---|
|
Display dates for promotion
Syntax Start date and end date are separated by a forward slash (/). The date format is (YYYY-MM-DD), followed by the letter ‘T’, the time of the day when the sale starts or ends, and by an expression of the time zone for the sale. Example If your promotion was valid from 3.00 a.m. on 19 July 2009 to 9.00 p.m. on 26 July 2009 EST (Eastern Standard Time), you would submit:
If your promotion was valid from 3.00 a.m. on 19 July 2009 to 9.00 p.m. on 26 July 2009 GMT (Greenwich Mean Time), you would submit:
|
Important:
This attribute specifies the date and time frame when the promotion will be live on Google.com and Shopping ads. If the display dates for promotion |
|
Syntax
|
This attribute specifies the promotion description. The description is not shown to customers |
|
Generic redemption code
Syntax
Example EXTRA20 |
This attribute specifies the code that customers can use online to redeem the promotion. It's required if the coupon code required Note: All delivery promotions must include a valid redemption code. Free-of-charge-delivery promotions must include a valid coupon code that shoppers can manually apply. Otherwise, delivery will be treated as a service that is normally offered and must be specified in the product data source. If the promotion is offered for a specific duration, then the duration must also be reflected in the product data source. See Promotions programme policies for more information. |
|
Syntax
|
This attribute is a link to an image that features the promotion or the promotional item. |
|
Fine print for promotion
Syntax
|
This attribute is the text of any terms and conditions that apply to the promotion, such as restrictions and exclusions. The terms and conditions will be shown to the customer along with the generic redemption code. |
|
Price for promotion
Syntax Must be a number and the currency. Example 15.00 GBP |
This attribute is the promotional sales price of an item or category. For example, a promotion in which all jeans are £50. The promotion price is available to customers who enter a promotion code or meet the promotional requirements. |
To express interest in promotions, fill inthis form.
Create a sale event in feed
Follow the sample CSV to upload products and events.
Here are the detailed explanations for the attributes related to sale events.
Sale event is only available for the promotions targeted for the United Kingdom.
| Attribute | Format | Description |
|---|---|---|
Promotion destination [promotion_destination] |
Supported value
|
Currently, to enrol in events, [Free_listings] must be set as the only promotion destination |
Coupon value type [coupon_value_type] |
Supported values
|
All the existing coupon value types are supported for event. |
|
Event applicability
|
Supported values
[specific_categories] |
Event applicability for this promotion. If event applicability is set to Event applicability, which indicates event, cannot be set up together with product applicability If you choose to set up an event, event applicability is a required field. Otherwise, product applicability |
Promotion URL [promotion_url] |
Required for event Syntax
|
|
Google product category[google_product_category] |
Optional Set if “ Supported values Predefined Google product category: The ID or the full path of the product category. You may submit either the ID or the full path, but not both. Download a list of all Google product categories: To prevent garbled text in the .txt version: Change your browser encoding to Unicode UTF-8.
Repeated field Yes. There can be up to five Google product categories |
Example
or
|