This article lists all of the attributes you can provide in your promotions feed.
To use promotions, you can submit your product data to Google through a feed. The information within your feed is then distributed on relevant Shopping ads as well as free product listings appearing on the Shopping tab in the US (may also appear outside of the US as well). Promotions will display for customers on desktop and mobile devices in Australia, France, Germany, India, the UK, Canada, and the US.
Free listings destination is only available in the US.Submit a promotions feed
File type: You can use either an XML file, tab-delimited file, or Google Spreadsheet. See a sample feed template
Registering and uploading a new feed: Follow the steps to register and upload a new promotions feed. Upload your promotions feed to the same Merchant Center account you use for your online products feed.
Create promotions to target specific products
You can create promotions for specific products in the following ways:
- Apply product filter attributes in your promotion feed: If a promotion applies to specific products in your product feed, you may use product filter attributes. See Product filters.
- Map the
promotion_idto products in your product feed: For Google to recognize the products included in your promotion, map apromotion_idto the eligible products in your products feed. For more information about mapping, see how to create promotion groups for specific products.
If you set product filters on the promotion feeds and explicit promotion_ids in the product feed, 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 feed to define how your promotions will display:
| Attribute | Format | Minimum requirements at a glance |
|---|---|---|
promotion_id |
Required Syntax
|
|
product_applicability |
Required Supported values
|
If the value is |
offer_type |
Required Supported values
If
|
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.
Learn more about how to include redemption codes for shipping promotions in the promotions program policies. |
long_title |
Required 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_effective_dates |
Required Syntax
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:
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:
|
Important:
If you use the promotion builder, it will only support the Tip: You can validate your promotion before it starts by using the |
redemption_channel |
Required Supported values
* |
This attribute indicates the promotion is valid online. |
promotion_destination |
Required
Supported values
Add a supported value to your feed. 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, see About attributes with repeated fields. Note: The The |
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: Buy_on_Google_listings, Free_listings, Free_local_listings.Product filters
If you create a promotion that only applies to specific products in your product feed, use the product filter in your promotion feed. The product filter attributes only apply when product_applicability 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 feed that have brand =“example1” and product_type = “Tshirt”.
Alternatively, you can also link a product to a specific promotion by setting the promotion_id in the product feed.
| Attribute | Format | Description |
|---|---|---|
item_id |
Syntax
|
The promotion only applies to products that match the |
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_id_exclusion |
Syntax
|
Products with one of these item ids are excluded from the promotion. |
product_type_exclusion |
Syntax
Example
|
Products with one of these product types are excluded from the promotion. |
brand_exclusion |
Syntax
Example
|
Products with one of these brands are excluded from the promotion. |
item_group_id_exclusion |
Syntax
|
Products with one of these item_group_id_exclusion are excluded from the promotion. |
Promotion details
The following sections describe the different attributes 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 user to redeem the promotion
- Promotion categories determine the type of promotion
- Limits determine 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 user to receive a promotion)
Preconditions
This attribute communicates the precondition (a minimum purchase amount) that a user 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_amountto 50 USD.
A “Free tote bag with $100 purchase” promotion, set theminimum_purchase_amountto 100 USD.
| Attribute | Format | Description |
|---|---|---|
minimum_purchase_amount |
Optional Syntax Promotions feeds only support currencies of the specified locales. Example
|
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 user will receive promotion Y. |
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. You can further restrict a promotion category with limits. See Limits.
| Attribute | Format | Description |
|---|---|---|
percent_off |
Optional Syntax Must be an integer Example
|
This attribute specifies the percentage discount offered in the promotion. For example, 10% off. |
money_off_amount |
Optional Syntax Must be a number and the currency Example
|
This attribute specifies the discount amount. For example, $20.00 off. |
get_this_quantity_discounted |
Optional Syntax Must be an integer Example
|
This attribute specifies the number of items to which the promotion or discount applies For example, set this attribute to 1 for a “Buy 2, get 1 free” (100% off) promotion. |
free_shipping |
Optional Supported values
|
This attribute specifies the type of free shipping offered in the promotion. |
free_gift_value |
Optional Syntax Must be a number and specify currency Example
|
This attribute specifies the monetary value of the free gift offered in the promotion. |
free_gift_description |
Optional Syntax String should not exceed 100 characters Example
|
This attribute is the description (but not the value) of any free gift offered in the promotion. Use the |
free_gift_item_id |
Optional Syntax
|
This attribute specifies free gift if it is an item in your product feed. The The |
Limits
These attributes communicate the limits that a user needs to meet to redeem a promotion. Limits do not 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 limit_quantity to 10.
"10% off, up to order value $100", set limit_value to $100.
| Attribute | Format | Description |
|---|---|---|
limit_quantity |
Optional Syntax Must be an integer Example
|
This attribute is used to communicate the maximum number of items that can be bought using this promotion. |
limit_value |
Optional Syntax Must be a number and specify currency. Example
|
This attribute communicates the maximum item value allowed for this promotion. |
Additional attributes
| Attribute | Format | Description |
|---|---|---|
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:
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:
|
Important:
This attribute specifies the date and time frame when the promotion will be live on Google.com and Shopping ads. If the |
description |
Optional Syntax
|
This attribute specifies the promotion description. The description is not shown to users |
generic_redemption_code |
Optional Syntax
Example
|
This attribute specifies the code that users can use online to redeem the promotion. It is required if 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 feed. If the promotion is offered for a specific duration, then the duration must also be reflected in the product feed. See promotions program policies for more information. |
image_link |
Optional Syntax
|
This attribute is a link to an image that features the promotion or the promotional item. |
fine_print |
Optional 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 user along with |
promotion_price |
Optional Syntax Must be a number and the currency. Example
|
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 users who enter a promotion code or meet the promotional requirements. |
|
|
Optional Supported values:
|
This attribute signals the type of promotion you’re running, allowing Google to perform a more automated review process, which can expedite promotion approval. When you use the optional For example, A list of required and optional attributes to be included in your promotions feed, depending on the |
Attributes to use with coupon_value_type in your promotions feed
coupon_value_type values shows the required and optional feed attributes for each.no structured data
- Required: None
-
Optional:
minimum_purchase_amount,buy_this_quantity,limit_quantity,limit_value,promotion_price,money_off_amount,percent_off,get_this_quantity_discounted,free_gift_value,free_gift_item_id,free_gift_description
money off
- Required:
money_off_amount - Optional:
minimum_purchase_amount
percent off
- Required:
percent_off - Optional:
minimum_purchase_amount
buy m get n money off
- Required:
money_off_amount,buy_this_quantity,get_this_quantity_discounted - Optional: None
buy m get n percent off
- Required:
percent_off,buy_this_quantity,get_this_quantity_discounted - Optional: None
buy m get money off
- Required:
money_off_amount,buy_this_quantity - Optional: None
buy m get percent off
- Required:
percent_off,buy_this_quantity - Optional: None
free gift
- Required:
free_gift_description - Optional:
minimum_purchase_amount,buy_this_quantity
free gift with value
- Required:
free_gift_value - Optional:
minimum_purchase_amount,buy_this_quantity
free gift with item id
- Required:
free_gift_item_id - Optional:
minimum_purchase_amount,buy_this_quantity
free shipping standard
- Required: None
- Optional:
free_shipping_type,minimum_purchase_amount,buy_this_quantity
free shipping overnight
- Required: None
- Optional:
free_shipping_type,minimum_purchase_amount,buy_this_quantity
free shipping two day
- Required: None
- Optional:
free_shipping_type,minimum_purchase_amount,buy_this_quantity
free shipping with shipping config
- Required: None
- Optional: None
To express interest in promotions, please fill out this form.