Capability Bitmasks
The Promotions by capabilities endpoint takes two bitmasks that describe what your integration has implemented:
proBits(PromotionTypeCapabilities): the promotion types you can apply.condBits(ConditionCapabilities): the cart, line and product conditions you can evaluate.
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
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.
| Condition | Kind | Bit |
|---|---|---|
MedCustomer | Cart | 1 |
RecCustomer | Cart | 2 |
CustomerInPricingGroup | Cart | 4 |
NoSalePricing | Line | 8 |
Classification | Product | 16 |
NonStock | Product | 32 |
BatchTracked | Product | 64 |
GiftCard | Product | 128 |
Regular | Product | 256 |
ContainsCannabis | Product | 512 |
IsGram | Product | 1024 |
IsEach | Product | 2048 |
Supplier | Product | 4096 |
CustomerNotInPricingGroup | Cart | 8192 |
SpecificationValue | Product | 16384 |
NoTierPricing | Line | 32768 |
NoGroupPricing | Line | 65536 |
NoManualLineDiscount | Line | 131072 |
NoInvoiceLevelDiscountOnCart | Cart | 262144 |
NoLoyaltyDiscountOnCart | Cart | 524288 |
PackageDate | Product | 1048576 |
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
EachMatchedPercentOffpromotion type, soproBitsis 1024. - Product selection (the
CatalogIdcondition) has no bit and is always included, whatevercondBitsyou 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, soproBitsis still 1024. condBitsnow needsClassification(16) andSupplier(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.