--- sidebar_label: 'API Reference' sidebar_position: 2 --- # Rules API Reference Full reference for the rule object and its fields. Use the [Examples](./example-rules.md) 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](#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](./stockout.md). ## 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: ```json { "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.