Merchant Promotions feed specification

This article lists all of the attributes 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 display 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 you use for your online products feed. 

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

Required fields

Include the following attributes in your feed to display your promotions on Google.com and Shopping ads:

promotion_id

This attribute is the unique id of a promotion. For online promotions that apply to specific products, the promotion_id in your promotions feed must match this attribute in your products feed. The promotion_id tells Google which products belong to a specific promotion.
Important:
  • The promotion_id is case and space sensitive. If you're mapping a specific promotion to a set of products in your products feed, the promotion_id you provide must match in both feeds.
  • The promotion_id should not contain spaces or symbols (e.g. %, !, etc.).
  • To add multiple promotion_id values to an item, submit the values separated by commas in the promotion_id column in your products feed.
  • You can map up to 10 promotion_ids to one item in the products feed.
  • Maximum length of the promotion_id is 60 characters.

product_applicability

This attribute specifies if the promotion is applicable to all products or only specific products.
Valid values
  • ALL_PRODUCTS
  • SPECIFIC_PRODUCTS
Important:
  • If SPECIFIC_PRODUCTS applies, you must map a promotion_id to applicable products in your products feed for Google to recognize the eligible products. These specific products are continuously tested for the duration of the promotion. For more information about mapping, review how to create promotion groups for specific products.
  • If this promotion applies to ALL_PRODUCTS, you do not need to add a promotion_id in the products feed. The promotion validity is tested against all of the items in your products feed.

offer_type

This attribute indicates whether or not a coupon code is required for shoppers to redeem the offer.
Valid values
  • NO_CODE
  • GENERIC_CODE
If offer_type is GENERIC_CODE (e.g. a code that is the same across all shoppers), the attribute below is required:
  • Generic_redemption_code
  • Provide the text code that customers can use online (e.g. EXTRA20).
Note: All shipping promotions must include a valid redemption code.
  • Free shipping promotions must include a valid coupon code which the shoppers can manually apply. Otherwise, it will be considered as a service that is normally offered which must be reflected in the products feed. If the promotion is offered for a specific duration, then this must also be reflected in the products feed.
  • Learn more about how to include redemption codes for shipping promotions in the Merchant Promotions Program Policies.

long_title

This attribute specifies the full title of the promotion
Important:
  • Follow our Editorial requirements closely. The Editorial requirements outline title requirements and provides helpful examples of acceptable and unacceptable titles.
  • It should describe the promotion completely and accurately. Maximum length is 60 characters.

promotion_effective_dates

This attribute describes the date and time frame when the promotion is active and ready for validation review. The promotion live time may be delayed for a few hours due to the validation review.

Start date and end date are separated by a forward slash (/). The start date is specified by the format (YYYY-MM-DD), followed by the letter ‘T’, the time of the day when the sale starts (in Greenwich Mean Time, GMT), followed by an expression of the time zone for the sale. The end date should be in the same format.

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
If you use the Promotion tool, it will only support the promotion_effective_date attribute and the time will default to the time zone of your device. If you would like the promotion to be in a different time zone, adjust the redemption start and end times manually.

Example:
  • Your device is in PT and your promotion is starting at 9:00 AM ET. The redemption start time must be modified to be 6:00AM PT in the creation form.
Tip: Have your promotion validated earlier by using the promotions display_date attribute option. Learn more about Merchant Promotions feed formatting and attributes.

redemption_channel

This attribute indicates the promotion is valid online.
Valid value
  • ONLINE

Optional fields

promotion_display_dates

This attribute describes the date and time frame when the promotion is set to be live on Google.com and Shopping ads.

Start dates and end dates separated by a forward slash (/). The start date is specified by the format (YYYY-MM-DD), followed by the letter ‘T’, the time of the day when the sale starts (in Greenwich Mean Time, GMT), followed by an expression of the time zone for the sale. The end date should be in the same format.

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

Note: If the promotion_display_date attribute is not used, the promotion_effective_dates will be the date and time frame for when the promotion will be live on Google.com and Shopping ads. This optional attribute is supported by using the regular Promotions feed only.

minimum_purchase_amount

This attribute describes any minimum amount of purchase that must be made for this offer to be applicable. Promotions feeds only support currencies of the specified locales.

Example (US): 20 USD

Example (IN): 300 INR
Example (AU): 15 AUD

generic_redemption_code

This attribute describes the text code that customers can use online to redeem the promotion. It is required if your offer_type is GENERIC_CODE.

Example: EXTRA20

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, it will be considered as a service that is normally offered which must be reflected in the products feed. If the promotion is offered for a specific duration, then this must also be reflected in the products feed. Refer to a section in Merchant Promotions Program Policies for more detailed information.

Optional structured data fields

To display additional details about your promotion as part of your Shopping ads, add structured data attributes to your feed.

RETURN TO MERCHANT PROMOTIONS HOME

Was this article helpful?
How can we improve it?