Price lists

How to use the Rules Engine in conjunction with price lists and set up price rules

The Rule Engine enables you to manage discounts and more also a the price list level (e.g. changing the standard prices of a price list based on certain conditions), using the proper price rules.

To make the Rule Engine work in conjunction with price lists, you need to do is create a new (or update an existing) price list and specify the price rules that you want to be implemented in the rules object. The discount defined by the related actions will be automatically applied to the price list's prices that match the given conditions.

Example

The following request updates the price list identified by the ID vLrWRCDzBE so that all the prices with an amount greater than 10000 cents will be discounted by 10%:

curl -g -X PATCH \
  'https://yourdomain.commercelayer.io/api/price_lists/vLrWRCDzBE' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
    "data": {
      "type": "price_lists",
      "id": "vLrWRCDzBE",
      "attributes": {
        "rules": {
          "rules": [
            {
              "name": "10% Discount on price greater than 10000 cents",
              "conditions": [
                {
                  "field": "price.amount_cents",
                  "matcher": "gt",
                  "value": 10000
                }
              ],
              "actions": [
                {
                  "type": "percentage",
                  "selector": "price"
                  "value": 0.1
                }
              ]
            }
          ]
        }
      }
    }
  }

Available actions

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

Percentage

Fixed price

Fixed amount

Check and validation

Checking if a price rule has been correctly applied is pretty straightforward. Once you've applied the desired rules at the time of the price list's creation or update as shown in the example above, you can simply:

• Fetch all the price list's prices and verify that only the desired ones have been discounted.

• Fetch a single price that should have been discounted and check if it's been correctly updated. This way you can also have access to the detailed rules outcomes.

To see the matching prices' amounts updated in the response remember to use a token with the market to which the price list belongs to in scope.

Examples

Checking the price list's prices

Request

The following request retrieves all the prices belonging to the price list identified by the ID vLrWRCDzBE (for better readability we requested only a subset of fields):

curl -g -X GET \
  'https://yourdomain.commercelayer.io/api/price_lists/vLrWRCDzBE/prices?fields[prices]=amount_cents,original_amount_cents,compare_at_amount_cents,processed_at' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'

Response

On success, the API responds with a 200 OK status code, returning a paginated collection of price list's prices. As you can see the prices whose amount was greater than 10000 cents now show an amount_cents that differs from the original_amount_cents, being discounted by 10% as specified in the rule's action:

{
  "data": [
    {
      "id": "pVOMUMyNvA",
      "type": "prices",
      "links": { ... },
      "attributes": {
        "amount_cents": 2900,
        "original_amount_cents": 2900,
        "compare_at_amount_cents": 4000,
        "processed_at": "2025-01-17T22:00:15.193Z"
      },
      "meta": {
        "mode": "test",
        "organization_id": "YyrQYFmLRk",
        "trace_id": "bfb801b193b16ff40d17c4411e79f9729a55ed85a9d00dde9c822be72fce439d"
      }
    },
    {
      "id": "gLQzUrPnEa",
      "type": "prices",
      "links": { ... }, 
      "attributes": {
        "amount_cents": 2900,
        "original_amount_cents": 2900,
        "compare_at_amount_cents": 4000,
        "processed_at": "2025-01-17T22:00:15.195Z"
      },
      "meta": { ... }
    },
    {
      "id": "peNYUxwryA",
      "type": "prices",
      "links": { ... },
      "attributes": {      
        "amount_cents": 9180,
        "original_amount_cents": 10200,
        "compare_at_amount_cents": 12000,
        "processed_at": "2025-01-17T22:00:15.197Z"
      },
      "meta": { ... }
    },
    {
      "id": "aGqWUrMGEA",
      "type": "prices",
      "links": { ... },
      "attributes": {
        "amount_cents": 11610,
        "original_amount_cents": 12900,
        "compare_at_amount_cents": 15000,
        "processed_at": "2025-01-17T22:00:15.198Z"
      },
      "meta": { ... }
    },
    {
      "id": "gMJQUkdKja",
      "type": "prices",
      "links": { ... },
      "attributes": {
        "amount_cents": 9180,
        "original_amount_cents": 10200,
        "compare_at_amount_cents": 12000,
        "processed_at": "2025-01-17T22:00:15.200Z"
      },
      "meta": { ... }
    },
    {
      "id": "glnlUqkBop",
      "type": "prices",
      "links": { ... },
      "attributes": {
        "amount_cents": 2100,
        "original_amount_cents": 2100,
        "compare_at_amount_cents": 3000,
        "processed_at": "2025-01-17T22:00:15.202Z"
      },
      "meta": { ... }
    },
    {
      "id": "ARXmUrVwWa",
      "type": "prices",
      "links": { ... },
      "attributes": {
        "amount_cents": 9000,
        "original_amount_cents": 9000,
        "compare_at_amount_cents": 11100,
        "processed_at": "2025-01-17T22:00:15.203Z"
      },
      "meta": { ... }
    },
    {
      "id": "grBlUMJKlg",
      "type": "prices",
      "links": { ... },
      "attributes": {
        "amount_cents": 900,
        "original_amount_cents": 900,
        "compare_at_amount_cents": 1500,
        "processed_at": "2025-01-17T22:00:15.205Z"
      },
      "meta": { ... }
    }
  ],
  "meta": {
    "record_count": 8,
    "page_count": 1
  },
  "links": {
    "first": "https://rules-engine.commercelayer.co/api/price_lists/vLrWRCDzBE/prices?fields[prices]=amount_cents,original_amount_cents,compare_at_amount_cents,processed_at?page[number]=1&page[size]=10",
    "last": "https://rules-engine.commercelayer.co/api/price_lists/vLrWRCDzBE/prices?fields[prices]=amount_cents,original_amount_cents,compare_at_amount_cents,processed_at?page[number]=1&page[size]=10"
  }
}

Checking a single price

Request

The following request retrieves the price identified by the ID aGqWUrMGEA (matching price):

curl -g -X GET \
  'https://yourdomain.commercelayer.io/api/prices/aGqWUrMGEA' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'

Response

On success, the API responds with a 200 OK status code, returning the requested price object. Being the original amount of the price greater than 10000 cents, it has been discounted by 10%, as can be seen by comparing the amount_cents and the original_amount_cents values. For more information, you can inspect the rules object in the response:

• The rules_outcomes object shows that the price matches the rule's condition and that the requested action has been applied.

• The resource_payload object is the lightweight price payload that the Core API integration created to be checked against the rule's condition.

{
  "data": {
    "id": "aGqWUrMGEA",
    "type": "prices",
    "links": { ... },
    "attributes": {
      "currency_code": "USD",
      "sku_code": "BACKPACK818488000000XXXX",
      "amount_cents": 11610,
      "amount_float": 116.10,
      "formatted_amount": "$116.10",
      "original_amount_cents": 12900,
      "formatted_original_amount": "$129.00",
      "compare_at_amount_cents": 15000,
      "compare_at_amount_float": 150.0,
      "formatted_compare_at_amount": "$150.00",
      "processed_at": "2025-01-17T22:44:50.941Z",
      "created_at": "2025-01-17T11:47:36.784Z",
      "updated_at": "2025-01-17T21:59:29.079Z",
      "reference": null,
      "reference_origin": null,
      "rules": {
        "rules": [
          {
            "id": "8b0419e1-8647-19b1-150d-06e9e8f7c005",
            "name": "10% Discount on price greater than 10000 cents",
            "actions": [
              {
                "type": "percentage",
                "value": 0.1,
                "groups": [ "23c015c7-56c4-4a7b-8c8f-26c992c72d9e" ],
                "selector": "price"
              }
            ],
            "conditions": [
              {
                "field": "price.amount_cents",
                "group": "23c015c7-56c4-4a7b-8c8f-26c992c72d9e",
                "value": 10000,
                "matcher": "gt"
              }
            ]
          }
        ]
      },
      "rule_outcomes": [
        {
          "id": "8b0419e1-8647-19b1-150d-06e9e8f7c005",
          "name": "10% Discount on price greater than 10000 cents",
          "priority": 0,
          "match": true,
          "conditions_logic": "and",
          "conditions": [
            {
              "field": "price.amount_cents",
              "group": "23c015c7-56c4-4a7b-8c8f-26c992c72d9e",
              "value": 10000,
              "matcher": "gt",
              "match": true,
              "matches": [ { "price": "aGqWUrMGEA" } ],
              "scope": "any"
            }
          ],
          "actions": [
            {
              "resources": [
                {
                  "resource_type": "prices",
                  "id": "aGqWUrMGEA",
                  "quantity": null,
                  "value": 0.1,
                  "action_type": "percentage"
                }
              ]
           }
          ]
        }
      ],
      "resource_payload": {
        "price": {
          "id": "aGqWUrMGEA",
          "amount_cents": 12900
        }
      },
      "jwt_custom_claim": null,
      "metadata": {}
    },
    "relationships": {
      "price_list": { ... },
      "sku": { ... },
      "price_tiers": { ... },
      "price_volume_tiers": { ... },
      "price_frequency_tiers": { ... },
      "attachments": { ... },
      "versions": { ... },
      "jwt_customer": { ... },
      "jwt_markets": { ... },
      "jwt_stock_locations": { ... }
    },
    "meta": { ... }
  }
}

Request

The following request retrieves the price identified by the ID pVOMUMyNvA (non-matching price):

curl -g -X GET \
  'https://yourdomain.commercelayer.io/api/prices/pVOMUMyNvA' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token'

Response

On success, the API responds with a 200 OK status code, returning the requested price object. Being the original amount of the price lower than 10000 cents, it hasn't been discounted and the amount_cents value is still equal to the original_amount_cent value. For more information, you can inspect the rules object in the response::

• The rules_outcomes show that the price doesn't match the rule's condition (the conditions.matches array is empty). Consequently, no action is applied (the actions array is empty as well).

• The resource_payload is the lightweight price payload that the Core API integration created to be checked against the rule's condition.

{
  "data": {
    "id": "pVOMUMyNvA",
    "type": "prices",
    "links": { ... },
    "attributes": {
      "currency_code": "USD",
      "sku_code": "5PANECAP000000FFFFFFXXXX",
      "amount_cents": 2900,
      "amount_float": 29.0,
      "formatted_amount": "$29.00",
      "original_amount_cents": 2900,
      "formatted_original_amount": "$29.00",
      "compare_at_amount_cents": 4000,
      "compare_at_amount_float": 40.0,
      "formatted_compare_at_amount": "$40.00",
      "processed_at": "2025-01-17T23:05:37.532Z",
      "created_at": "2025-01-17T11:46:16.929Z",
      "updated_at": "2025-01-17T11:46:16.929Z",
      "reference": null,
      "reference_origin": null,
      "rules": {
        "rules": [
          {
            "id": "8b0419e1-8647-19b1-150d-06e9e8f7c005",
            "name": "10% Discount on price greater than 10000 cents",
            "actions": [
              {
                "type": "percentage",
                "value": 0.1,
                "groups": [ "23c015c7-56c4-4a7b-8c8f-26c992c72d9e" ],
                "selector": "price"
              }
            ],
            "conditions": [
              {
                "field": "price.amount_cents",
                "group": "23c015c7-56c4-4a7b-8c8f-26c992c72d9e",
                "value": 10000,
                "matcher": "gt"
              }
            ]
          }
        ]
      },
      "rule_outcomes": [
        {
          "id": "8b0419e1-8647-19b1-150d-06e9e8f7c005",
          "name": "10% Discount on price greater than 10000 cents",
          "priority": 0,
          "match": false,
          "conditions_logic": "and",
          "conditions": [
            {
              "field": "price.amount_cents",
              "group": "23c015c7-56c4-4a7b-8c8f-26c992c72d9e",
              "value": 10000,
              "matcher": "gt",
              "match": false,
              "matches": [],
              "scope": "any"
            }
          ],
          "actions": []
           }
          ]
        }
      ],
      "resource_payload": {
        "price": {
          "id": "pVOMUMyNvA",
          "amount_cents": 2900
        }
      },
      "jwt_custom_claim": null,
      "metadata": {}
    },
    "relationships": {
      "price_list": { ... },
      "sku": { ... },
      "price_tiers": { ... },
      "price_volume_tiers": { ... },
      "price_frequency_tiers": { ... },
      "attachments": { ... },
      "versions": { ... },
      "jwt_customer": { ... },
      "jwt_markets": { ... },
      "jwt_stock_locations": { ... }
    },
    "meta": { ... }
  }
}

Use cases

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

Price lists