data-src=../../../includes/saas-only.md

Catalog price rules

Use these REST endpoints to manage catalog price rules in Adobe Commerce as a Cloud Service. Rules apply product discounts to the specified websites and customer groups.

Authentication

These endpoints require an IMS access token. To access them, you must have the Magento_CatalogRule::promo_catalog permission.

Website scope

Set the rule's target websites with website_ids. The Store header controls the REST request scope. See the REST API overview for URL and header details.

REST API reference

Rule fields

Create and update requests wrap the rule fields in a rule object. Defaults only apply when creating a rule. On update, omitted or null fields preserve their existing values.

Discount actions

The simple_action determines how discount_amount changes the price:

Schedule dates

Both from_date and to_date accept:

• YYYY-MM-DD. The start date uses the beginning of the day and the end date uses the end of the day in the configured Admin timezone.
• YYYY-MM-DD HH:MM:SS. The datetime is interpreted as UTC.

Schedule values are stored and returned as UTC datetimes. To clear an existing schedule boundary in an update, send an empty string for that field. Omitting the field or sending null preserves its current value.

Conditions

The condition object is a root group. Each group has a conditions array containing leaf conditions, nested groups, or both.

• aggregator: "all" combines children with AND. "any" combines them with OR. The default is "all".
• match specifies the required result for each child: true or false. The default is true. The aggregator determines whether any or all children must have that result. For example, "all" with match: false requires every child condition to be false.
• A leaf uses attribute_code, operator, and a string value. Do not include aggregator, match, or child conditions on a leaf.
• A nested group uses aggregator, match, and child conditions. Do not include leaf fields on a group.

The following condition value targets products in attribute set 4 that belong to either category 12 or category 13. You can send it in a create or update request.

{
  "aggregator": "all",
  "match": true,
  "conditions": [
    {
      "attribute_code": "attribute_set_id",
      "operator": "==",
      "value": "4"
    },
    {
      "aggregator": "any",
      "match": true,
      "conditions": [
        {
          "attribute_code": "category_ids",
          "operator": "==",
          "value": "12"
        },
        {
          "attribute_code": "category_ids",
          "operator": "==",
          "value": "13"
        }
      ]
    }
  ]
}

Condition trees support up to 10 levels and 100 total nodes, including the root group. Nested groups must contain at least one child.

Use only operators returned for the attribute by the metadata endpoint. Where an operator supports multiple values, supply a comma-separated string, such as "12,13", rather than a JSON array. Scalar operators for structured values require a single value. The <=> operator means "is undefined" and does not require a value.

Boolean condition values use "0" or "1". Date condition values accept YYYY-MM-DD or YYYY-MM-DD HH:MM:SS.

Condition attributes

The metadata endpoint returns the discount actions and condition attributes available on your instance. Each attribute includes its supported operators and, for attributes with predefined values, the endpoint that returns those values.

GET /V1/catalogPriceRules/metadata

The following response is shortened to show only the category condition:

{
  "simple_actions": [
    "by_percent",
    "by_fixed",
    "to_percent",
    "to_fixed"
  ],
  "condition_attributes": [
    {
      "attribute_code": "category_ids",
      "label": "Category",
      "input_type": "select",
      "operators": ["==", "!=", "{}", "!{}", "()", "!()"],
      "value_source": "/V1/categories"
    }
  ]
}

Available attributes depend on your instance's configuration. Use the attributes and operators returned by the metadata endpoint.

Lookup values

Retrieve the IDs needed for rule scope and condition values using the following endpoints. Each endpoint requires the permission shown next to it.

• Website IDs: GET /V1/store/websites, which requires Magento_Backend::store.
• Customer group IDs: GET /V1/customerGroups/search, which requires Magento_Customer::group.
• Category IDs: GET /V1/categories, which requires Magento_Catalog::categories.
• Product attribute set IDs: GET /V1/products/attribute-sets/sets/list, which requires Magento_Catalog::sets.
• Attribute option values: GET /V1/products/attributes/{attributeCode}/options, which requires Magento_Catalog::attributes_attributes.

Use option values, not option labels, in conditions for select and multiselect attributes.

Manage rules

Create a rule

The following request creates an inactive rule that reduces prices by 10 percent for products in category 12, on website 1, for customer group 1.

POST /V1/catalogPriceRules

Request body:

{
  "rule": {
    "name": "Category discount",
    "website_ids": [1],
    "customer_group_ids": [1],
    "simple_action": "by_percent",
    "discount_amount": 10,
    "condition": {
      "aggregator": "all",
      "match": true,
      "conditions": [
        {
          "attribute_code": "category_ids",
          "operator": "==",
          "value": "12"
        }
      ]
    }
  }
}

The response returns the saved rule object. The following response is shortened to show the generated ID and default values:

{
  "rule_id": 42,
  "name": "Category discount",
  "is_active": 0,
  "discount_amount": 10,
  "stop_rules_processing": 1,
  "sort_order": 0
}

Review the saved rule before activating it with is_active: 1.

data-variant=info

data-slots=text

Retrieve a rule

GET /V1/catalogPriceRules/42

The response returns the rule object, including its full condition tree.

Update a rule

Updates preserve existing values for fields you omit or set to null. For example, the following request activates the rule and changes the discount to 15 percent without changing its name, scope, schedule, or conditions:

PUT /V1/catalogPriceRules/42

Request body:

{
  "rule": {
    "is_active": 1,
    "discount_amount": 15
  }
}

The response returns the updated rule object. The API validates the combined existing and requested values. For example, updating discount_amount to 150 on a by_percent rule fails even when simple_action is omitted.

Updates that activate a rule or leave it active also validate its existing conditions. If a referenced category, attribute set, or option has been removed, correct the condition before saving.

If you provide condition, it replaces the entire condition tree. Omitting condition or sending null preserves the existing tree. To remove all product conditions, send an empty root group:

{
  "rule": {
    "condition": {
      "aggregator": "all",
      "match": true,
      "conditions": []
    }
  }
}

An empty root group makes the rule apply to all products within its website and customer group scope. It is not a way to disable the rule. To disable it, set is_active to 0.

Search rules

Use /V1/catalogPriceRules/search to list and filter rules. The following request returns the first page of 20 active rules:

GET /V1/catalogPriceRules/search
    ?searchCriteria[filterGroups][0][filters][0][field]=is_active
    &searchCriteria[filterGroups][0][filters][0][value]=1
    &searchCriteria[filterGroups][0][filters][0][conditionType]=eq
    &searchCriteria[pageSize]=20
    &searchCriteria[currentPage]=1

The query parameters are shown on separate lines for readability. Send them as one URL.

The response contains:

• items - an array of rule objects, including their condition trees.
• search_criteria - the criteria used for the request.
• total_count - the total number of matching rules across all pages.

See Search using REST endpoints for filter groups, comparison operators, sorting, and pagination. This endpoint returns 200 rules per page by default and at most 500.

Delete a rule

DELETE /V1/catalogPriceRules/42

The response confirms deletion:

true

Error handling