Giving customers the opportunity to buy items at discounted prices is a great way to drive sales. You can determine whether or not an item has an associated promotion by including the PromotionDetails or PromotionSummary response group in your request. The PromotionSummary response group returns most if not all of the information you need to display promotional information on a web site, as shown in the following figure.
The PromotionDetails response group offers additional information.
Promotions are only available with items that have offers. Items that do not have offers are, for example, Collections and Variation parent ASINs. For that reason, when you use either of the promotion response groups, you must also use, in the same request, a response group that returns an offer, including:
Large
OfferFull
Offers
You can use the following operations to get promotion information are those that can return offers:
ItemLookup
ItemSearch
ListLookup
SimilarityLookup
ECS operations do not enable you to create promotions for items. The promotional response groups only enable you to return promotional information.
There are many different kinds of promotions associated with items for sale. ECS fully supports the following promotion categories:
FreeShipping--The item is shipped free of charge.
BuyQuantityXGetAmounOffX--If you buy at least the specified number of items, the cost of the next item is discounted. For example, if a customer buys three shirts, the fourth shirt is half off.
ForEachQuantityXGetAmountOffX--Each item is discounted by the specified amount. For example, all shirts are 30% off.
Other promotion categories return only partial information about a promotion.
These promotional categories are returned by two response elements, depending on the response group:
Category, in PromotionSummary responses
PromotionCategory, in PromotionDetails responses
Items returned by one of the promotions response groups are related to the promotion in one of the following ways:
Benefit-- The item is part of the promotional reward. For example, in a buy one camera and get a camera case free promotion, the camera case is the benefit item.
Eligible -- The item is what the customer must purchase to qualify for the promotion. For example, in a buy one camera and get a camera case free promotion, the camera is the eligible item
Both -- It is possible for an item to be both the benefit and eligible item. For example, in a buy two shirts get the third shirt half off promotion, the shirt is both the benefit and the eligible item.
The promotions response groups specify whether an item is the benefit or eligible item by using the elements IsInBefefitSet and IsInEligibilitySet.
<IsInBenefitSet>true</IsInBenefitSet> <IsInEligibilityRequirementSet>true</IsInEligibilityRequirementSet>
The value type for both of these elements is boolean. When "true," the item is part of that set. For example, if IsInBenefitSet is "true," the item is one of the benefits of the promotion.
If IsInBenefitSet is "true," the response also contains the element "BenefitDescription," which describes the benefit item, for example:
<BenefitDescription>Save $25.00 when you spend $125.00 or more on Kitchen & Housewares or Bed & Bath products offered by Amazon.com. Enter code AUGSAVER at checkout.</BenefitDescription>
If IsInEligibilitySet is "true," the response will contain the element, "EligibilityDescription," which describes the eligible item.
The promotion response groups provide a wealth of information about specific items. It is almost always a good idea to include one or both of the promotion response groups in requests that also ask for offers. Among all of the response elements returned by PromotionSummary, the following are typically used in the display of promotion information:
BenefitDescription--Describes the benefit, which is the item(s) that the customer receives as a result of the promotion. This element will not be present if the item is not part of the promotional benefits.
EligibilityDescription--Describes the items the customer must purchase to qualify for the promotion. This element will not be present if the item does not qualify the customer to receive the promotional benefit.
TermsAndConditions--Specifies the terms and conditions of the promotion.
The following response snippet shows the values for these elements.
<BenefitDescription>Save $25.00 when you spend $125.00 or more on Kitchen & Housewares or Bed & Bath products offered by Amazon.com. Enter code AUGSAVER at checkout.</BenefitDescription> <TermsAndConditions><STRONG>To receive the Best Value discount:</STRONG> <OL> <LI>Add $125 of qualifying Kitchen & Housewares or Bed & Bath products to your Shopping Cart via the <STRONG>Add to Shopping Cart</STRONG> button on each respective product information page. … </TermsAndConditions>
For the developer, the following additional fields, from PromotionDetails, are also helpful:
ComponentType--Specifies what the promotion applies to, for example, Shipping, ItemPrice, Subtotal.
CouponCombinationType--Specifies the kinds of promotional coupons that can be combined, for example, Unrestricted, Preferential, and Exclusive, where:
Unrestricted--Can be used with any other promotions
Preferential--Can be used with some other promotions
Exclusive--Cannot be used with any other promotions
FormattedPrice--The price formatted for display.
IsInBenefitSet--A boolean value. When True, the associated ASIN is what the customer receives as part of the promotion.
IsInEligibilityRequirementSet--A boolean value. When True, the associated ASIN is what the customer must purchase to qualify for the promotion.
The following response snippet shows the values for these elements.
<ComponentType>ItemPrice</ComponentType> <CouponCombinationType>Unrestricted</CouponCombinationType> <IsInBenefitSet>true</IsInBenefitSet> <IsInEligibilityRequirementSet>true</IsInEligibilityRequirementSet>
These values show that the promotion is based on discounting the price of the item ("ItemPrice"), that the promotion can be combined with any others ("Unrestricted"), and that the item is both what needs to be bought and what is awarded ("True").
To see full responses, refer to the respective response groups: Promotion Details or Promotion Summary.