Rule Engine & Risk Check

General

Learn about the Checkout Rule Engine and its configurations.

The Rule Engine can be used to restrict the checkout options configured for your shop. Checkout options are based on certain conditions (rules) that you set in the SCAYLE Panel.
This page describes aspects of the Rule Engine including:

• Checkout Options
• Adding rules
• Editing/deleting rules
• Rick Check to stop the buying process in the case of high risk orders
• Use cases for the Rule Engine
• Data model explanation

Checkout Options

Checkout options correspond to different results in the Rule Engine. Based on whether conditions are met (e.g., order > cost > withTax <= 500 ), options can be:

• Deactivated (option is visible but not usable)
• Disabled (option is not visible and not usable)
• Use to trigger notification (notification shown to customers when selecting the option for their order)

All options have to be configured before you can restrict them in the Rule Engine. You can't influence the order of options.

Option categories include:

• Delivery Options
• Payment Options
• Shipping Options
• Collection Point Delivery Options

Delivery Options

Results under Delivery Options include:

• All Address Options
• Collection Points
• Diverging Billing and Shipping Address
• Same Billing and Shipping Address

Delivery options on the front end

Example Rule Engine use case: Certain delivery options are disabled for large items

Payment Options

Methods may vary based on your specific checkout configuration. Some example payment options include:

• Accounting
• All Payment Methods
• Cash on Delivery (DHL)
• Giftcard (Epay)
• External
• PayPal

Example Rule Engine use case: Disable payment methods that are prone to fraud for certain basket values/items/shipping addresses.

Example Rule Engine use case (Express Payment Options): Restrict express payment methods to certain user groups.

Payment options on the front end

Shipping Options

The available shipping options are based on specific tenant architecture. Some required shipping options for the Rule Engine have to be added. Shipping options available dy default include:

• all_shipping_options
• express_delivery
• least_packages
• scheduled_delivery
• standard_delivery

Example Rule Engine use case: Disable a shipping option for certain country.

Shipping options on the front end

Collection Point Delivery Options

It is possible to configure the kind of collection points that are available on the map. Only collection point deactivation is possible.

Example Rule Engine use case: If a customer chooses "Pick-up station" as a delivery option, a map with all options is shown.

Collection Points on the front end

Add Rules

Rules (conditions) are created at the shop level.

You can add subconditions to a rule to handle complex scenarios. However within one rule, use the same operator - do not mix AND/OR operators within the same rule. For more details, see Use Cases

To add a rule:

• Navigate to Shops > Storefront > Checkout 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 too 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 subcondition, click the + SUB CONDITION button. [tip] When adding a subcondition, you have to choose the same operator for multiple subconditions within the rule. For more details, see Use Cases [/tip]
• Optional Add another rule (condition) with AND/OR operators.

3. 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.

Editing rules

To edit a rule:

1. Go to Shops > Storefront > Checkout 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 Shops > Storefront > Checkout 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 Shops > Storefront > Checkout Settings > Rule Engine.

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

Use Cases / Examples

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

Complex scenarios might include conditions and subconditons. Within one condition you can only set subconditons 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

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.

To set such a rule:

1. Add a Name (e.g., "Shipping costs by country") and Description (e.g., "Enable 34,38 euro for respective countries").
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

4. Click Create to save the rule.

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 Shopping 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.

  

2. 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.

  

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.

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 subconditions: 1. Go to Shops > Storefront > Checkout 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.

Example

json

Copy

{
    "address": {
        "billing": {
            "id": 998,
            "additional": "c/o AboutYou",
            "city": "Hamburg",
            "countryCode": "DEU",
            "houseNumber": "12",
            "isDefault": {
                "billing": false,
                "shipping": false
            },
            "recipient": {
                "firstName": "Anna",
                "gender": "m",
                "lastName": "Doe"
            },
            "referenceKey": "address-7656",
            "street": "Hauptstraße",
            "zipCode": "20459"
        },
        "shipping": {
            "id": 998,
            "city": "Hamburg",
            "collectionPoint": {
                "customerKey": "bced-234-234",
                "description": "Pedro's Kiosk",
                "key": "12345-a",
                "type": "hermes_parcelshop"
            },
            "countryCode": "DEU",
            "houseNumber": "10",
            "isDefault": {
                "billing": false,
                "shipping": false
            },
            "recipient": {
                "firstName": "Anna",
                "gender": "m",
                "lastName": "Doe"
            },
            "referenceKey": "address-7656",
            "street": "Domstrasse",
            "zipCode": "20459"
        }
    },
    "application": {
        "appId": 139,
        "countryCode": "DEU",
        "currencyCode": "EUR",
        "device": "desktop",
        "languageCode": "DE"
    },
    "client": {
        "currentTime": "2018-01-20T09:30:15+00:00",
        "ip": "0.0.0.0",
        "languageCode": "FR",
        "location": {
            "city": "Offenbach",
            "countryCode": "DEU",
            "region": "Hessen"
        },
        "userAgent": {
            "browser": "Chrome",
            "device": "desktop",
            "platform": "Windows",
            "version": "7.0"
        }
    },
    "customer": {
        "id": 9876,
        "authentication": {
            "data": {
                "accessToken": "a0we0effg424",
                "userId": "567765"
            },
            "type": "password"
        },
        "birthDate": "1981-02-02",
        "customData": {
            "score": {
                "requestFailed": true
            }
        },
        "email": "[email protected]",
        "firstName": "Anna",
        "gender": "f",
        "groups": [
            {
                "item": "new"
            },
            {
                "item": "app"
            }
        ],
        "lastName": "Doe",
        "phone": "0049/1234567890",
        "referenceKey": "customer-1234",
        "status": {
            "isActive": true,
            "isGuestCustomer": false,
            "isTestCustomer": false
        },
        "createdAt": "2018-01-20T09:30:15+00:00",
        "updatedAt": "2018-01-20T09:30:15+00:00"
    },
    "items": [
        {
            "availableQuantity": 20,
            "customData": {
                "key": "value"
            },
            "deliveryForecast": {
                "deliverable": {
                    "key": "directShipping",
                    "quantity": 18
                },
                "subsequentDelivery": {
                    "key": "christmas",
                    "quantity": 2
                }
            },
            "itemGroup": {
                "id": "ab123",
                "isMainItem": true,
                "isRequired": true
            },
            "key": "ac834d23e689u678",
            "packageId": 1,
            "price": {
                "appliedReductions": [
                    {
                        "amount": {
                            "absoluteWithTax": 100,
                            "relative": 0.5
                        },
                        "category": "sale",
                        "type": "relative"
                    }
                ],
                "reference": {
                    "size": "100",
                    "unit": "ml",
                    "withTax": 595
                },
                "tax": {
                    "vat": {
                        "amount": 190,
                        "rate": 0.19
                    }
                },
                "withoutTax": 1000,
                "withTax": 1190
            },
            "product": {
                "id": 4564545,
                "advancedAttributes": {
                    "materialCompositionTextile": {
                        "key": "materialCompositionTextile",
                        "label": "Materialzusammensetzung",
                        "values": [
                            {
                                "fieldSet": [
                                    [
                                        {
                                            "value": "Lining"
                                        }
                                    ]
                                ],
                                "groupSet": [
                                    {
                                        "fieldSet": [
                                            [
                                                {
                                                    "value": 80
                                                },
                                                {
                                                    "unit": "%"
                                                },
                                                {
                                                    "material": "Cotton"
                                                }
                                            ]
                                        ],
                                        "groupSet": [
                                        ]
                                    }
                                ]
                            }
                        ]
                    }
                },
                "attributes": {
                    "description": {
                        "key": "description",
                        "label": "Beschreibung",
                        "values": [
                            {
                                "id": 1234,
                                "label": "A descriptive string (possibly including HTML)",
                                "value": "Optional value"
                            }
                        ]
                    }
                },
                "categories": [
                    [
                        {
                            "categoryId": 20201,
                            "categoryName": "Frauen",
                            "categoryProperties": {
                                "priority": {
                                    "name": "priority",
                                    "value": "1"
                                }
                            },
                            "categoryUrl": "/frauen"
                        }
                    ]
                ],
                "definingAttributes": [
                    {
                        "key": "color",
                        "label": "Farbe"
                    }
                ],
                "images": [
                    {
                        "attributes": {
                            "description": {
                                "key": "description",
                                "label": "Beschreibung",
                                "values": [
                                    {
                                        "label": "A descriptive string (possibly including HTML)"
                                    }
                                ]
                            }
                        },
                        "hash": "9f6c628a98106dcce2bc5a4ac1de9c14"
                    }
                ],
                "masterKey": "480306626-1",
                "name": "Chelsea Boots",
                "createdAt": "2018-01-20T09:30:15+00:00",
                "updatedAt": "2018-01-20T09:30:15+00:00"
            },
            "status": "available",
            "variant": {
                "id": 1234567,
                "attributes": {
                    "vendorSize": {
                        "key": "vendorSize",
                        "label": "Größe",
                        "values": [
                            {
                                "id": 25472,
                                "label": "34",
                                "value": "Thirty Four"
                            }
                        ]
                    }
                },
                "referenceKey": "563843898",
                "stock": {
                    "customData": {
                    },
                    "deliveryForecast": {
                        "deliverable": {
                            "key": "directShipping",
                            "quantity": 18
                        },
                        "subsequentDelivery": {
                            "key": "christmas",
                            "quantity": 2
                        }
                    },
                    "isSellableWithoutStock": false,
                    "quantity": 18,
                    "supplierId": 271
                },
                "createdAt": "2018-01-20T09:30:15+00:00",
                "updatedAt": "2018-01-20T09:30:15+00:00"
            },
            "createdAt": "2018-01-20T09:30:15+00:00",
            "updatedAt": "2018-01-20T09:30:15+00:00"
        }
    ],
    "order": {
        "id": 123,
        "appliedLoyaltyPoints": 0,
        "basketKey": "basket-c6v7k4eer1",
        "cost": {
            "appliedReductions": [
                {
                    "amount": {
                        "absoluteWithTax": 100,
                        "relative": 0.5
                    },
                    "category": "voucher",
                    "type": "absolute"
                }
            ],
            "capture": 1090,
            "tax": {
                "vat": {
                    "amount": 123,
                    "rate": 0.5
                }
            },
            "withoutServiceCost": 1190,
            "withoutTax": 1000,
            "withTax": 1190
        },
        "currencyCode": "EUR",
        "customData": {
            "score": {
                "requestFailed": true
            }
        },
        "referenceKey": "order-2234",
        "createdAt": "2018-01-20T09:30:15+00:00",
        "updatedAt": "2018-01-20T09:30:15+00:00"
    },
    "packages": [
        {
            "id": 1,
            "carrierKey": "dhl",
            "deliveryDate": {
                "maximum": "2018-02-05",
                "minimum": "2018-02-02"
            },
            "deliveryStatus": "open",
            "returnIdentCode": "100-1",
            "shipmentKey": "shpmnt-100-1",
            "tracking": {
                "id": "79003131200523",
                "url": "https://tracking.hermesworld.com/?TrackID=79003131200523"
            }
        }
    ],
    "payment": [
        {
            "amount": 1190,
            "data": {
                "CCBrand": "VISA",
                "CCExpiry": "202005",
                "IPCity": "charlottenburg",
                "IPLatitude": "52.5151",
                "IPLongitude": "13.3053",
                "IPState": "berlin",
                "IPZone": "276",
                "IPZoneA2": "de"
            },
            "key": "computop_creditcard",
            "transactionKey": "creditcard-abcde"
        }
    ],
    "vouchers": [
        {
            "id": 198234,
            "applicableItems": [
                {
                    "isApplied": true,
                    "key": "a87ff679a2f3e71d9181a67b7542122c"
                },
                {
                    "isApplied": false,
                    "key": "eccbc87e4b5ce2fe28308fd9f2a7baf3"
                }
            ],
            "code": "fashion2020",
            "type": "absolute",
            "value": 1000
        }
    ]
}

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 (minimum length: ) (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) (minimum length: ) (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 (minimum length: ) (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) (minimum length: ) (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 (minimum length: ) (maximum length: 3)
  • currencyCode string (minimum length: ) (maximum length: 3)
  • device string
  • languageCode string (minimum length: ) (maximum length: 2)
• client object
  • currentTime string (date-time validation)
  • ip string
  • languageCode string (optional) (minimum length: ) (maximum length: 2)
  • location object (optional)
    • city string (optional)
    • countryCode string (optional) (minimum length: ) (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) (minimum length: ) (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) (minimum length: ) (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) (minimum length: ) (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) (minimum length: ) (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) (minimum length: ) (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) (minimum length: )
    • 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

Risk Check

Implement a custom risk assessment service

The risk check feature is meant to be used in combination with the Rule Engine. Your risk assessment results will be made available on the order and customer models, so that you can configure the Rule Engine to deny certain or even all payment methods depending on your own custom rule sets.

Once you have configured the API Credentials for this service and SCAYLE activated the feature, checkout will execute calls to the given endpoint. The response of those calls will be stored as the customData.score property on the order object.

Risk evaluation

SCAYLE supports the passive risk check approach:

1. The customer has already provided a billing & shipping address, selected a delivery and shipping options and selected a payment method.
2. The customer proceeds to close the order (after clicking on Buy now):
   • if the feedback is negative, the customer is redirected to the confirmation page, , leading to limited payment methods and notifying the customer to change the selected payment method
   • if the feedback is positive it redirects the customer to the order success page.

The Checkout will store the last risk check result for future interactions within the customer object.

How to implement

You need to provide a http service that can handle the usual load of your shop and which accepts requests from the SCAYLE networks.

If you want to limit incoming traffic by IP address, your SCAYLE Account Manager can provide more information about our networks.

This service needs to implement a POST endpoint according to the following schema:

Request

Your endpoint needs to be able to serve the following request.

Authentication

Basic auth according to SCAYLE Panel configuration.

Headers

Body

Request example

json

Copy

{
    "id": 123,
    "address": {
        "billing": {
            "id": 998,
            "additional": "c/o AboutYou",
            "city": "Hamburg",
            "countryCode": "DEU",
            "houseNumber": "12",
            "isDefault": {
                "billing": false,
                "shipping": false
            },
            "recipient": {
                "firstName": "Anna",
                "gender": "m",
                "lastName": "Doe"
            },
            "referenceKey": "address-1324",
            "street": "Domstraße 10",
            "zipCode": "20095"
        },
        "shipping": {
            "id": 998,
            "city": "Hamburg",
            "collectionPoint": {
                "customerKey": "bced-234-234",
                "description": "Pedro's Kiosk",
                "key": "12345-a",
                "type": "hermes_parcelshop"
            },
            "countryCode": "DEU",
            "houseNumber": "10",
            "isDefault": {
                "billing": false,
                "shipping": false
            },
            "recipient": {
                "firstName": "Anna",
                "gender": "m",
                "lastName": "Doe"
            },
            "referenceKey": "address-1324",
            "street": "Domstraße 10",
            "zipCode": "20095"
        }
    },
    "basketKey": "basket-c6v7k4eer1",
    "confirmedAt": "2018-01-20T11:30:15+00:00",
    "cost": {
        "withoutTax": 1000,
        "withTax": 1190
    },
    "currencyCode": "EUR",
    "customer": {
        "id": 9876,
        "authentication": {
            "data": {
                "accessToken": "a0we0effg424",
                "userId": "567765"
            },
            "type": "password"
        },
        "birthDate": "1981-02-02",
        "customData": {
            "score": {
                "requestFailed": true
            }
        },
        "email": "[email protected]",
        "firstName": "Anna",
        "gender": "f",
        "groups": [
            {
                "item": "new"
            },
            {
                "item": "app"
            }
        ],
        "lastName": "Doe",
        "phone": "0049/1234567890",
        "referenceKey": "customer-1234",
        "status": {
            "isActive": true,
            "isGuestCustomer": false,
            "isTestCustomer": false
        },
        "createdAt": "2018-01-20T09:30:15+00:00",
        "updatedAt": "2018-01-20T09:30:15+00:00"
    },
    "invoicedAt": "2018-01-22T11:30:15+00:00",
    "items": [
        {
            "availableQuantity": 20,
            "customData": {
                "key": "value"
            },
            "deliveryForecast": {
                "deliverable": {
                    "key": "directShipping",
                    "quantity": 18
                },
                "subsequentDelivery": {
                    "key": "christmas",
                    "quantity": 2
                }
            },
            "itemGroup": {
                "id": "ab123",
                "isMainItem": true,
                "isRequired": true
            },
            "key": "ac834d23e689u678",
            "packageId": 1,
            "price": {
                "appliedReductions": [
                    {
                        "amount": {
                            "absoluteWithTax": 100,
                            "relative": 0.5
                        },
                        "category": "sale",
                        "type": "relative"
                    }
                ],
                "reference": {
                    "size": "100",
                    "unit": "ml",
                    "withTax": 595
                },
                "tax": {
                    "vat": {
                        "amount": 190,
                        "rate": 0.19
                    }
                },
                "withoutTax": 1000,
                "withTax": 1190
            },
            "product": {
                "id": 4564545,
                "advancedAttributes": {
                    "materialCompositionTextile": {
                        "key": "materialCompositionTextile",
                        "label": "Materialzusammensetzung",
                        "values": [
                            {
                                "fieldSet": [
                                    [
                                        {
                                            "value": "Lining"
                                        }
                                    ]
                                ],
                                "groupSet": [
                                    {
                                        "fieldSet": [
                                            [
                                                {
                                                    "value": 80
                                                },
                                                {
                                                    "unit": "%"
                                                },
                                                {
                                                    "material": "Cotton"
                                                }
                                            ]
                                        ],
                                        "groupSet": [
                                        ]
                                    }
                                ]
                            }
                        ]
                    }
                },
                "attributes": {
                    "description": {
                        "key": "description",
                        "label": "Beschreibung",
                        "values": [
                            {
                                "id": 1234,
                                "label": "A descriptive string (possibly including HTML)",
                                "value": "Optional value"
                            }
                        ]
                    }
                },
                "categories": [
                    [
                        {
                            "categoryId": 20201,
                            "categoryName": "Frauen",
                            "categoryProperties": {
                                "priority": {
                                    "name": "priority",
                                    "value": "1"
                                }
                            },
                            "categoryUrl": "/frauen"
                        }
                    ]
                ],
                "definingAttributes": [
                    {
                        "key": "color",
                        "label": "Farbe"
                    }
                ],
                "images": [
                    {
                        "attributes": {
                            "description": {
                                "key": "description",
                                "label": "Beschreibung",
                                "values": [
                                    {
                                        "label": "A descriptive string (possibly including HTML)"
                                    }
                                ]
                            }
                        },
                        "hash": "9f6c628a98106dcce2bc5a4ac1de9c14"
                    }
                ],
                "masterKey": "480306626-1",
                "name": "Chelsea Boots",
                "createdAt": "2018-01-20T09:30:15+00:00",
                "updatedAt": "2018-01-20T09:30:15+00:00"
            },
            "status": "available",
            "variant": {
                "id": 1234567,
                "attributes": {
                    "vendorSize": {
                        "key": "vendorSize",
                        "label": "Größe",
                        "values": [
                            {
                                "id": 25472,
                                "label": "34",
                                "value": "Thirty Four"
                            }
                        ]
                    }
                },
                "referenceKey": "563843898",
                "stock": {
                    "customData": {
                    },
                    "deliveryForecast": {
                        "deliverable": {
                            "key": "directShipping",
                            "quantity": 18
                        },
                        "subsequentDelivery": {
                            "key": "christmas",
                            "quantity": 2
                        }
                    },
                    "isSellableWithoutStock": false,
                    "quantity": 18,
                    "supplierId": 271
                },
                "createdAt": "2018-01-20T09:30:15+00:00",
                "updatedAt": "2018-01-20T09:30:15+00:00"
            },
            "createdAt": "2018-01-20T09:30:15+00:00",
            "updatedAt": "2018-01-20T09:30:15+00:00"
        }
    ],
    "packages": [
        {
            "id": 1,
            "carrierKey": "dhl",
            "deliveryDate": {
                "maximum": "2018-02-05",
                "minimum": "2018-02-02"
            },
            "deliveryStatus": "open",
            "returnIdentCode": "100-1",
            "shipmentKey": "shpmnt-100-1",
            "tracking": {
                "id": "79003131200523",
                "url": "https://tracking.hermesworld.com/?TrackID=79003131200523"
            }
        }
    ],
    "payment": [
        {
            "amount": 1190,
            "data": {
                "CCBrand": "VISA",
                "CCExpiry": "202005",
                "IPCity": "charlottenburg",
                "IPLatitude": "52.5151",
                "IPLongitude": "13.3053",
                "IPState": "berlin",
                "IPZone": "276",
                "IPZoneA2": "de"
            },
            "key": "computop_creditcard",
            "transactionKey": "creditcard-abcde"
        }
    ],
    "referenceKey": "order-2234",
    "status": "invoice_completed",
    "vouchers": [
        {
            "id": 198234,
            "applicableItems": [
                {
                    "isApplied": true,
                    "key": "a87ff679a2f3e71d9181a67b7542122c"
                },
                {
                    "isApplied": false,
                    "key": "eccbc87e4b5ce2fe28308fd9f2a7baf3"
                }
            ],
            "code": "fashion2020",
            "type": "absolute",
            "value": 1000
        }
    ],
    "createdAt": "2018-01-20T09:30:15+00:00",
    "updatedAt": "2018-01-20T09:30:15+00:00"
}

Request schema

• id integer
• address object (optional)
  • billing object
    • id integer
    • additional string ([!-ɏ0-9 ]) (optional)
    • city string ([!-ɏ0-9 ])
    • collectionPoint object (optional)
    • countryCode string (minimum length: ) (maximum length: 3)
    • houseNumber string ([!-ɏ0-9 ])
    • isDefault object
    • recipient object
    • referenceKey string (^[0-9a-zA-Z\-\\_\.\@]*$) (optional) (minimum length: ) (maximum length: 100)
    • street string ([!-ɏ0-9 ])
    • title string ([!-ɏ0-9 ]) (optional)
    • zipCode string ([A-z0-9\- ]{1,12})
  • forward object (optional)
    • additional string ([!-ɏ0-9 ]) (optional)
    • city string ([!-ɏ0-9 ]) (optional)
    • collectionPoint object (optional)
    • countryCode string (optional) (minimum length: ) (maximum length: 3)
    • houseNumber string ([!-ɏ0-9 ]) (optional)
    • recipient object (optional)
    • street string ([!-ɏ0-9 ]) (optional)
    • zipCode string ([A-z0-9\- ]{1,12}) (optional)
    • createdAt string (date-time validation) (optional)
    • updatedAt string (date-time validation) (optional)
  • shipping object
    • id integer
    • additional string ([!-ɏ0-9 ]) (optional)
    • city string ([!-ɏ0-9 ])
    • collectionPoint object (optional)
    • countryCode string (minimum length: ) (maximum length: 3)
    • houseNumber string ([!-ɏ0-9 ])
    • isDefault object
    • recipient object
    • referenceKey string (^[0-9a-zA-Z\-\\_\.\@]*$) (optional) (minimum length: ) (maximum length: 100)
    • street string ([!-ɏ0-9 ])
    • title string ([!-ɏ0-9 ]) (optional)
    • zipCode string ([A-z0-9\- ]{1,12})

• basketKey string

• campaignKey string (optional)

• client **** (optional)

• confirmedAt string (date-time validation) (optional)

• cost object
  • withoutTax integer
  • withTax integer

• currencyCode string (^([A-Z]{3})$)

• customData object (optional) (object is extensible as desired)

• customer object (optional)
  • id integer
  • authentication object (optional)
    • data object (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)
  • 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) (minimum length: ) (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) (minimum length: ) (maximum length: 100)
  • referenceKey string (^[0-9a-zA-Z\-\\_\.\@]*$) (optional) (minimum length: ) (maximum length: 100)
  • status object
    • isActive boolean
    • isGuestCustomer boolean
    • isTestCustomer boolean
  • title string ([!-ɏ0-9 ]) (optional) (minimum length: ) (maximum length: 100)
  • type enum (personal retail organization family) (optional)
  • createdAt string (date-time validation)
  • updatedAt string (date-time validation)

• invoicedAt string (date-time validation) (optional)

• items array (optional)
  • availableQuantity integer (optional)
  • customData object (optional) (object is extensible as desired)
  • deliveryForecast object (optional)
    • deliverable object
    • subsequentDelivery object
  • itemGroup **** (optional)
  • key string
  • packageId integer
  • price object
    • appliedReductions array (optional)
    • reference object (optional)
    • tax object (object is extensible as desired)
    • withoutTax integer
    • withTax integer
  • product object
    • id integer
    • advancedAttributes object (optional) (object is extensible as desired)
    • attributes object (optional) (object is extensible as desired)
    • categories array (optional)
    • definingAttributes array (optional)
    • images array
    • 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
    • advancedAttributes object (optional) (object is extensible as desired)
    • attributes object (optional) (object is extensible as desired)
    • referenceKey string (optional)
    • stock object (optional)
    • createdAt string (date-time validation)
    • updatedAt string (date-time validation)
  • warehouseId integer (optional)
  • createdAt string (date-time validation)
  • updatedAt string (date-time validation)

• loyaltyCard object (optional)
  • cardNumber string
  • points integer
  • provider string ([A-Za-z])

• packages array (optional)
  • id integer
  • carrierKey string
  • deliveryDate object
    • 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) (minimum length: )
    • url string (uri validation) (optional)

• payment array (optional)
  • amount integer (optional)
  • data object (optional) (object is extensible as desired)
  • installment array (optional)
    • 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)

• preferred object (optional)
  • carrierKey string (optional)
  • deliveryPolicy enum (least_packages highest_stocks fastest_shipping) (optional)

• publicKey string (^[0-9a-zA-Z\-\\_]*$) (optional) (minimum length: ) (maximum length: 100)

• referenceKey string (^[0-9a-zA-Z\-\\_\.\@]*$) (optional) (minimum length: ) (maximum length: 100)

• shipping object (optional)
  • deliveredOn string ([0-9]{4}\-[0-9]{2}\-[0-9]{2}) (optional)
  • deliveryCosts integer (optional)
  • expressDeliveryCosts integer (optional)
  • policy string (^[0-9a-zA-Z\-\\_]*$) (minimum length: )

• shop object (optional)
  • id integer
  • country string (^([A-Z]{3})$)
  • language string (^([a-z]{2})$)

• status enum (order_open payment_pending payment_reserved invoice_completed cancellation_pending cancellation_completed invoice_partially_completed)

• 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

• createdAt string (date-time validation)

• updatedAt string (date-time validation)

Response

Your service needs to follow this specification when handling the checkout request.

Response body

The response body will be written to the order.customData.score property. Additionally, you may define a custom value set and use this as a reference via the rule engine rules.

Examples

green/red based

value based

request failed

Properties:

• result enum,object,array,number,string,… (optional)

Status Codes: