docs

Rule Engine

General

The Checkout Rule Engine allows you to dynamically control checkout options such as delivery, shipping, and payment methods.

By defining rules, you can automatically enable, disable or hide options. You can also trigger notifications based on customer, order, or payment data.´

Example use cases:

  • Certain delivery options are disabled for large items
  • Disable a shipping option for certain country.
  • Disable payment methods that are prone to fraud for certain basket values/items/shipping addresses.
  • Restrict express payment methods to certain user groups.

Rules

Rules can change how available checkout options behave in three ways:

  • Disable – the option remains visible but cannot be selected
  • Hide – the option is completely removed from the checkout view
  • Notification – a message is displayed when the customer tries to select the option

Supported option categories are

  • Delivery
  • Shipping
  • Payment
  • Collection Points

Creating Rules

Rules are created at the shop level.

To add a rule:

  • In the SCAYLE Panel, open Settings ➜ Rule Engine.
  • Select +ADD RULE or +ADD FIRST RULE.

Complete the 3 sections on the New Rule page.

  1. General Info: Add a Name and Description for the rule.
  2. Click ADD CONDITION to add a new rule:
  • Select an object or collection from the list (e.g., order, customer, payment).
  • Menus are populated based on previous selections (e.g., order > id, customer > lastName, payment > amount).
  • When the variable selection is complete, click ADD.
  • Select the operator (e.g., =, !=, >, <, <=, IS, IS NOT, IN, NOT IN) and corresponding value (e.g., 10, London).
  • To add a sub-condition, click the + SUB CONDITION button.

When adding a sub-condition, you have to choose the same operator for multiple sub-conditions within the rule.

  • Optional Add another rule (condition) with AND/OR operators.
  1. Results: Select one or more results to trigger if the conditions are met (e.g., Payment Options ➜ All Payment Methods ➜ Deactivate Payment Method).
Results

Rule Engine Result.

Rule Engine Result: Deactivate payment method.

Since the rules disable options, it is easier to start with the more general excludes and then become more specific.

  • For example, first, exclude shipping options that are not relevant for one country so you don't have to repeat the exclusion in every rule

Managing rules

To edit a rule:

1. Go to Settings ➜ Rule Engine.

2. On the Rule Engine page, hover over the three-dot menu on the rule you want to edit, and Edit.

To deactivate a rule:

1. Go to Settings ➜ Rule Engine.

2. On the Rule Engine page, hover over the three-dot menu on the rule you want to deactivate, select Deactivate.

To delete a rule:

1. Go to Settings ➜ Rule Engine.

2. On the Rule Engine page, hover over the three-dot menu on the rule you want to delete, and Delete.

Examples

The following examples are intended to explain some real-world scenarios.

Complex scenarios might include conditions and sub-conditons. Within one condition you can only set sub-conditons using the same operator (AND/OR).

Minimum Order Value (MOV) for Payment Method

A rule can be set for payment methods requiring a minimum order value (MOV). For example, you may want to disable the Accounting (B2B) payment method for orders less than a threshold. If MOV is not reached, the payment method is deactivated (does not appear in checkout).

To set this rule:

  1. Add a Name (e.g., "MOV for Accounting") and Description (e.g., "Minimum Order Value for Accounting Payment Method")
  2. Add the Condition: order > cost > withoutServiceCost <= 5000 (≙ 50.00€)
  3. Select the Result: Payment Options > Accounting | Deactivate Payment Method
  4. Click Create to save the rule

Example- Minimum Order Value (MOV) for a Payment Method

Shipping Costs per Country

A rule can be set to enable/disable specific shipping costs for a given shipping country (global or EU shop). For example, you can create a rule where, if a customer selects a shipping country, all shipping options are disabled that do not have a specific cost.

For details on setting Shipping Options (including shipping cost) see Shipping Options.

To set such a rule:

  1. Add a Name (e.g., "Shipping costs for TUR") and Description (e.g., "Disables shipping options for TUR").
  2. Add the Condition: e.g., address > shipping > countryCode IS TUR
  3. Select the Results: e.g.,
  • Shipping Options > rule-engine.available_shipping_options.1299 | Deactivate Shipping Options
  • Shipping Options > rule-engine.available_shipping_options.1546 | Deactivate Shipping Options
  • Shipping Options > rule-engine.available_shipping_options.1427 | Deactivate Shipping Options
  • Deactivate other shipping options where shipping cost ≠ 34,38
  1. Click Create to save the rule.

For conditions with countryCode use the iso_alpha3 (e.g., for Germany it is DEU).

Shipping Options per Shipping Country

Free Shipping Campaign for Time Frame

Rules can be set to enable free shipping for a given time period (e.g., promotion campaign). This requires 2 rules, one to enable free shipping and another to define standard shipping outside of the free shipping time period.

This can be done as follows:

  1. Create a Rule for Free Shipping
  • Add a Name (e.g., "Free Shipping Option") and Description (e.g., "Free shipping for time frame + min. order value").
  • Add the Conditions: e.g.,
    • order > cost > withoutServiceCost >= 4000 (40.00)
    • AND client > currentTime between 06-03-2023 09:00:00 - 09-03-2023 00:00:00
  • Select the Results: e.g., Shipping Options ➜ DHL Standard | Deactivate Shipping Options
  • Click Create to save the rule.

Free Shipping Option

  1. Create a Rule to Disable Free Shipping
  • Add a Name (e.g., "Free Shipping Disable") and Description (e.g., "Enable free shipping only when campaign is active").
  • Add the Conditions: e.g.,
    • client > currentTime before 06-03-2023 09:00:00
    • OR client > currentTime after 09-03-2023 00:00:00
    • OR order > cost > withoutServiceCost <= 4000 (40.00)
  • Select the Results: e.g., Shipping Options > DHL Standard (free shipping) | Deactivate Shipping Options
  • Click Create to save the rule.

Disable Free Shipping Option

Max Order Value

Below is a sample rule set for an order with a max value of 700 €. All payment methods will be deactivated if the customer orders items that cost higher than 700 €.

To set this a rule:

  • Add a Name (e.g., "Max Order Value") and Description (e.g., "Max. order value = 700 €").
  • Add the Condition: e.g., order > cost > withTax > 70000 (≙ 700.00 €)
  • Select the Results: e.g.,
    • Payment Options ➜ All Payment Methods | Deactivate Payment Method
    • Payment Options ➜ All Payment Methods | Error Payment Method
    • Add error message (e.g, "The maximum order value is 700 €")
  • Click Create to save the rule.

Payment methods disabled for order values above 700 €.

Setting Multiple Subconditions: Free Shipping for a time period for chosen customers

Scenario: Set free shipping for all women living in Berlin or Hamburg for orders from the 7th of March until the 9th of March.
You can set a rule containing multiple statements, however within a statement, use the same operator. A single rule can contain multiple subconditions joined by one operator (such as a sub-condition AND another subcondition AND another subcondition), but you cannot mix operators within a single rule. To add a statement with a different operator, create a new rule.

For example, one rule could target:

  • Main condition: is female. AND
    1. Sub condition: shipping after the 7th of March AND
    2. Sub condition: shipping before the 9th of March.

To target women who live in Berlin OR in Hamburg, we have to add a new condition, as we cannot mix operators AND/OR within the same condition statement.

  • Main Condition: lives in Germany.
  1. Sub condition: lives in Berlin OR
  2. Sub condition: lives in Hamburg

To add multiple conditions and sub-conditions:

1. Go to Settings ➜ Rule Engine

2. Select +ADD RULE.

3. Add a Name and Description.

4. Click ADD CONDITION too add a new rule:

  • Select customer > gender > ADD.
  • Choose the IS and select f from the dropdown. Specify the timeframe:
  • Click +SUB CONDITION, then order > createdAt > datetimeOperations > ADD. Select before from the dropdown. Pick the date and time from the calendar.
  • Click ADD CONDITION, then order > updatedAt > datetimeOperations > ADD. Select after from the dropdown. Pick the date and time from the calendar.

Add new condition to specify location. Multiple locations possible using OR operator:

  • Click ADD CONDITION too add a new rule:
  • Select address > shipping > city > ADD. Type a city, for example "Berlin".
  • Click +SUB CONDITION, then address > shipping > city > ADD. Type a city, for example "Hamburg".
  • Switch toggle to OR.

Add free shipping:

  • Select the Results: e.g., Shipping Options ➜ DHL Standard | Deactivate Shipping Options
    • Click Create to save the rule.

Data model explanation

You can access a variety of properties to build your custom rules. Rules can be written on the following standardized data structure. Not all information will be available from beginning to end during the ordering process, for example a shipping address will not yet be available for new customers when evaluating rules for the delivery options filter.

Schema

  • address object
    • billing object
      • id integer
      • additional string ([!-ɏ0-9 ]) (optional) - Additional data pertaining to the address, such as c/o AboutYou.
      • city string ([!-ɏ0-9 ])
      • collectionPoint object (optional) - A collection point is an alternate shipping address, which will hold the customer's packages until pickup. Examples for collection points are DHL Packstations, DHL Post Offices and Hermes Paketshops.
        • customerKey string ([A-z0-9]) (optional)
        • description string ([!-ɏ0-9 ]) (optional)
        • key string ([A-z0-9])
        • type string
      • countryCode string (maximum length: 3)
      • houseNumber string ([!-ɏ0-9 ])
      • isDefault object
        • billing boolean
        • shipping boolean
      • recipient object
        • firstName string ([!-ɏ0-9 ])
        • gender enum (m f d) (optional)
        • lastName string ([!-ɏ0-9 ])
      • referenceKey string (^[0-9a-zA-Z\-\\_\.\@]*$) (optional) (maximum length: 100) - External reference set by the client to integrate a 3rd party system
      • street string ([!-ɏ0-9 ])
      • title string ([!-ɏ0-9 ]) (optional)
      • zipCode string ([A-z0-9\- ]{1,12})
    • shipping object
      • id integer
      • additional string ([!-ɏ0-9 ]) (optional) - Additional data pertaining to the address, such as c/o AboutYou.
      • city string ([!-ɏ0-9 ])
      • collectionPoint object (optional) - A collection point is an alternate shipping address, which will hold the customer's packages until pickup. Examples for collection points are DHL Packstations, DHL Post Offices and Hermes Paketshops.
        • customerKey string ([A-z0-9]) (optional)
        • description string ([!-ɏ0-9 ]) (optional)
        • key string ([A-z0-9])
        • type string
      • countryCode string (maximum length: 3)
      • houseNumber string ([!-ɏ0-9 ])
      • isDefault object
        • billing boolean
        • shipping boolean
      • recipient object
        • firstName string ([!-ɏ0-9 ])
        • gender enum (m f d) (optional)
        • lastName string ([!-ɏ0-9 ])
      • referenceKey string (^[0-9a-zA-Z\-\\_\.\@]*$) (optional) (maximum length: 100) - External reference set by the client to integrate a 3rd party system
      • street string ([!-ɏ0-9 ])
      • title string ([!-ɏ0-9 ]) (optional)
      • zipCode string ([A-z0-9\- ]{1,12})
  • application object
    • appId integer
    • countryCode string (maximum length: 3)
    • currencyCode string (maximum length: 3)
    • device string
    • languageCode string (maximum length: 2)
  • client object
    • currentTime string (date-time validation)
    • ip string
    • languageCode string (optional) (maximum length: 2)
    • location object (optional)
      • city string (optional)
      • countryCode string (optional) (maximum length: 3)
      • region string (optional)
    • userAgent object (optional)
      • browser string (optional)
      • device string (optional)
      • platform string (optional)
      • version string (optional)
  • customer object
    • id integer
    • authentication object (optional)
      • data object (optional)
        • accessToken string (optional)
        • userId string (optional)
      • type enum (facebook password)
    • birthDate string (^((19|20)[0-9]{2}\-[0-9]{2}\-[0-9]{2})$) (optional)
    • customData object (optional) (object is extensible as desired) - Additional data attached by the client to enhance the customer
    • email string (email validation) (optional) (maximum length: 50)
    • firstName string ([!-ɏ0-9 ])
    • gender enum (m f d) (optional)
    • groups array (optional)
      • item string (^[0-9a-zA-Z\-\\_]*$) (optional) (maximum length: 60)
    • lastName string ([!-ɏ0-9 ])
    • phone string (00[0-9]{1,3}/[0-9]{1,20}) (optional)
    • publicKey string (^[0-9a-zA-Z\-\\_]*$) (optional) (maximum length: 100) - Public reference set by the client to display to customers in account areas and transactional emails
    • referenceKey string (^[0-9a-zA-Z\-\\_\.\@]*$) (optional) (maximum length: 100) - External reference set by the client to integrate a 3rd party system
    • status object
      • isActive boolean
      • isGuestCustomer boolean
      • isTestCustomer boolean
    • title string ([!-ɏ0-9 ]) (optional) (maximum length: 100)
    • type enum (personal retail organization family) (optional)
    • createdAt string (date-time validation)
    • updatedAt string (date-time validation)
  • items array
    • availableQuantity integer (optional) - The number of deliverable items available in the warehouse for immediate shipping.
    • customData object (optional) (object is extensible as desired) - customData allows the tennant to attach data to an item. The data will remain attached to the item from the basket through the process of order creation and delegation and may be displayed to the customer during the order lifecycle.
    • deliveryForecast object (optional) - When an item cannot be shipped within the regular delivery timeframe, and the warehouse is already aware of this, prior to the customer placing the order (ie it is not an unintentionally delayed delivery). This is generally the case when the item is out of stock and: the warehouse is waiting for incoming returns to restock the item, the warehouse has ordered fresh stocks from the supplier/manufacturer and is waiting for these to be shipped to the warehouse.
      • deliverable object
        • key string (optional)
        • quantity integer (optional)
      • subsequentDelivery object
        • key enum (endOfJanuary endOfFebruary endOfMarch endOfApril endOfMay endOfJune endOfJuly endOfAugust endOfSeptember endOfOctober endOfNovember endOfDecember midOfJanuary midOfFebruary midOfMarch midOfApril midOfMay midOfJune midOfJuly midOfAugust midOfSeptember midOfOctober midOfNovember midOfDecember easter christmas available directShipping outsold) (optional)
        • quantity integer (optional)
    • itemGroup **** (optional)
    • key string
    • packageId integer - Items are grouped by package, depending on the item's supplier configuration. The packageId references an entry in the packages list with delivery estimates and expected carrier.
    • price object - The price is provided in a currency's lowest denomination (e.g. cent for EUR). In a multi-supplier environment, the price displayed on an item is dictated by the supplier order of preference, which is configured in the SCAYLE Panel.
      • appliedReductions array (optional) - The discounts detail the reductions included in the final price.withTax and price.withoutTax calculation.
        • amount object
        • absoluteWithTax integer
        • relative number - The rate is calculated on the basis of the reduction in relation to the preDiscountPrice price.
        • category enum (sale campaign voucher)
        • type enum (relative absolute)
      • reference object (optional)
        • size string (optional)
        • unit string (optional)
        • withTax integer (optional)
      • tax object (object is extensible as desired) - List of all taxes applied in calculating the price.withTax
        • $key object (optional)
        • amount number
        • rate number
      • withoutTax integer - This price excludes taxes, but also includes all applicable reductions.
      • withTax integer - The price is calculated including taxes and all applicable reductions such as discounts for sale and campaigns (should a campaign key be provdided on the request).
    • product object
      • id integer - This id can be applied as a parameter on the url to retrieve an individual product in the Fetch Product by ID endpoint.
      • advancedAttributes object (optional) (object is extensible as desired) - A subset of advanced attributes
        • $key **** (optional)
      • attributes object (optional) (object is extensible as desired)
        • $key object (optional)
        • key string
        • label string - The locale is defined by the configuration of the shop associated with the authentication token. Translations of the individual attributes are maintained in the SCAYLE Panel.
        • multiSelect boolean (optional)
        • type string,null (optional)
        • values ****
      • categories array (optional)
        • categoryHidden boolean (optional) - If set to true, this Category is not displayed in the Shop.
        • categoryId integer - This id can be applied as a parameter on the url to retrieve an individual category in the Fetch Category by ID endpoint.
        • categoryName ****
        • categoryProperties **** (optional)
        • categoryUrl ****
      • definingAttributes array (optional) - A subset of the attributes groups that distinguish the variants from other variants attached to the product.
        • key string
        • label string - The locale is defined by the configuration of the shop associated with the authentication token. Translations of the individual attributes are maintained in the SCAYLE Panel.
      • images array
        • attributes object (optional) (object is extensible as desired)
        • hash string - As the hash is generated with the image data, it can be applied to monitor for changes on the underlying image.
      • masterKey string (optional)
      • name string
      • createdAt string (date-time validation)
      • updatedAt string (date-time validation)
    • reservationKey string (optional)
    • status enum (available unavailable deliverable undeliverable cancelled)
    • variant object
      • id integer - This id can be applied as a parameter on the url to retrieve an individual variant in the Fetch Variant by ID endpoint.
      • advancedAttributes object (optional) (object is extensible as desired) - A subset of advanced attributes
        • $key **** (optional)
      • attributes object (optional) (object is extensible as desired) - A subset of attributes will always be provided on the variant: those characteristics of a variant that set it apart from the other variants attached to the same product. By applying the with parameter in the query the returned attributes can be extended at will.
        • $key object (optional)
        • key string
        • label string - The locale is defined by the configuration of the shop associated with the authentication token. Translations for the individual attributes are maintained in the SCAYLE Panel.
        • multiSelect boolean (optional)
        • values ****
      • referenceKey string (optional)
      • stock object (optional)
        • customData object,array (optional)
        • deliveryForecast object (optional) - When an item cannot be shipped within the regular delivery timeframe, and the warehouse is already aware of this, prior to the customer placing the order (ie it is not an unintentionally delayed delivery). This is generally the case when the item is out of stock and: the warehouse is waiting for incoming returns to restock the item, the warehouse has ordered fresh stocks from the supplier/manufacturer and is waiting for these to be shipped to the warehouse.
        • deliverable object (optional)
        • subsequentDelivery object (optional)
        • isSellableWithoutStock boolean (optional) - Determines if the given variant is sellable even though it has no stock
        • quantity integer - Remaining quantity in stock for the given variant. Reserved items have not been deducted from the overall stock count.
        • supplierId integer,null
      • createdAt string (date-time validation)
      • updatedAt string (date-time validation)
    • warehouseId integer (optional)
    • createdAt string (date-time validation)
    • updatedAt string (date-time validation)
  • order object
    • id integer - This id can be applied as a parameter on the url to retrieve an individual order in the Fetch Order by ID endpoint.
    • appliedLoyaltyPoints integer (optional) - Amount of discount loyalty points used for the order
    • basketKey string - Reference to the basket attached to this order
    • campaignKey string (optional) - Reference to the campaign applied to this order
    • confirmedAt string (date-time validation) (optional)
    • cost object - The price is provided in a currency's lowest denomination (e.g. cent for EUR). In a multi-supplier environment, the price displayed on an item is dictated by the supplier order of preference, which is configured in the SCAYLE Panel.
      • appliedFees array (optional) - The appliedFees detail the additional payment and delivery costs included in the final price.withTax and price.withoutTax calculation.
        • amount ****
        • category enum (payment delivery)
        • key string
        • option string (optional)
      • appliedReductions array (optional) - The discounts detail the reductions included in the final price.withTax and price.withoutTax calculation.
        • amount object
        • absoluteWithTax integer
        • relative number - The rate is calculated on the basis of the reduction in relation to the preDiscountPrice price.
        • category enum (voucher)
        • type enum (absolute)
      • capture integer (optional) - The total value to be captured excluding reductions (membership loyalty points, giftcard, and voucher discounts)
      • tax object (object is extensible as desired) - List of all taxes applied in calculating the price.withTax
        • $key object (optional)
        • amount number
        • rate number
      • withoutServiceCost integer (optional) - The price is calculated including taxes and all applicable reductions such as discounts for sale and campaigns, but without any service costs.
      • withoutTax integer - This price excludes taxes, but also includes all applicable reductions.
      • withTax integer - The price is calculated including taxes and all applicable reductions such as discounts for sale and campaigns (should a campaign key be provdided on the request).
    • currencyCode string (^([A-Z]{3})$) - The three character ISO-4217 currency code that identifies the currency. The currency is defined on the configuration of the shop, and can be modified in the SCAYLE Panel.
    • customData object (optional) (object is extensible as desired) - Additional data attached by the client to enhance the order
    • referenceKey string (^[0-9a-zA-Z\-\\_\.\@]*$) (optional) (maximum length: 100) - External reference set by the client to integrate a 3rd party system
    • createdAt string (date-time validation)
    • updatedAt string (date-time validation)
  • packages array
    • id integer - Basket and order items are matched to a package by cross-referencing the item[].packageId.
    • carrierKey string
    • deliveryDate object - The delivery dates are calculated based on the hour-to-hour estimates configured per supplier in the SCAYLE Panel. Once the order has been confirmed and shipments have been received, the calculation is based on the warehouse cut-off times and transport duration. If the carrier provides a delivery estimate, this is applied.
      • maximum string ([0-9]{4}\-[0-9]{2}\-[0-9]{2})
      • minimum string ([0-9]{4}\-[0-9]{2}\-[0-9]{2})
    • deliveryStatus enum (open shipment_pending delegation_pending shipment_completed cancellation_completed)
    • returnIdentCode null,string (optional)
    • shipmentKey string (optional)
    • tracking object (optional)
      • id string (optional)
      • url string (uri validation) (optional)
  • payment array
    • amount integer (optional)
    • data object (optional) (object is extensible as desired)
    • installment array (optional) - Details about installments
      • amount integer (optional)
      • type enum (annualInterest firstInstallment installmentAddition paymentMethodCosts subsequentInstallments valutaAddition) (optional)
    • key string (optional)
    • options object (optional)
      • countOfInstallments integer (optional)
      • hasPaybreak boolean (optional)
    • transactionKey string (optional)
  • vouchers array (optional)
    • id integer
    • applicableItems array (optional)
      • isApplied boolean (optional)
      • key string (optional)
    • code string ([A-z0-9]{0,12})
    • type enum (absolute relative)
    • value number
Example
Previous
Newsletter Subscription
Next up
Transactions & Orders