Skip to main content

Conditions

Conditions decide when a promotion can be applied. There are four kinds, and all four must pass before a promotion applies:

  • Cart conditions, in the promotion's CartCondition: requirements the whole cart must meet, such as the type of customer.
  • Line conditions, in the promotion's LineCondition: requirements a line item must meet, such as not already having a sale price.
  • Product conditions, in the PromotionType's product fields (such as ItemsToMatch): which products the promotion applies to.
  • Package conditions, in a product condition tree's PackageCondition node: requirements the package selected for a line item must meet, such as how close it is to its expiry date.

Condition trees​

Each kind of condition is a tree of nodes. Every node has a Type field that says what kind of node it is and which other fields it has. A tree must evaluate to true for the promotion to apply.

Every kind of condition has the same four logical nodes for building trees:

Node (Type)FieldsEvaluates to true when
AllOfConditions: a list of nodes of the same kindEvery node in Conditions is true.
AnyOfConditions: a list of nodes of the same kindAt least one node in Conditions is true.
NoneOfConditions: a list of nodes of the same kindEvery node in Conditions is false.
NoneAlways. A no-op, which can be a node in a tree or a whole tree on its own.

Most other nodes have a bit in the condBits capability bitmask. Promotions with a node whose bit you don't supply aren't returned. The logical nodes and the CatalogId product condition have no bit, so every integration must implement them.

Product conditions​

A ProductCondition tree filters which products a promotion applies to. A line item is applicable to the promotion only if the entire tree evaluates to true for its product.

Node (Type)FieldsEvaluates to true when the line item's product
CatalogIdId (guid): a CatalogIdHas the given CatalogId.
ClassificationParentCategoryOrClassificationId (int32): a parent category or classification IDBelongs to the given parent category or classification.
NonStockIs a non-stock product.
BatchTrackedIs batch-tracked.
GiftCardIs a gift card.
RegularIs a regular product.
ContainsCannabisContains cannabis.
IsGramIs sold by the gram.
IsEachIs sold by the each.
SupplierSupplierId (int32): a supplier IDBelongs to the given supplier.
SpecificationValueStringId (string), FieldId (int32), Value (string)Has a specification value matching the StringId/FieldId, with a value matching Value (case-insensitive).
PackageConditionPackageCondition: a PackageCondition treeThe package selected for the product satisfies the given package condition tree

All fields​

Every field a ProductCondition node can have. Which are populated depends on its Type.

NameType
Typestring
ConditionsProductCondition[]?
ParentCategoryOrClassificationIdint32?
Idguid?
SupplierIdint32?
StringIdstring?
Valuestring?
FieldIdint32?
PackageConditionPackageCondition

Matching product data​

To check whether a product matches these conditions, you need its product data from Cova. This assumes you're already caching it from the Data Platform DetailedProductData endpoints. This table shows where each condition's data is in a DetailedProductData response.

NodeProperty in DetailedProductDataMatches when
CatalogIdProductIdEqual to Id. These conditions are always returned by the promotion endpoints.
ClassificationClassificationIdThe promotion's ParentCategoryOrClassificationId may be a category rather than a classification. Set IncludeClassifications: true on DetailedProductData requests and check the Classifications collection for the category structure.
NonStockIsNonStocktrue
BatchTrackedIsBatchTrackedtrue. Subject to state traceability; usually means "contains cannabis".
GiftCardProductSpecifications[]A field exists with a DisplayName of "Integrated Gift Card" and a value of true/yes. Set IncludeProductSpecifications: true on DetailedProductData requests.
RegularIsNonStockfalse
ContainsCannabisProductSpecifications[]A field exists with a DisplayName starting with "Retail Marijuana Product Type" and a value that isn't null or empty. Set IncludeProductSpecifications: true on DetailedProductData requests.
IsGramMeasurementTypeMass
IsEachMeasurementTypeSingleUnit
SupplierSupplierSkus[]An entry's SupplierId equals the condition's. Set IncludeProductSkusAndUpcs: true on DetailedProductData requests.
SpecificationValueProductSpecifications[]A specification's FieldId matches, and its value exactly matches Value. Set IncludeProductSpecifications: true on DetailedProductData requests.

Package conditions​

Package conditions control how promotions should apply to specific product packages. Package conditions form a condition tree stored within a PackageCondition node within a product tree.

note

For the AllOf and AnyOf nodes within a package condition tree, the children conditions are stored under the PackageConditions property.

Example
{
"Type": "AnyOf",
"PackageConditions": [
{
"Type": "PackageDate",
"Operator": "IsWithin",
"DateType": "ExpiryDate",
"Days": 12
}
]
}

Package date condition​

A package date condition is evaluated by comparing the current date to a specific date from the package being evaluated.

Package date conditions can be used to form conditions like:

  • When within 12 days of the package's expiry date
  • When more than 20 days past the package's harvest date

Package Date conditions have three properties that control how the condition is evaluated:

  • DateType - Which package date should be used for comparison
  • Operator - How the current date should be compared to the chosen package date
  • Days - The number of days to use for the date comparison

Package Date conditions have the following parameters:

ParameterTypeDescription
TypePackageDateIdentifies the package condition as a Package Date condition
DateTypeOne of:
  • ExpiryDate
  • UseByDate
  • PackagedDate
  • ProductionDate
  • HarvestDate
  • TestDate
The package date to compare against
OperatorOne of:
  • IsWithin
  • IsMoreThan
How to compare the current date to the chosen package date
DaysintegerMust be non-negative

Start & End Dates​

Each DateType is classified as either a Start Date, or an End Date.

Start Dates:

  • PackagedDate
  • ProductionDate
  • HarvestDate
  • TestDate

End Dates:

  • ExpiryDate
  • UseByDate

Evaluation​

The Package Date condition is evaluated in the following manner based on whether the DateType is a start or end type:

Date Type is Start / End dateOperatorCondition
Start DateIsWithin(current date) <= (package date) + (# of days)
Start DateIsMoreThan(current date) > (package date) + (# of days)
End DateIsWithin(current date) >= (package date) - (# of days)
End DateIsMoreThan(current date) < (package date) - (# of days)

Examples​

When within 10 days of the expiry date (an end date)
{
"Type": "PackageDate",
"DateType": "ExpiryDate",
"Operator": "IsWithin",
"Days": 10
}
Expiry DateCurrent DateEvaluates To
April 20, 2026April 12, 2026true
April 20, 2026April 25, 2026true
April 20, 2026April 5, 2026false
When within 10 days of the test date (a start date)
{
"Type": "PackageDate",
"DateType": "TestDate",
"Operator": "IsWithin",
"Days": 10
}
Test DateCurrent DateEvaluates To
April 10, 2026April 5, 2026true
April 10, 2026April 15, 2026true
April 10, 2026April 25, 2026false
When more than 10 days before the expiry date (an end date)
{
"Type": "PackageDate",
"DateType": "ExpiryDate",
"Operator": "IsMoreThan",
"Days": 10
}
Expiry DateCurrent DateEvaluates To
April 20, 2026April 15, 2026false
April 20, 2026April 25, 2026false
April 20, 2026April 5, 2026true
When more than 10 days after the test date (a start date)
{
"Type": "PackageDate",
"DateType": "TestDate",
"Operator": "IsMoreThan",
"Days": 10
}
Test DateCurrent DateEvaluates To
April 10, 2026April 5, 2026false
April 10, 2026April 15, 2026false
April 10, 2026April 25, 2026true

Cart conditions​

A CartCondition tree filters which carts a promotion can apply to. Some of its nodes need information about the customer or the sale that your integration may not have.

Node (Type)FieldsEvaluates to true when
MedCustomerThe customer is a medical customer.
RecCustomerThe customer isn't a medical customer.
CustomerInPricingGroupPricingGroupId (int32): a pricing group IDThe customer belongs to the given pricing group.
CustomerNotInPricingGroupThe customer doesn't belong to any pricing group, or there's no customer on the sale.
NoInvoiceLevelDiscountOnCartThe cart doesn't have an invoice-level discount applied.
NoLoyaltyDiscountOnCartThe cart doesn't have a loyalty discount applied.

Line conditions​

A LineCondition tree filters which line items a promotion can apply to. Some of its nodes need information about pricing that your integration may not have.

Node (Type)FieldsEvaluates to true when the line item
NoSalePricingIsn't using sale pricing.
NoTierPricingIsn't using tier pricing.
NoGroupPricingIsn't using group pricing.
NoManualLineDiscountDoesn't have a manually applied line discount.