Need to create rules based on bundles?
Learn more
LogoLogo
APIsChangelog
  • Getting started
  • Rules
  • Conditions
    • Scope
    • Aggregations
    • Nested
    • Dynamic values
  • Actions
    • Types
      • Percentage
      • Fixed amount
      • Fixed price
      • Buy X pay Y
      • Every X discount Y
    • Bundle
      • Balanced
      • Every
    • Aggregation
    • Limit
  • Matchers
  • Operators
  • Check and validation
  • Core API integration
    • Order rules
    • Price rules
    • Virtual relationships
  • Resources
    • Promotions
    • Price lists
  • Use cases
    • Promotions
      • Discount line items based on item's price
      • Get a discount when paying by credit card
      • Discount an order based on promo item and total number of items
      • Offer a specific shipping method for free in a specific country
      • Discount items with large stock availability
      • Discount all the SKU in an order based on the shipping country
      • Discount all the SKU in an order based on the customer email domain
    • Price lists
      • Discount all prices greater than or equal to a specific value
      • Discount specific SKUs for new clients
      • Change strike-through price based on customer email domain
On this page
  • Example
  • Check and outcomes
  • Validation and errors

Check and validation

How to use the public endpoint to check and validate a rule against a specific payload

PreviousOperatorsNextOrder rules

Last updated 1 month ago

If you need to check and validate a rule against a specific payload, you can leverage the public endpoint:

https://{{your_domain}}.commercelayer.io/api/rules/check

Where {{your_domain}} is the unique subdomain of a Commerce Layer organization for which the Rules Engine is enabled.

To do that you just need to send a POST request using a or access token and passing the rules you want to check along with the payloads you want the rules to be checked against:

Key
Type
Description

payload

Array

An array of objects containing the resource payload(s) you want the rules to be checked against.

rules

Array

An array of objects containing the rules you want to check against the payload.

You'll get in the response all the rules outcomes information, including:

  • The overall matching result of the rules.

  • The list of all the conditions matchers.

  • The list of single resources on which the related actions will be applied.

  • Any errors.

... and more.

Example

Check and outcomes

The following request checks the outcomes of a rule that should apply a 3% discount to the total amount of the orders paid by credit card against two different order payloads:

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/api/rules/check' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "payload": [
      {
        "order": {
          "id": "oKkhYLlzgE",
          "payment_method": {
            "id": "gnYtPpKLeG",
            "payment_source_type": "credit_cards"
          }
        }
      },
      {
        "order": {
          "id": "DgkhGJlzgf",
          "payment_method": {
                    "id": "snXtWdKLdC",
                    "payment_source_type": "wire_transfers"
                }
            }
        }
    ],
    "rules": [
      {
        "name": "Discount 3% if paid by credit card",
        "conditions": [
          {
            "field": "order.payment_method.payment_source_type",
            "matcher": "eq",
            "value": "credit_cards",
            "group": "discountable-orders"
          }
        ],
        "actions": [
          {
            "type": "percentage",
            "selector": "order",
            "value": 0.03,
            "groups": [ "discountable-orders" ]
          }
        ]
      }
    ]
  }'

The response code is 200 OK and the response payload shows the outcomes of the rule's application:

  • The overall rule matches because one of the two orders in the payload was paid by credit card. The order and related payment method IDs are listed within the conditions.matches array.

  • The 3% percentage discount is applied to the order paid by credit card only (oKkhYLlzgE), as you can see from the actions.resources array.

{
  "data": [
    {
      "id": "x123y456-7zk8-9012-x34y-56789z0123kx",
      "name": "Discount 3% if paid by credit card",
      "priority": 0,
      "match": true,
      "conditions_logic": "and",
      "conditions": [
        {
          "field": "order.payment_method.payment_source_type",
          "matcher": "eq",
          "value": "credit_cards",
          "group": "discountable-orders"
          "match": true,
          "matches": [
            {
              "order": "oKkhYLlzgE",
              "payment_method": "gnYtPpKLeG",
              "group": "discountable-orders"
            }
          ],
          "scope": "any"
        }
      ],
      "actions": [
        {
          "resources": [
            {
              "resource_type": "orders",
              "id": "oKkhYLlzgE",
              "group": "discountable-orders",
              "quantity": null,
              "value": 0.03,
              "action_type": "percentage"
            }
          ]
        }
      ]
    }
  ]
}

Validation and errors

The following request checks the outcomes of a couple of rules that should apply a 3% discount to the total amount of the orders paid by credit card and a 1000 cents fixed amount discount to the total amount of the orders that have more than two SKUs, but the rule payloads contain some errors:

  • The type of action in the second rule is fixed (which doesn't exist among the available action types) instead of fixed_amount.

curl -g -X POST \
  'https://{{your_domain}}.commercelayer.io/api/rules/check' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "payload": [
      {
        "order": {
          "id": "oKkhYLlzgE",
          "payment_method": {
            "id": "gnYtPpKLeG",
            "payment_source_type": "credit_cards"
          }
        }
      },
      {
        "order": {
          "id": "DgkhGJlzgf",
          "payment_method": {
            "id": "snXtWdKLdC",
            "payment_source_type": "wire_transfers"
          }
        }
      }
    ],
    "rules": [
      {
        "name": "Discount 3% if paid by credit card",
        "conditions": [
          {
            "field": "order.payment_method.payment_source",
            "matcher": "eq",
            "value": "credit_cards",
            "group": "paid-by-cc"
          }
        ],
        "actions": [
          {
            "type": "percentage",
            "selector": "order",
            "value": "3%",
            "groups": [ "paid-by-cc" ]
          }
        ]
      },
      {
        "name": "Discount 1000 cents if order has > 2 items",
        "conditions": [
          {
            "field": "order.skus_count",
            "matcher": "gt",
            "value": 2,
            "group": "min-num-items"
          }
        ],
        "actions": [
          {
            "type": "fixed",
            "selector": "order",
            "value": 1000,
            "groups": [ "min-num-items" ]
          }
        ]
      }
    ]
  }'

The response code is 400 Bad request and the response payload details all the errors, with a reference to the malformed rule in the title key:

{
  "errors": [
    {
      "title": "Discount 3% if paid by credit card",
      "detail": "Field 'payment_source' is not valid for 'payment_method'.",
      "code": "BAD_REQUEST"
    },
    {
      "title": "Discount 3% if paid by credit card",
      "detail": "Actions value must be a Float with a maximum of 4 decimals, between 0 and 1 (inclusive).",
      "code": "BAD_REQUEST"
    },
    {
      "title": "Discount 1000 cents if order has > 2 items",
      "detail": "Actions action type must be one of: percentage, fixed_amount, fixed_price, buy_x_pay_y, every_x_discount_y.",
      "code": "BAD_REQUEST"
    }
  ]
}

If you just need to validate the syntax of one or more rules, you can pass an empty object in the payload array "payload": [ { } ]. If you get a 200 OK response code, it means that the rule is syntactically correct. Otherwise, the errors will be listed in the response with a 400 Bad request status code.

The first rule's field is payment_source (a wrong attribute that doesn't exist in the Core API's resource object) instead of payment_source_type.

The of the percentage discount value in the first rule is incorrect.

sales channel
integration
format
payment method