Need to create rules based on bundles?
Learn more
Changelog

Promotions

How to set up promotions with the Rules Engine using order rules

The Rule Engine enables you to set up almost any kind of promotions to boost your sales, from the simplest to the most complex, using the proper order rules.

To make the Rule Engine work in conjunction with promotions, you need to leverage Commerce Layer flex promotions. All you need to do is create a new flex promotion and give it a meaningful name, specifying the activation and expiration dates as the values of the related attributes and the order rules that you want to be implemented in the rules object. The discount defined by the related actions will be automatically applied to the orders that match the given conditions.

Example

The following request creates a flex promotion that applies a 10% discount to the whole order if it contains at least 2 units of a promotional product:

curl -g -X POST \
  'https://yourdomain.commercelayer.io/api/flex_promotions' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "flex_promotions",
    "attributes": {
      "name": "Personal promotion",
      "starts_at": "2018-01-01T12:00:00.000Z",
      "expires_at": "2018-01-02T12:00:00.000Z",
      "rules": {
        "rules": [
          {
            "name": "10% Promo T-shirt x2",
            "conditions": [
              {
                "field": "order.line_items.sku.code",
                "matcher": "eq",
                "value": "PROMOTSHIRT",
                "nested": {
                  "conditions": [
                    {
                      "field": "order.line_items.quantity",
                      "matcher": "gteq",
                      "value": 2
                    }
                  ]
                }
              }
            ],
            "actions": [
              {
                "type": "percentage",
                "selector": "order",
                "value": "0.1"
              }
            ]
          }
        ]
      }
    }
  }
}'

Available actions

The following action types are enabled on the flex promotions endpoint:

PercentageFixed priceFixed amountBuy X pay YEvery X discount Y

Check and validation

Once you've created a flex promotion (and defined one or more order rules) you can validate it against a specific order to check the rules outcomes (e.g. if and how the related discount will be applied in the case in point). You just need the flex promotion and the order IDs so that you can send (using a sales channel or integration access token) a GET request to the endpoint:

https://{{your_domain}}.commercelayer.io/api/flex_promotions/{{promo_id}}/check/{{order_id}}

Where:

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

  • {{promo_id}} is the ID of the flex promotion whose outcomes you want to check.

  • {{order_id}} is the ID of the order against which you want to validate the flex promotion.

Examples

Matching order

Let's assume you want to check the flex promotion identified by the ID ZOqmZfjPOp against the order identified by the ID NZrQhpRpRZ:

The following flex contains a rule according to which the orders with a total amount greater than 5000 cents will be discounted by 10%:

{
  "data": {
    "id": "ZOqmZfjPOp",
    "type": "flex_promotions",
    "links": { ... },
    "attributes": {
      "name": "Discount 10% if total greater than 5000 cents",
      "type": "flex_promotions",
      "exclusive": false,
      "priority": null,
      "starts_at": "2025-01-14T14:24:14.975Z",
      "expires_at": "2025-12-14T14:10:51.660Z",
      "total_usage_limit": null,
      "total_usage_count": 0,
      "active": true,
      "status": "active",
      "rules": {
        "rules": [
          {
            "id": "b0dd0bbf-7938-3d99-f556-14ba2b67c5fe",
            "name": "Discount 10% if total greater than 5000 cents",
            "conditions": [
              {
                "field": "order.total_amount_cents",
                "group": "bc285595-bae4-53fd-7471-41ef3048c220",
                "value": 5000,
                "matcher": "gt"
              }
            ],            
            "actions": [
              {
                "type": "percentage",
                "value": 0.1,
                "groups": [ "bc285595-bae4-53fd-7471-41ef3048c220" ],
                "selector": "order"
              }
            ]
          }
        ]
      },
      "disabled_at": null,
      "created_at": "2025-01-14T14:24:15.234Z",
      "updated_at": "2025-01-14T14:40:50.884Z",
      "reference": null,
      "reference_origin": null,
      "rule_outcomes": {},
      "resource_payload": {},
      "metadata": {}
    },
    "relationships": { ... },
    "meta": { ... }
  }
}

Let's call the validation endpoint to check the rule's outcomes:

The following request validates the rule identified by the ID ZOqmZfjPOp against the order identified by the ID NZrQhpRpRZ:

curl -g -X GET \
  'http://yourdomain.commercelayer.io/api/flex_promotions/ZOqmZfjPOp/check/NZrQhpRpRZ' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json'

Non-matching order

Let's assume you want to check the same flex promotion against the order identified by the ID PgojhLQLQR instead:

The following flex contains a rule according to which the orders with a total amount greater than 5000 cents will be discounted by 10%:

{
  "data": {
    "id": "ZOqmZfjPOp",
    "type": "flex_promotions",
    "links": { ... },
    "attributes": {
      "name": "Discount 10% if total greater than 5000 cents",
      "type": "flex_promotions",
      "exclusive": false,
      "priority": null,
      "starts_at": "2025-01-14T14:24:14.975Z",
      "expires_at": "2025-12-14T14:10:51.660Z",
      "total_usage_limit": null,
      "total_usage_count": 0,
      "active": true,
      "status": "active",
      "rules": {
        "rules": [
          {
            "id": "b0dd0bbf-7938-3d99-f556-14ba2b67c5fe",
            "name": "Discount 10% if total greater than 5000 cents",
            "conditions": [
              {
                "field": "order.total_amount_cents",
                "group": "bc285595-bae4-53fd-7471-41ef3048c220",
                "value": 5000,
                "matcher": "gt"
              }
            ],            
            "actions": [
              {
                "type": "percentage",
                "value": 0.1,
                "groups": [ "bc285595-bae4-53fd-7471-41ef3048c220" ],
                "selector": "order"
              }
            ]
          }
        ]
      },
      "disabled_at": null,
      "created_at": "2025-01-14T14:24:15.234Z",
      "updated_at": "2025-01-14T14:40:50.884Z",
      "reference": null,
      "reference_origin": null,
      "rule_outcomes": {},
      "resource_payload": {},
      "metadata": {}
    },
    "relationships": { ... },
    "meta": { ... }
  }
}

Let's call the validation endpoint to check the rule's outcomes:

The following request validates the rule identified by the ID ZOqmZfjPOp against the order identified by the ID PgojhLQLQR:

curl -g -X GET \
  'http://yourdomain.commercelayer.io/api/flex_promotions/ZOqmZfjPOp/check/PgojhLQLQR' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Accept: application/vnd.api+json'

Use cases

If you need to check more examples of promotions based on the Rule Engine, feel free to explore the related section of this documentation:

Promotions
PreviousVirtual relationshipsNextPrice lists

Last updated