This page describes the types used to annotate promotional email and their associated properties. These types and properties are included in a promotional email's header as JSON-LD.

See the Preview tool to see an example of the required structure. For more details, see the Email Markup Gettting Started guide.


The Organization type lets you specify a logo to include in the promotion.

Name Type Description
logo ImageObject or URL The associated logo. See best practices for Logo URL.


The DiscountOffer type lets you specify the value of deal as part of the promotion. You can include a discount code and specify dates for which the discount is valid.

Name Type Description
description Text The text on deal badge. See best practices for Deal Badge.
discountCode Text The discount code of the offer. See best practices for Discount Code.
availabilityStarts DateTime The offer is valid from this date and time.
availabilityEnds DateTime The offer is valid up until this date and time. See best practices for Expiration Date.


The PromotionCard type supports two different layouts:

  • Layout with a single image.
  • Layout with several images organized in a list of catalog cards.

PromotionCard with the single image

Name Type Description
promotionCardLayout PromotionCardLayoutType Layout type, should be SingleImageLayout.
image ImageObject or URL Single image preview of the email. See best practices for Single image preview.

PromotionCard with multiple images organized in catalog cards *

Name Type Description
promotionCardLayout PromotionCardLayoutType Layout type, should be CatalogCardLayout.
image ImageObject or URL Image to display on a catalog card. See best practices for Catalog card image preview.
headline Text Title of the catalog card.
potentialAction ViewAction This attribute should contain an URL of the landing page for the catalog card.
price Number or Text Price to show on the catalog card **.
priceCurrency Text The currency (in 3-letter ISO 4217 format) of the price.
discountValue Number or Text Discount amount that should be applied to the price. Discount price is calculated by using the next formula: Discount price = price - discountValue.
promotedItemDate DateTime Date to show on the catalog card **.
position Number Position of the card in the list of promotion cards. Cards will be displayed in increasing order, starting with 0.

* Email annotation can have up to six promotion cards.
** A catalog card can display either price or promotedItemDate at the same time.


The EmailMessage type lets you include alternative annotations for the email.

Name Type Description
subjectLine Text An alternative subject line shown when deal badge or discount code is also displayed. See best practices for Subject Line.