This article lists all of the attributes 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 you use for your online products 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 promotion 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 recognize 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 products data source. For more information about mapping, view how to create a promotion for specific products .
If you set product filters on the promotion 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:
[promotion_id]
Required
Syntax
- Maximum length is 50 characters
- Case sensitive
- Should not contain spaces or symbols, such as % and !
This attribute is the unique ID of a promotion.
The promotion ID [promotion_id]
attribute is used to link promotions to specific products.
Products eligible for promotion [product_applicability]
Required
Supported values
- All products
[all_products] - Specific products
[specific_products]
This attribute specifies if the promotion applies to all products or only to specific products.
- If the value is specific products
[specific_products], you must use product filter attributes or map a promotion ID[promotion_id]to applicable products in your products data source. These specific products are continuously tested for the duration of the promotion. - If the value is all products
[all_products], you don't need to use product filter attributes or a promotion ID[promotion_id]in the products data source. The promotion validity is tested against all of the items in your products data source.
Coupon code required [offer_type]
Required
Supported values
- No code
[no_code] - Generic code
[generic_code]
If the value for this attribute is [generic_code]
a code that's the same for all customers, the attribute below is required:
- Generic redemption code
[generic_redemption_code]
This attribute indicates whether or not a coupon code is required for customers to redeem the offer.
Note: All shipping promotions must include a valid redemption code.
- Free shipping promotions must include a valid coupon code that customers can manually apply. Otherwise, shipping will be treated as a service that's normally offered.
Learn more about how to include redemption codes for shipping promotions in the promotions program policies .
[long_title]
Required
Syntax
- Maximum length is 60 characters
Example
- Free mug with purchase
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_effective_dates]
Required
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 day when the sale starts or ends, and an expression of the time zone for the sale.
Example
If your promotion is valid from 3:00 a.m. on July 19, 2009 to 9:00 p.m. on July 26, 2009 EST (Eastern Standard Time), you would submit:
2009-07-19T03:00:00-05:00/2009-07-26T21:00:00-05:00
If your promotion is valid from 3:00 a.m. on July 19, 2009 to 9:00 p.m. on July 26, 2009 GMT (Greenwich Mean Time), you would submit:
2009-07-19T03:00:00+00:00/2009-07-26T21:00:00+00:00
Important:
- GMT is Greenwich Mean Time. -5 hours represents EST while -8 hours represents PST.
- Promotions have a 6-month limit (183 days).
- Daylight Savings: -4 hours represents EDT while -7 hours represents PDT.
If you use the promotion builder, it will only support the promotion start date [promotion_effective_dates]
attribute and the time will default to the time zone of your Merchant Center account setting. If you want the promotion to be in a different time zone, adjust the time zone manually.
Tip: You can validate your promotion before it starts by using the promotion display dates [promotions_display_dates]
attribute. Learn more about Promotions feed formatting and attributes
Eligible channel for promotion [redemption_channel]
Note: This attribute is only available in the classic Merchant Center experience.
Required
Supported values
- Online
[online] - In store
[in_store] - Both
[in_store, online]
Important:
- If this value is left empty, your promotion will default to online
[online]. - This value must include
[in_store]if[promotion_destination]is set to "local inventory_ads".
Promotion destination [promotion_destination]
Required
Supported values
- Shopping ads
[Shopping_ads] - Free listings
[Free_listings] - YouTube affiliate
[YouTube_affiliate] - Local inventory ads
[Local_inventory_ads]
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:
-
promotion_destination: Local_inventory_ads -
promotion_destination: Shopping_ads -
promotion_destination: Free_listings
Important:
If you use the promotion destination [promotion_destination]
attribute, and don't specify a destination by including a supported value in your data source, your promotion will display in Shopping ads and free listings by default.
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:
- The free listings
[Free_listings]destination requires an approved offer for free listings. In addition, we recommend offers submitted via promotions source be in structured format to help ensure faster approval. - The YouTube affiliate destination is being piloted and is currently only available for select merchants.
- When you target a promotion for the Youtube affiliate destination, that promotion cannot be targeted to any additional Promotion destinations because it can lead to un-mapping of the promotion.
Store applicability [store_applicability]
Requiredfor local promotions
Supported values
-
all_stores -
specific_stores
This attribute indicates whether your promotion is applicable to all stores or only specific stores.
Important:
- If
specific_storesis selected, you must also use either the store codes inclusion[store_codes_inclusion]attribute or the store codes exclusion[store_codes_exclusion]attribute. - If
all_storesis selected, the attributes store codes inclusion and store codes exclusion will be ignored.
Store codes inclusion [store_codes_inclusion]
Required ifStore applicability
[store_applicability]
attribute is set to specific stores
.
This attribute indicates the specific stores to which your promotion applies.
Important:
- If your promotion applies to
specific_stores, list those store codes as submitted to your Business Profiles. - You may use either the store codes inclusion
[store_codes_inclusion]or store codes exclusion[store_codes_exclusion]attribute, but not both simultaneously.
Store codes exclusion [store_codes_exclusion]
Required ifStore applicability
[store_applicability]
attribute is set to "specific stores".
This attribute indicates the specific stores from which your promotion is excluded.
Important:
- If your promotion excludes
specific_stores, list those store codes as submitted to your Business Profiles. - You may use either the store codes exclusion
[store_codes_exclusion]or store codes inclusion[store_codes_inclusion]attribute, but not both simultaneously.
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.
Audience [audience]
Supported values
- "
new_users" or "new_customers"
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 repeatedfields 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.
Product ID for promotion [item_id]
Optional
Syntax
- String
- Maximum length is 50 characters
- Case sensitive. Must match the product feed.
The promotion only applies to products that match the product ID for promotion [item_id]
specified in this attribute.
Note: The product ID for promotion [item_id]
attribute matches the ID [id]
attribute in the products data source spec
.
Product type [product_type]
Optional
Syntax
- Unicode characters. We recommend ASCII only.
- Maximum length is 750 characters.
- Case insensitive.
Brand [brand]
Optional
Syntax
- Unicode characters. We recommend ASCII only.
- Maximum length is 70 characters.
- Case insensitive.
The promotion only applies to products that match the brand specified in this attribute.
Item group ID [item_group_id]
Optional
Syntax
- String
- Maximum length is 50 characters
- Case sensitive. Must match the product data source.
This promotion applies to products that match the item group ID [item_group_id]
which is set with this attribute.
Excluded item ID [item_id_exclusion]
Optional
Syntax
- String
- One or more item IDs
- Maximum length is 50 characters.
- Case sensitive. Must match the product data source.
Excluded product types [product_type_exclusion]
Optional
Syntax
- Unicode characters. We recommend ASCII only.
- Maximum length is 70 characters.
- Case insensitive.
Example
Rings
Excluded brands [brand_exclusion]
Optional
Syntax
- String
- Maximum length is 50 characters.
- Case insensitive.
Example
Acme Products
Excluded item group ID [item_group_id_exclusion]
Optional
Syntax
- String
- Maximum length is 50 characters.
- Case sensitive. Must match the product data source.
Custom label 0–4 [custom_label_0-4]
Optional
Syntax
- String
- Maximum length is 50 characters.
- Case insensitive.
Excluded custom label 0–4 [custom_label_0-4_exclusion]
Optional
Syntax
- String
- Maximum length is 50 characters.
- Case insensitive.
Promotion details
The following sections describe the different attributes you can use to create structured promotions, such as “Buy N, get M”.
- Preconditionsare used to set up the requirements that must be met for the customer to redeem the promotion
- Promotion categoriesdetermine the type of promotion
- Limitsdetermine the restrictions 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 shipping with $50 purchase” promotion, set the minimum purchase amount
[minimum_purchase_amount]attribute to 50 USD. - A “Free tote bag with $100 purchase” promotion, set the minimum purchase amount
[minimum_purchase_amount]attribute to 100 USD.
[minimum_purchase_amount]
Optional
Syntax
Promotions sources only support currencies of the specified locales.
Example
20 USD
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.
The value of minimum purchase amount should be equal or more than 1.
Minimum purchase quantity for promotion [buy_this_quantity]
Optional
Syntax
Must be an integer
Example
2
Redemption restriction [redemption_restriction]
Optional
Example
Enum
List of values:
-
subscribe_and_save -
first_order -
sign_up_for_email -
sign_up_for_text -
forms_of_payment (India only) -
custom
Custom redemption condition [custom_redemption_restriction]
Optional
Syntax
- String of the redemption condition
- Maximum length is 50 characters.
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 1, get 1 free” 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
.
| 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], 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 gift monetary value [free_gift_value], free gift item ID[free_gift_item_id], free gift description[free_gift_description], redemption restriction [redemption_restriction], custom redemption condition[custom_redemption_restriction]
Money off [money_off]
- Required: Monetary discount amount of a promotion
[money_off_amount] - Optional: Minimum purchase amount
[minimum_purchase_amount], redemption restriction[redemption_restriction], custom redemption condition[custom_redemption_restriction]
Percent off [percent_off]
- Required: Percent off
[percent_off] - Optional: Minimum purchase amount
[minimum_purchase_amount], redemption restriction[redemption_restriction], custom redemption condition[custom_redemption_restriction]
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: Redemption restriction
[redemption_restriction], custom redemption condition[custom_redemption_restriction]
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: Redemption restriction
[redemption_restriction], custom redemption condition[custom_redemption_restriction]
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: Redemption restriction
[redemption_restriction], custom redemption condition[custom_redemption_restriction]
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: Redemption restriction
[redemption_restriction], custom redemption condition[custom_redemption_restriction]
Free gift [free_gift]
- Required: Free gift description
[free_gift_description] - Optional: Minimum purchase amount
[minimum_purchase_amount], minimum purchase quantity for promotion[buy_this_quantity], redemption restriction[redemption_restriction], custom redemption condition[custom_redemption_restriction]
Free gift monetary value [free_gift_with_value]
- Required: Free gift monetary value
[free_gift_value] - Optional: Minimum purchase amount
[minimum_purchase_amount], minimum purchase quantity for promotion[buy_this_quantity], redemption restriction[redemption_restriction], custom redemption condition[custom_redemption_restriction]
Free gift item ID [free_gift_with_id]
- Required: Free gift item ID
[free_gift_item_id] - Optional: Minimum purchase amount
[minimum_purchase_amount], minimum purchase quantity for promotion[buy_this_quantity], redemption restriction[redemption_restriction], custom redemption condition[custom_redemption_restriction]
Free shipping standard [free_shipping_standard]
- Required: None
- Optional: Free shipping type
[free_shipping_type], minimum purchase amount[minimum_purchase_amount], minimum purchase quantity for promotion[buy_this_quantity], minimum purchase quantity for promotion[buy_this_quantity], redemption restriction[redemption_restriction], custom redemption condition[custom_redemption_restriction]
Free shipping overnight [free_shipping_overnight]
- Required: None
- Optional: Free shipping type
[free_shipping_type], minimum purchase amount[minimum_purchase_amount], minimum purchase quantity for promotion[buy_this_quantity], redemption restriction[redemption_restriction], custom redemption condition[custom_redemption_restriction]
Free shipping two day [free_shipping_two_day]
- Required: None
- Optional: Free shipping type
[free_shipping_type], minimum purchase amount[minimum_purchase_amount], minimum purchase quantity for promotion[buy_this_quantity], redemption restriction[redemption_restriction], custom redemption condition[custom_redemption_restriction]
Free shipping with shipping config [free_shipping_with_shipping_config]
- Required: None
- Optional: None
Cash back [cash_back]
- Required: Cash back amount
[cash_back_amount] - Optional: Minimum purchase amount
[minimum_purchase_amount], minimum purchase quantity for promotion[buy_this_quantity], redemption restriction[redemption_restriction], custom redemption condition[custom_redemption_restriction]
Percentage cash back [percentage_cash_back]
- Required: Cash back percentage
[cash_back_percentage] - Optional: Minimum purchase amount
[minimum_purchase_amount], minimum purchase quantity for promotion[buy_this_quantity], redemption restriction[redemption_restriction], custom redemption condition[custom_redemption_restriction]
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: Minimum purchase amount
[minimum_purchase_amount], minimum purchase quantity for promotion[buy_this_quantity], redemption restriction[redemption_restriction], custom redemption condition[custom_redemption_restriction]
Percent off range [percent_off_range]
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: Minimum purchase amount
[minimum_purchase_amount], minimum purchase quantity for promotion[buy_this_quantity], redemption restriction[redemption_restriction], custom redemption condition[custom_redemption_restriction]
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 1 get 1 free, up to 10 items" set maximum purchase quantity for promotion
[limit_quantity]to 10. - "10% off up to $100", set max discount amount limit
[max_discount_amount]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 USD |
This attribute communicates the maximum discount value of this promotion. This is used for |
Additional attributes
Display dates for promotion [promotion_display_dates]
Optional
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 July 19, 2009 to 9:00 p.m. on July 26, 2009 EST (Eastern Standard Time), you would submit:
2009-07-19T03:00:00-05:00/2009-07-26T21:00:00-05:00
If your promotion was valid from 3:00 a.m. on July 19, 2009 to 9:00 p.m. on July 26, 2009 GMT (Greenwich Mean Time), you would submit:
2009-07-19T03:00:00+00:00/2009-07-26T21:00:00+00:00
Important:
- GMT is Greenwich Mean Time. -5 hours represents EST while -8 hours represents PST.
- Promotions have a 6- month limit (183 days).
- Daylight Savings: -4 hours represents EDT while -7 hours represents PDT.
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 [promotion_display_date]
attribute is not specified, the promotion start date [promotion_effective_dates]
determines the date and time frame when the promotion will be live on Google.com and Shopping ads. This optional attribute is supported by the regular Promotions source only.
This attribute specifies the promotion description.
The description is not shown to customers
Generic redemption code [generic_redemption_code]
Optional
Syntax
- String
- Maximum length is 20 characters
Example
EXTRA20
This attribute specifies the code that customers can use online to redeem the promotion. It's required if the coupon code required [offer_type]
is set to generic code [generic_code]
.
Note: All shipping promotions must include a valid redemption code.
Free shipping promotions must include a valid coupon code that shoppers can manually apply. Otherwise, shipping 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 program policies for more information.
Fine print for promotion [fine_print]
Optional
Syntax
- String
- Maximum length is 500 characters.
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 [promotion_price]
Optional
Syntax
Must be a number and the currency.
Example
15.00 USD
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 out this 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 States.
[promotion_destination]
Supported value
-
[Free_listings]
[Free_listings]
must be set as the only promotion destination[coupon_value_type]
Supported values
-
money_off -
percent_off -
buy_m_get_n_money_off -
buy_m_get_n_percent_off -
buy_m_get_percent_off -
buy_m_get_money_off -
free_gift -
free_gift_with_value -
free_gift_with_item_id -
free_shipping_standard -
free_shipping_overnight -
free_shipping_two_day -
cash_back -
percentage_cash_back -
money_off_range -
percent_off_range
Event Applicability
[event_applicability]
Supported values
- Sitewide
[sitewide]
- Specific categories
[specific_categories]
Event applicability for this promotion.
If event applicability is set to sitewide
, it indicates this event applies site wide.
Event Applicability, which indicates event, cannot be set up together with Product Applicability
[product_applicability]
, which indicates product promotion. You can only choose one of them.
If you choose to set up an event, Event Applicability is a required field. Otherwise, Product Applicability
[product_applicability]
for product promotion is a required field.
[promotion_url]
Required for event
Syntax
- String
- Valid promotion landing page URL.
[google_product_category]
Optional
Set if “ event_applicability
” is “ specific_category”
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.
- To download this list in another language, you can select that language from the menu at the bottom of this page.
Repeated field
Yes. There can be up to 5 Google product category
Example
2271
or
Apparel & Accessories > Clothing > Dresses
