Skip to main content

Promotion Types

A promotion's PromotionType object describes the discount it gives and the conditions for applying it. Its Type field names the promotion type, and which other fields are populated depends on that type.

Each type has a bit in the proBits capability bitmask. For how each type is applied to a cart, see Applying promotions.

Naming​

Each type's name is made of two parts: the kind of promotion, then the kind of discount it gives. For example, CheapestMatchedForDollar is a CheapestMatchedFor promotion with a Dollar discount.

Promotion typeKind of promotionDiscount
CheapestMatchedForDollarCheapestMatchedForDollar
CheapestMatchedForDollarOffCheapestMatchedForDollarOff
CheapestMatchedForPercentOffCheapestMatchedForPercentOff
MatchThenCheapestOtherForDollarMatchThenCheapestOtherForDollar
MatchThenCheapestOtherForDollarOffMatchThenCheapestOtherForDollarOff
MatchThenCheapestOtherForPercentOffMatchThenCheapestOtherForPercentOff
BundleForTotalDollarDistributedBundleForTotalDollarDistributed
BundleForTotalDollarOffDistributedBundleForTotalDollarOffDistributed
BundleForPercentOffBundleForPercentOff
EachMatchedDollarOffEachMatchedDollarOff
EachMatchedPercentOffEachMatchedPercentOff

All percentages are decimals between 0.0 and 1.0: 0.3 means 30% off.

All fields​

Every field a PromotionType can have, and the promotion types that use it. Fields a promotion's type doesn't use are null. The sections below describe each type's fields.

NameTypeUsed by
TypestringAll
DollarValueOfCheapestdecimal?CheapestMatchedForDollar
PercentOffOfCheapestdecimal?CheapestMatchedForPercentOff
DollarOffOfCheapestdecimal?CheapestMatchedForDollarOff
DollarValueOfOtherdecimal?MatchThenCheapestOtherForDollar
DollarOffOfOtherdecimal?MatchThenCheapestOtherForDollarOff
PercentOffOfOtherdecimal?MatchThenCheapestOtherForPercentOff
DollarValueOfAlldecimal?BundleForTotalDollarDistributed
DollarOffOfAlldecimal?BundleForTotalDollarOffDistributed
PercentOffOfAlldecimal?BundleForPercentOff
DollarOffOfEachdecimal?EachMatchedDollarOff
PercentOffOfEachdecimal?EachMatchedPercentOff
ItemsToMatchProductCondition?CheapestMatchedFor, EachMatched
OtherItemConditionsProductCondition?MatchThenCheapestOtherFor
MatchConditionsProductCondition?MatchThenCheapestOtherFor
BundleItemsToMatchBundleMatch[]?BundleFor
NumberToMatchint32?CheapestMatchedFor, MatchThenCheapestOtherFor
GramsPerMatchUnitdecimal?All except EachMatchedPercentOff
MaxApplicationCountint32?CheapestMatchedFor, MatchThenCheapestOtherFor

BundleMatch​

One element of a BundleFor promotion's bundle.

NameTypeDescription
ProductConditionProductConditionThe condition tree that determines which products can be considered as this element of the bundle.
QuantityToMatchdecimalThe quantity of products matching ProductCondition required to make up this element of the bundle. GramsPerMatchUnit converts gram-based quantities into each-based ones.

CheapestMatchedFor​

Once enough products match ItemsToMatch, the cheapest of them gets the discount. See how to apply them.

CheapestMatchedForDollar​

NameTypeDescription
TypestringCheapestMatchedForDollar
DollarValueOfCheapestdecimalThe dollar amount to charge for the cheapest product applicable to this promotion.
ItemsToMatchProductConditionThe condition tree that determines which products apply to this promotion.
NumberToMatchint32The number of items that must pass the ItemsToMatch filter for this promotion to apply.
GramsPerMatchUnitdecimalThe number of grams that count as a single unit for NumberToMatch.
MaxApplicationCountint32?The maximum number of times this promotion can be applied to a single cart. Null means no limit.

CheapestMatchedForDollarOff​

NameTypeDescription
TypestringCheapestMatchedForDollarOff
DollarOffOfCheapestdecimalThe dollar amount to take off the cheapest product applicable to this promotion.
ItemsToMatchProductConditionThe condition tree that determines which products apply to this promotion.
NumberToMatchint32The number of items that must pass the ItemsToMatch filter for this promotion to apply.
GramsPerMatchUnitdecimalThe number of grams that count as a single unit for NumberToMatch.
MaxApplicationCountint32?The maximum number of times this promotion can be applied to a single cart. Null means no limit.

CheapestMatchedForPercentOff​

NameTypeDescription
TypestringCheapestMatchedForPercentOff
PercentOffOfCheapestdecimalThe percentage discount to apply to the cheapest product applicable to this promotion.
ItemsToMatchProductConditionThe condition tree that determines which products apply to this promotion.
NumberToMatchint32The number of items that must pass the ItemsToMatch filter for this promotion to apply.
GramsPerMatchUnitdecimalThe number of grams that count as a single unit for NumberToMatch.
MaxApplicationCountint32?The maximum number of times this promotion can be applied to a single cart. Null means no limit.

MatchThenCheapestOtherFor​

Once enough products match MatchConditions, the cheapest other product matching OtherItemConditions gets the discount. See how to apply them.

MatchThenCheapestOtherForDollar​

NameTypeDescription
TypestringMatchThenCheapestOtherForDollar
DollarValueOfOtherdecimalThe dollar amount to charge for the cheapest item passing the OtherItemConditions filter.
OtherItemConditionsProductConditionThe condition tree that determines which products can receive the discount.
MatchConditionsProductConditionThe condition tree that determines which products apply to this promotion.
NumberToMatchint32The number of items that must pass the MatchConditions filter for this promotion to apply.
GramsPerMatchUnitdecimalThe number of grams that count as a single unit for NumberToMatch.
MaxApplicationCountint32?The maximum number of times this promotion can be applied to a single cart. Null means no limit.

MatchThenCheapestOtherForDollarOff​

NameTypeDescription
TypestringMatchThenCheapestOtherForDollarOff
DollarOffOfOtherdecimalThe dollar amount to take off the cheapest item passing the OtherItemConditions filter.
OtherItemConditionsProductConditionThe condition tree that determines which products can receive the discount.
MatchConditionsProductConditionThe condition tree that determines which products apply to this promotion.
NumberToMatchint32The number of items that must pass the MatchConditions filter for this promotion to apply.
GramsPerMatchUnitdecimalThe number of grams that count as a single unit for NumberToMatch.
MaxApplicationCountint32?The maximum number of times this promotion can be applied to a single cart. Null means no limit.

MatchThenCheapestOtherForPercentOff​

NameTypeDescription
TypestringMatchThenCheapestOtherForPercentOff
PercentOffOfOtherdecimalThe percentage discount to apply to the cheapest item passing the OtherItemConditions filter.
OtherItemConditionsProductConditionThe condition tree that determines which products can receive the discount.
MatchConditionsProductConditionThe condition tree that determines which products apply to this promotion.
NumberToMatchint32The number of items that must pass the MatchConditions filter for this promotion to apply.
GramsPerMatchUnitdecimalThe number of grams that count as a single unit for NumberToMatch.
MaxApplicationCountint32?The maximum number of times this promotion can be applied to a single cart. Null means no limit.

BundleFor​

Once the cart has enough of each element in BundleItemsToMatch, every item in the bundle is discounted. See how to apply them.

BundleForTotalDollarDistributed​

NameTypeDescription
TypestringBundleForTotalDollarDistributed
DollarValueOfAlldecimalThe total dollar amount to charge for all the items in the bundle.
BundleItemsToMatchBundleMatch[]The elements of this bundle. An element can be more than a single quantity.
GramsPerMatchUnitdecimalThe number of grams that count as a single unit for QuantityToMatch.

BundleForTotalDollarOffDistributed​

NameTypeDescription
TypestringBundleForTotalDollarOffDistributed
DollarOffOfAlldecimalThe total dollar amount to take off all the items in the bundle.
BundleItemsToMatchBundleMatch[]The elements of this bundle. An element can be more than a single quantity.
GramsPerMatchUnitdecimalThe number of grams that count as a single unit for QuantityToMatch.

BundleForPercentOff​

NameTypeDescription
TypestringBundleForPercentOff
PercentOffOfAlldecimalThe percentage discount to apply to every item in the bundle.
BundleItemsToMatchBundleMatch[]The elements of this bundle. An element can be more than a single quantity.
GramsPerMatchUnitdecimalThe number of grams that count as a single unit for QuantityToMatch.

EachMatched​

Every product matching ItemsToMatch gets the discount, with no quantity requirement. See how to apply them.

EachMatchedDollarOff​

NameTypeDescription
TypestringEachMatchedDollarOff
DollarOffOfEachdecimalThe dollar amount to take off each item passing the ItemsToMatch filter.
ItemsToMatchProductConditionThe condition tree that determines which products receive the discount.
GramsPerMatchUnitdecimalThe number of grams that count as a single unit when applying the DollarOffOfEach discount.

EachMatchedPercentOff​

NameTypeDescription
TypestringEachMatchedPercentOff
PercentOffOfEachdecimalThe percentage discount to apply to every item passing the ItemsToMatch filter.
ItemsToMatchProductConditionThe condition tree that determines which products receive the discount.