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
  • Available actions
  • Check and validation
  • Examples
  • Use cases
  1. Resources

Price lists

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

PreviousPromotionsNextPromotions

Last updated 3 months ago

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 .

To make the Rule Engine work in conjunction with , you need to do is a new (or 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

Check and validation

Examples

Checking the price list's prices

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'

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

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'

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.

{
  "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": { ... }
  }
}

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'

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

{
  "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

The following are enabled on the flex promotions endpoint:

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 , you can simply:

and verify that only the desired ones have been discounted.

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 .

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

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

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

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

action types
Percentage
Fixed price
Fixed amount
lightweight price payload
lightweight price payload
related section
Price lists
example above
Fetch all the price list's prices
Fetch a single price
price rules
in scope
a subset of fields
price lists
create
update