Check and validation

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

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 sales channel or integration 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

Request

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" ]
          }
        ]
      }
    ]
  }'

Response

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

Request

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 first rule's field is payment_source (a wrong attribute that doesn't exist in the Core API's payment method resource object) instead of payment_source_type.
• The format of the percentage discount value in the first rule is incorrect.

• 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" ]
          }
        ]
      }
    ]
  }'

Response

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.