Skip to main content

Capability Bitmasks

The Promotions by capabilities endpoint takes two bitmasks that describe what your integration has implemented:

The API only returns promotions your integration can fully handle. A promotion is left out if its type isn't in proBits, or if any node in its condition trees needs a bit that isn't set in condBits. Some promotion types and conditions need information about products, customers or pricing that your integration may not have, so the bitmasks let you filter out promotions you can't support.

To build a bitmask, add together the bits of everything you support.

Promotion type bits​

Promotion typeBit
CheapestMatchedForDollar1
CheapestMatchedForPercentOff2
CheapestMatchedForDollarOff4
MatchThenCheapestOtherForDollar8
MatchThenCheapestOtherForDollarOff16
MatchThenCheapestOtherForPercentOff32
BundleForTotalDollarDistributed64
BundleForTotalDollarOffDistributed128
BundleForPercentOff256
EachMatchedDollarOff512
EachMatchedPercentOff1024

Condition bits​

One bitmask covers all three kinds of condition: cart, line and product. Their bits don't overlap.

Some nodes have no bit: every integration must implement them. These are the logical nodes (AllOf, AnyOf, NoneOf and None) of all three kinds, and the product condition CatalogId.

ConditionKindBit
MedCustomerCart1
RecCustomerCart2
CustomerInPricingGroupCart4
NoSalePricingLine8
ClassificationProduct16
NonStockProduct32
BatchTrackedProduct64
GiftCardProduct128
RegularProduct256
ContainsCannabisProduct512
IsGramProduct1024
IsEachProduct2048
SupplierProduct4096
CustomerNotInPricingGroupCart8192
SpecificationValueProduct16384
NoTierPricingLine32768
NoGroupPricingLine65536
NoManualLineDiscountLine131072
NoInvoiceLevelDiscountOnCartCart262144
NoLoyaltyDiscountOnCartCart524288
PackageDateProduct1048576

Examples​

Percent off hand-picked products​

A retailer wants to give 20% off a selection of products they picked by hand while building the promotion.

  • That's the EachMatchedPercentOff promotion type, so proBits is 1024.
  • Product selection (the CatalogId condition) has no bit and is always included, whatever condBits you supply. Assuming your integration can only process a list of products, the final URL is:
~/ConditionCapabilities/1/PromotionTypeCapabilities/1024/Promotions

This returns only EachMatchedPercentOff promotions whose conditions are lists of products.

Percent off a classification from one supplier​

Now the retailer wants to give 20% off everything they've classified as "Pre-roll" that comes from the supplier "Hi-Roller".

  • It's still EachMatchedPercentOff, so proBits is still 1024.
  • condBits now needs Classification (16) and Supplier (4096): 16 + 4096 = 4112.
~/ConditionCapabilities/4112/PromotionTypeCapabilities/1024/Promotions

This returns only EachMatchedPercentOff promotions whose conditions use lists of products, classifications, suppliers, or any combination of them. Part of a returned promotion might look like this:

"PromotionType": {
"Type": "EachMatchedPercentOff",
"PercentOffOfEach": 0.2,
"ItemsToMatch": {
"Type": "AllOf",
"Conditions": [
{
"Type": "AnyOf",
"Conditions": [
{
"Type": "Classification",
"ParentCategoryOrClassificationId": 12345 // Pre-roll
}
]
},
{
"Type": "AnyOf",
"Conditions": [
{
"Type": "Supplier",
"SupplierId": 54321 // Hi-Roller
}
]
}
]
}
}

Promotions rely on many data points from the Cova product catalog. If you don't capture a value such as SupplierId, you can't evaluate promotions with Supplier conditions, so leave its bit out. See Matching product data for where each value comes from.