Merchant Promotions feed specification

This article lists all of the attributes that you can provide in your Promotions feed.

To use Merchant Promotions, you must submit your product data to Google through a feed. Your feed is then distributed on relevant ads on Shopping ads. Merchant Promotions will be displayed for shoppers on desktop and mobile devices in Australia, France, Germany, India, the UK and the US. 

Submit a Promotions feed

File type: You can use either an XML file, tab-delimited file or Google Spreadsheet.


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 that you use for your online products feed. 

Google reviews all promotions against Google Merchant Promotions Programme policies and Editorial requirements before displaying them. 

Create promotions to target specific products

You can create promotions for specific products in your product feed 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_id [promotion_id] to your products: For Google to recognise the products included in your promotion, map a promotion_id to 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 [promotion_ids] in the product feed, then the promotion applies to products selected by both techniques.

Basic promotions data

Include the following attributes in your feed to define how your promotions will be displayed on Google.com and Shopping ads:

Attribute Format Minimum requirements at a glance
promotion_id [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] is used to link promotions to specific products.
product_applicability [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 feed. These specific products are continuously tested for the duration of the promotion.
  • If the value is ALL_PRODUCTS [ALL_PRODUCTS], you do not need to use product filter attributes or a promotion_id [promotion_id] in the products feed. The promotion validity is tested against all of the items in your products feed.
offer_type [offer_type]

Required

Supported values

  • NO_CODE [NO_CODE]
  • GENERIC_CODE [GENERIC_CODE]

If offer_type [offer_type] is GENERIC_CODE [GENERIC_CODE] (that is, a code that is 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 delivery promotions must include a valid redemption code.

  • Free delivery promotions must include a valid coupon code that customers can manually apply. Otherwise, delivery will be treated as a service that is normally offered.

Learn more about how to include redemption codes for delivery promotions in the Merchant Promotions Programme policies.

long_title [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 [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 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:

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 19 July 2009 to 9.00 p.m. on 26 July 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 six-month limit (183 days).
  • Daylight Savings: -4 hours represents EDT while -7 hours represents PDT.

If you use the Promotion tool, it will only support the promotion_effective_date [promotion_effective_date] 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 promotions display_date [display_date] attribute option. Learn more about Merchant Promotions feed formatting and attributes.

redemption_channel [redemption_channel]

Required

Supported values

  • ONLINE [ONLINE]
This attribute indicates that the promotion is valid online.
promotion_destination [promotion_destination] Required

Supported values

  • SHOPPING_ADS [SHOPPING_ADS]
  • SHOPPING_ACTIONS [SHOPPING_ACTIONS]

Add a supported value to your feed. To submit your promotion to both destinations, separate each value as a separately submitted column:

  • promotion_destination [promotion_destination]: shopping_ads [shopping_ads]
  • promotion_destination [promotion_destination]: shopping_actions [shopping_ads]

Important:

These are repeated fields, and both values simultaneously are supported. Values indicated in this field will overwrite any product defaults.

For more details on repeated fields, see About attributes with repeated fields

Note:

SHOPPING_ACTIONS [SHOPPING_ACTIONS] is only applicable to advertisers enrolled in Shopping Actions.

Product filter

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 [product_applicability] is set to SPECIFIC_PRODUCTS​ [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 one 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 [brand] = "example1" and product_type [product_type] = "Tshirt", the promotion will apply only to those products in the product feed that have brand [brand] = "example1" and product_type [product_type] = "Tshirt".

Alternatively, you can also link a product to a specific promotion by setting the promotion_id [promotion_id] in the product feed.

Attribute Format Description
item_id [item_id]

Syntax

  • String
  • Maximum length is 50 characters

The promotion only applies to products that match the item_id [item_id] specified in this attribute. Note: The item_id [item_id] attribute matches the id [id] attribute in the products feed spec.

product_type [product_type]

Syntax

  • Unicode characters. Recommended: ASCII only.
  • Maximum length is 750 characters
  • Case sensitive. Must match the product feed 
The promotion only applies to products that match the product type specified in this attribute.
brand [brand]

Syntax

  • Unicode characters. Recommended: ASCII only.
  • Maximum length is 70 characters.
  • Case sensitive. Must match the product feed 

The promotion only applies to products that match the brand specified in this attribute.

item_​​group_​​id [item_group_id]

Syntax

  • String
  • Maximum length is 50 characters
  • Case sensitive. Must match the product feed 

     

This promotion applies to products that match the item_group [item_group] in this attribute.

item_id_exclusion [item_id_exclusion]

Syntax

  • String
  • One or more item IDs
  • Maximum length is 50 characters
  • Case sensitive. Must match the product feed 
Products with one of these item ids are excluded from the promotion.
product_type_exclusion [product_type_exclusion]

Syntax

  • Unicode characters. Recommended: ASCII only
  • Maximum length is 70 characters
  • Case sensitive. Must match the product feed 

    Example

    Rings
     

Products with one of these product types are excluded from the promotion.
brand_exclusion

Syntax

  • String
  • Maximum length is 50 characters
  • Case sensitive. Must match the product feed 

Example

Acme Products

Products with one of these brands are excluded from the promotion.
item_group_id_exclusion Syntax
  • String
  • Maximum length is 50 characters
  • Case sensitive. Must match the product feed 
Products with one of these item_group_id_exclusion [item_group_id_exclusion] 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 user 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 user to receive a promotion).

Preconditions

These attributes communicate the preconditions that a user needs to meet to redeem a promotion. Preconditions do not filter the products that are eligible for a promotion. To filter, use Product filters.

For example, if you want to create:

  • A 'Buy two, get one free' promotion for jeans, set the minimum_purchase_quantity [minimum_purchase_quantity] to 2.
  • A '£10 off on 3 or more jeans' promotion for jeans, set the minimum_purchase_quantity to 3.
Note: minimum_purchase_quantity [minimum_purchase_quantity] and minimum_purchase_amount [minimum_purchase_amount] cannot exist on the same promotion.
Attribute Format Description
minimum_purchase_quantity [minimum_purchase_quantity]

Optional

Syntax

The minimum_purchase_quantity [minimum_purchase_quantity] must be an integer.

Example

2

This attribute sets the minimum purchase quantity required for the promotion to be redeemed.

This attribute can be used in combination with the percent_off [percent_off], get_this_quantity_discounted [get_this_quantity_discounted] or money_off_amount [money_off_amount] attributes.

For example, for X number of purchases of the same product or a combination of products, the user will receive promotion Y. 

For example, set this attribute to 2 for a 'Buy two, get 20% off' promotion. 

minimum_purchase_amount [minimum_purchase_amount]

Optional

Syntax

Promotions feeds 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 user will receive promotion Y. 

membership_type [membership_type]

Optional

Supported values

  • FREE_MEMBERSHIP_REQUIRED [FREE_MEMBERSHIP_REQUIRED]
  • PAID_MEMBERSHIP_REQUIRED [PAID_MEMBERSHIP_REQUIRED]
  • STORE_CREDIT_CARD_REQUIRED [SHOP_CREDIT_CARD_REQUIRED]

Set this attribute for promotions that require a membership or shop credit card.

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' promotion. See Add structured data attributes

You can only associate one promotion category with a promotion_id [promotion_id]. You can further restrict a promotion category with limits. See Limits.

Attribute Format Description
percent_off [percent_off]

Optional

Syntax

Must be an integer

Example

10

This attribute specifies the percentage discount offered in the promotion.

For example, 10% off.

money_off_amount [money_off_amount]

Optional

Syntax

Must be a number and the currency

Example

20.00 GBP

This attribute specifies the discount amount.

For example, £20.00 off.

get_this_quantity_discounted

Optional

Syntax

Must be an integer

Example

2

This attribute specifies the number of items to which the promotion or discount applies

For example, set this attribute to 1 for a 'Buy two, get one free' (100% off) promotion. 

free_shipping [free_delivery]

Optional

Supported values

  • FREE_SHIPPING_STANDARD [FREE_DELIVERY_STANDARD]
  • FREE_SHIPPING_OVERNIGHT [FREE_DELIVERY_OVERNIGHT]
  • FREE_SHIPPING_TWO_DAY [FREE_DELIVERY_TWO_DAY]
This attribute specifies the type of free delivery offered in the promotion.
free_gift_value [free_gift_value]

Optional

Syntax

Must be a number and specify currency

Example

40.00 GBP

This attribute specifies the monetary value of the free gift offered in the promotion. 
free_gift_description [free_gift_description]

Optional

Syntax

String should not exceed 100 characters

Example

Free tote bag with £100 purchase.

This attribute is the description (but not the value) of any free gift offered in the promotion. 

Use the free_gift_item_id [free_gift_item_id] attribute instead when the product is in your product feed.

free_gift_item_id [free_gift_item_id]

Optional

Syntax

Unicode characters. Recommended: ASCII only 

Maximum length is 50 characters

This attribute specifies the free gift if it is an item in your product feed.

The item_id [item_id] specified in this attribute is the product that the user will receive as free gift.

The item_id [item_id] should map to the ID from your product feed.

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:

For 'Buy one, get one free, up to 10 items', set limit_quantity [limit_quantity] to 10.

For '10% off, up to order value £100', set limit_value [limit_value] to £100.
 

Attribute Format Description
limit_quantity [limit_quantity]

Optional

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. 

limit_value [limit_value]

Optional

Syntax

Must be a number and specify currency.

Example

50.00 GBP

This attribute communicates the maximum item value allowed for this promotion.

Additional attributes

Attribute Format Description
promotion_display_dates [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 19 July 2009 to 9.00 p.m. on 26 July 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 19 July 2009 to 9.00 p.m. on 26 July 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 six-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 promotion_display_date [promotion_display_date] attribute is not specified, the promotion_effective_dates [promotion_effective_dates] determine 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 feed only.

description [description]

Optional

Syntax

String

Maximum length is 2500 characters

This attribute specifies the promotion description.

The description is not shown to users

generic_redemption_code [generic_redemption_code]

Optional

Syntax

String

Maximum length is 20 characters

Example

EXTRA20

This attribute specifies the code that users can use online to redeem the promotion. It is required if offer_type [offer_type] is GENERIC_CODE.

Note: All delivery promotions must include a valid redemption code.

Free delivery promotions must include a valid coupon code that customers can manually apply. Otherwise, delivery 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 Merchant Promotions Programme policies for more information.

image_link [image_link]

Optional

Syntax

  • The image_link [image_link] must be a URL.
  • The linked image must be at least 200 x 200 pixels.
  • There is no required aspect ratio
     

This attribute is a link to an image that features the promotion or the promotional item.

fine_print [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 user along with generic_redemption_code [generic_redemption_code].

promotion_price [promotion_price]

Optional

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 users who enter a promotion code or meet the promotional requirements.

 
To express interest in the Merchant Promotions feature, please fill in this form.
Was this helpful?
How can we improve it?