Promotion Types and Requirements

Promotions provide discounts to shoppers when they meet certain purchase requirements.

For the Shopper Products and Shopper Search APIs, promotion information includes both pricing and callout message information. However, the specific pricing and callout information that is fetched is determined by:

  • Promotion Type
  • Product Type
  • Product Purchase Requirements

Promotions are categorized into types:

  • Product: a discount on an individual product, or on a product with specific purchasing options (size, color, or style), for example:
    • 10% off shirts when you buy 2
    • Buy 3 ties for $10
    • $5 off a TV when purchasing a 1-year warranty
    • Get 10% off Sony PlayStation with source code wii100. (Source codes can be set in the Shopper context.)
  • Order: a discount on the total cost of the basket, for example:
    • $10 off for shoppers who are members of the gold membership customer group
  • Shipment: a discounted shipping cost, for example:
    • Free shipping on orders over $50 with coupon code “freeship”

A product, which is only applicable to product promotions, is classified as one of the following:

  • Qualifying Product

    • Product used to trigger a discount, for example:

      • In a “Buy 3 of product X, and get 10% off of up to 4 of product Y” promotion, the qualifying product is product X.

      • Important: Qualifying products can have variants, which are different purchasing options, such as size or color. The specific product buying option that is specified for the promotion is known as the master or primary product. Variant products might or might not be included in the promotion.

        • If the product is master, the response includes::
        • If the product is a variant, the response includes:

  • Discounted Product

    • Product that receives a monetary discount, for example:
      • In a “Buy 3 of product X, and get 10% off of up to 4 of product Y” promotion, the discounted product is product Y.

  • Bonus Product

    • A free product, for example:
      • In a “Buy 3 of product X, and get one product Y for free” promotion, the bonus product is product Y.

Promotions can, but are not required to, have specific product purchase requirements, such as purchasing a set quantity or a specific item:

  • Non-conditional:
    • No additional purchase criteria, such as discounts, free samples, or other offers, for example:
      • “$10 Off of product X”, "50% Off All Items," or "Free Gift with Purchase."
  • Conditional:
    • Customers must fulfill additional conditions to qualify for the offer, such as making a minimum purchase, signing up for a membership or loyalty program, or participating in a specific activity, for example:
      • "Spend $50 and Get 20% Off," "Buy 2, Get 1 Free," “Buy an 80” TV and Receive a Free Streaming Device”, or "Get a Discount Coupon for Your Next Purchase When You Sign Up for Our Newsletter."
    • Important: Conditional product purchase requirements only apply to product promotions, not order or shipment promotions.
  • Bonus:
    • Involves offering customers an additional item or service for free or at a discounted rate when they purchase a specified product or meet certain conditions. The bonus item is typically related to a primary product, serving as an incentive to encourage customers to make a purchase, for example:
      • "Buy a Laptop and Get a Free Mouse," "Purchase a Shampoo and Conditioner Set and Receive a Travel-sized Hair Serum for Free," or "Buy a Gaming Console and Get a Free Game."
    • Important: Bonus product purchase requirements only apply to product promotions, not order or shipment promotions.

Based on the promotion type, product type, and product purchase requirements, The content of the response includes the following information:

  • Pricing
  • Callout Message

Pricing information is only returned for qualifying products with non-conditional purchase requirements in product level promotions, for example: Buy product X and get $10 off or Buy product X and get 10% off. For other promotion types, product types, and product purchase requirements, pricing is impacted by shopper-driven actions, and cannot be calculated until the shopper makes additional purchasing decisions.

In addition:

  • Promotional pricing is only returned for variant products that are included in a promotion when the primary product is the qualifying product for the promotion.
  • The priceRange returned in the response per price book returns the min and max price across variants, for example: if an ipod-classic-silver costs $219 and an ipod-classic-black costs $200, the minprice is : 200 and max is 219.

Callout messages provide details about the qualifying, discounted, or bonus product, as applicable, and what the shopper must do to qualify for the promotion.

The callout message is returned in the productPromotions[].calloutMsg attribute of the response body.

For example, the following code includes a non-conditional purchase callout message for a $10 discount when purchasing a women's shirt:

The following example provides a conditional purchase callout message for a $50 discount when purchasing a man's suit that costs more than $400: