Rules API Reference

Full reference for the rule object and its fields. Use the Examples article to see complete JSON payloads for common scenarios.

Type

The first step in creating a rule is to choose the correct type. The table below lists all possible types with example scenarios.

Rule applies to	Action	Rule Type	Description
product	disable	disableProduct	Used to control time-based offers, such as a lunch offer only available between 11:00–14:00. Can also limit pickup options, e.g. disabling curbside orders after 18:00.
product	enable	enableProduct	Used to enable normally disabled products.
product	upsell	upsellProduct	Used to trigger the upsell screen based on a list of products.
product	stockout	stockoutProduct	Used when stores can no longer produce a certain product.
category	disable	disableCategory	Used to disable a whole category, e.g. breakfast might only be served at certain stores and disabled for the rest.
category	enable	enableCategory	Used to enable normally disabled categories.
category	upsell	upsellCategory	Used to trigger the upsell screen when a product from one of the listed categories is added to the basket.
product/category	upsell	upsellReplacementOffer	Used to perform plus-menu upsells and to offer replacement products when the chosen product is no longer available. See Replacement offer below.
store	disable	disableStore	Used to close a store that has problems, or to close all or specific stores over a holiday.
store	enable	enableStore	Used to enable a store once it has been fully configured.

For stockout-specific operational requirements, see Stockout.

Fields

comment

Write a short explanation of what the rule is supposed to do, for example:

"activate breakfast category at 07:00 for all stores, during the weekend"

A good comment provides context that is useful long after the rule was created. In the example above it is clear that:

• The rule targets a breakfast category
• It applies to all stores
• It is active from 07:00 on weekends

recommendations

Used for upsell rule types (upsellProduct, upsellCategory, upsellReplacementOffer). Fields:

Field	Description
triggerEvent	When the upsell is triggered. productAdd triggers when a product is added to the basket; checkout triggers when the guest presses the checkout button.
shownOnPage	Controls the order when multiple upsell steps are configured for the same trigger. Lower numbers appear first.
ifInBasket	Whether the upsell is shown if the recommended product is already in the basket.
productIds	Array of product IDs to recommend. Used for upsellProduct.
categoryIds	Array of category IDs to recommend. Used for upsellCategory.

Replacement offer

When creating a upsellReplacementOffer, do not use productIds or categoryIds. Instead, provide a replacementOffer object with the following properties (all arrays):

Property	Description
source1	Product IDs that trigger the replacement offer (first pairing). E.g. a small beverage.
source2	Product IDs that trigger the replacement offer (second pairing). E.g. small fries. Optional if only one pair is needed.
destination1	Product IDs to offer instead of source1. E.g. a medium beverage.
destination2	Product IDs to offer instead of source2. E.g. medium fries. Optional if only one pair is needed.

Example: to offer vegan protein as a meal replacement, use only one source/destination pair.

filter

The filter object defines more granular triggering criteria — for example, a rule that only applies to specific stores, certain days of the week, or particular order types.

Every property inside filter shares the same structure:

{
  "appliesTo": "all" | "specific" | "allExceptSpecific",
  "values": [ ... ]  // required when appliesTo is "specific" or "allExceptSpecific"
}

appliesTo value	Behaviour
all	The filter condition matches everything; values is not used.
specific	Only the items listed in values are matched.
allExceptSpecific	Everything except the items listed in values is matched.

Available filter properties:

Filter property	Value type	Data type
products	Product IDs	int
categories	Category IDs	int
stores	Store IDs	string
storeCountryIsoCodes	ISO 3166 Alpha-2 country codes	string
orderClasses	NotSet, TakeAway, Delivery, EatIn, DriveThrough, KioskTakeAway, KioskEatIn	string
daysOfWeek	monday, tuesday, wednesday, thursday, friday, saturday, sunday	string

activeDuring

Controls when the rule is active.

• timeOfDay — set applies to always, or to between and provide startTime and endTime in hh:mm:ss format.
• dates — set applies to always, or to between and provide startDate and endDate as RFC 3339 date-time strings (e.g. 2022-05-13T06:00:00Z).

executionIndex

Sets the priority order in which rules are evaluated. A lower index is evaluated first. The last rule evaluated for a given product, category, or store wins.

Example: if index 1 says "show cola" and index 42 says "hide cola", the cola will be hidden because index 42 is evaluated last.