From 6e2cb6e3d37796961e24ef4f1ad13d82fdec29ff Mon Sep 17 00:00:00 2001 From: Sangmi Lee Date: Thu, 1 Oct 2026 12:02:20 +0200 Subject: [PATCH 1/5] docs: document catalog price rule REST APIs --- src/pages/config.md | 1 + .../catalog-price-rules/index.md | 352 ++++++++++++++++++ src/pages/rest/saas-integrations/index.md | 1 + 3 files changed, 354 insertions(+) create mode 100644 src/pages/rest/saas-integrations/catalog-price-rules/index.md diff --git a/src/pages/config.md b/src/pages/config.md index 80b6409c9..e5861c986 100644 --- a/src/pages/config.md +++ b/src/pages/config.md @@ -156,6 +156,7 @@ - [Multicoupon](/rest/modules/multicoupon/index.md) - [Sales refunds](/rest/modules/sales/index.md) - [SaaS integrations](/rest/saas-integrations/index.md) + - [Catalog price rules](/rest/saas-integrations/catalog-price-rules/index.md) - [Custom email](/rest/saas-integrations/custom-email/index.md) - [Gift card accounts](/rest/saas-integrations/gift-card-accounts/index.md) - [Login as Customer](/rest/saas-integrations/login-as-customer/index.md) diff --git a/src/pages/rest/saas-integrations/catalog-price-rules/index.md b/src/pages/rest/saas-integrations/catalog-price-rules/index.md new file mode 100644 index 000000000..ce8344608 --- /dev/null +++ b/src/pages/rest/saas-integrations/catalog-price-rules/index.md @@ -0,0 +1,352 @@ +--- +title: Catalog Price Rule REST Endpoints +description: Learn how to create, retrieve, update, delete, and search catalog price rules with REST APIs in Adobe Commerce as a Cloud Service. +keywords: + - REST + - Integration +--- + + + +# Catalog price rule API + +The catalog price rule REST API lets integrations manage product discounts without creating or editing each rule in the Admin. Use the API to discover supported conditions, create rules, and manage existing rules with the same nested condition logic available in the Admin. + +Catalog price rules apply to products for the specified websites and customer groups. For cart price rules, which apply discounts during checkout, use the [salesRules API](https://adobe-commerce-saas.redoc.ly/tag/salesRules/). The two APIs use different condition payloads. + +## Authentication and scope + +Authenticate each request with an Adobe Identity Management Service (IMS) access token. The associated Admin role must include the `Magento_CatalogRule::promo_catalog` Access Control List (ACL) resource. Customer and guest access is not supported. + +See [REST authentication](../../authentication/index.md) for user and server-to-server authentication. + +Use the Adobe Commerce as a Cloud Service URL structure: + +```http +GET https://.api.commerce.adobe.com//V1/catalogPriceRules/metadata +Authorization: Bearer +Content-Type: application/json +Store: all +``` + +Do not include `/rest` or a store view code in the URL. The `Store` header specifies the request scope, while the rule's `website_ids` specifies the websites where the discount applies. Include `website_ids` in the rule payload. + +## REST API reference + +All six endpoints require the `Magento_CatalogRule::promo_catalog` ACL resource. + +| Method | Endpoint | Description | +| --- | --- | --- | +| `GET` | `/V1/catalogPriceRules/metadata` | Discover discount actions and attributes available for conditions. | +| `GET` | `/V1/catalogPriceRules/search` | Search rules with filters, sorting, and pagination. | +| `GET` | `/V1/catalogPriceRules/{ruleId}` | Retrieve a rule by ID. | +| `POST` | `/V1/catalogPriceRules` | Create a rule. | +| `PUT` | `/V1/catalogPriceRules/{ruleId}` | Update a rule. | +| `DELETE` | `/V1/catalogPriceRules/{ruleId}` | Delete a rule. | + +## Discover available conditions + +Before creating a rule, retrieve the metadata: + +```http +GET /V1/catalogPriceRules/metadata +``` + +The response contains `simple_actions`, the supported discount actions, and `condition_attributes`, the attributes that can be used in rule conditions. Each attribute includes its `attribute_code`, `label`, `input_type`, supported `operators`, and a `value_source` endpoint when values must be retrieved separately. + +The following response excerpt shows the category condition: + +```json +{ + "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" + } + ] +} +``` + +The available product attributes depend on the instance's attribute configuration. Use the returned metadata instead of assuming that an attribute or operator is supported. + +Retrieve the IDs needed for rule scope and condition values using the following endpoints. These endpoints have their own permission requirements. + +| Values | Endpoint | +| --- | --- | +| Website IDs | `GET /V1/store/websites` | +| Customer group IDs | `GET /V1/customerGroups/search` | +| Category IDs | `GET /V1/categories` | +| Product attribute set IDs | `GET /V1/products/attribute-sets/sets/list` | +| Attribute option values | `GET /V1/products/attributes/{attributeCode}/options` | + +Use option values, not option labels, in conditions for select and multiselect attributes. + +## Rule fields + +Create and update requests wrap the rule fields in a `rule` object. The following requirements and defaults apply when creating a rule. Updates preserve omitted or null fields. + +| Field | Type | Description | +| --- | --- | --- | +| `rule_id` | Integer | The generated rule ID returned by the API. For updates, use the ID in the URL. | +| `name` | String | Required. Must not be blank. | +| `description` | String | Optional rule description. | +| `website_ids` | Integer array | Required. A nonempty list of existing storefront website IDs. Website ID `0` is not supported. | +| `customer_group_ids` | Integer array | Required. A nonempty list of existing customer group IDs. | +| `simple_action` | String | Required. One of the four supported discount actions. | +| `discount_amount` | Number | Required. Must be nonnegative. Percentage actions accept values from 0 to 100. | +| `is_active` | Integer | `0` for inactive or `1` for active. Defaults to `0`. | +| `stop_rules_processing` | Integer | `1` prevents subsequent rules from applying to matching products. `0` allows further rule processing. Defaults to `1`. | +| `sort_order` | Integer | Nonnegative rule priority. Lower values have higher priority. Defaults to `0`. | +| `from_date` | String | Optional start date or UTC datetime. | +| `to_date` | String | Optional end date or UTC datetime. Must not precede `from_date`. | +| `condition` | Object | Optional root condition group containing leaf conditions or nested groups. Omitting it on create targets all products within the rule's website and customer group scope. | + +### Discount actions + +The `simple_action` determines how `discount_amount` changes the price: + +| Action | Behavior | Example for a price of 100 | +| --- | --- | --- | +| `by_percent` | Reduce the price by the specified percentage. | An amount of `20` produces a price of 80. | +| `by_fixed` | Reduce the price by the specified fixed amount. | An amount of `20` produces a price of 80. | +| `to_percent` | Set the price to the specified percentage. | An amount of `20` produces a price of 20. | +| `to_fixed` | Set the price to the specified fixed amount. | An amount of `20` produces a price of 20. | + +### 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. + +## 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`. Replace these IDs with existing values from your instance. + +```http +POST /V1/catalogPriceRules +``` + +Request body: + +```json +{ + "rule": { + "name": "Category discount", + "description": "Ten percent off products in the selected category.", + "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, including its generated `rule_id` and default values: + +```json +{ + "rule_id": 42, + "name": "Category discount", + "description": "Ten percent off products in the selected category.", + "is_active": 0, + "website_ids": [1], + "customer_group_ids": [1], + "simple_action": "by_percent", + "discount_amount": 10, + "stop_rules_processing": 1, + "sort_order": 0, + "condition": { + "aggregator": "all", + "match": true, + "conditions": [ + { + "attribute_code": "category_ids", + "operator": "==", + "value": "12" + } + ] + } +} +``` + +Review the saved rule before activating it with `is_active: 1`. You can also set `is_active` explicitly when creating a rule. + +## Build nested 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 all or any 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 update targets products in attribute set `4` that belong to either category `12` or category `13`. Replace these IDs with valid values from your instance. + +```http +PUT /V1/catalogPriceRules/42 +``` + +Request body: + +```json +{ + "rule": { + "condition": { + "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. + +## Retrieve and update a rule + +Retrieve a rule by its ID: + +```http +GET /V1/catalogPriceRules/42 +``` + +The response returns the rule object, including its full condition tree. + +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: + +```http +PUT /V1/catalogPriceRules/42 +``` + +Request body: + +```json +{ + "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. + +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: + +```json +{ + "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`, not the collection URL, to list and filter rules. The following request finds active rules, sorts them by ID, and returns the first page of 20 results: + +```text +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[sortOrders][0][field]=rule_id + &searchCriteria[sortOrders][0][direction]=ASC + &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. + +Increase `searchCriteria[currentPage]` to retrieve subsequent pages. An omitted or zero page size defaults to 200. Values above 500 are capped at 500. Negative page sizes and current pages below 1 are rejected. + +See [Search using REST endpoints](../../use-rest/performing-searches.md) for filter groups, comparison operators, sorting, and pagination. + +## Delete a rule + +```http +DELETE /V1/catalogPriceRules/42 +``` + +The response confirms deletion: + +```json +true +``` + +## Validation + +Invalid rule input returns HTTP `400`. Validation checks required fields, discount actions and amounts, flags, schedule dates, and the existence of referenced websites and customer groups. + +Conditions are checked against the metadata's allowed attributes and operators. Referenced categories, product attribute sets, and option values must be valid. Boolean condition values use `"0"` or `"1"`, and date condition values accept `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`. + +A supplied root `condition` must be an object with a `conditions` array. Malformed nodes, empty nested groups, and condition trees that exceed the depth or node limits are rejected. + +Updates that activate a rule or keep it active also validate its existing conditions. If a referenced category, attribute set, or option has been removed, correct the condition before activating or updating the rule. + +Retrieving, updating, or deleting a nonexistent rule returns HTTP `404`. + +## Storefront price updates + +Only active rules within their schedule affect storefront prices for the specified websites and customer groups. + +Price updates are asynchronous. A successful create, update, or delete response confirms the rule operation, not that storefront prices have already changed. Allow time for the price update to complete before checking prices through Catalog Service GraphQL, using the applicable customer group context. diff --git a/src/pages/rest/saas-integrations/index.md b/src/pages/rest/saas-integrations/index.md index 5e6151745..549531f72 100644 --- a/src/pages/rest/saas-integrations/index.md +++ b/src/pages/rest/saas-integrations/index.md @@ -9,6 +9,7 @@ keywords: Review the following topics to learn more about REST APIs available only on Adobe Commerce as a Cloud Service: +- [Catalog price rules](catalog-price-rules/index.md) - [Custom email](custom-email/index.md) - [Gift card accounts](gift-card-accounts/index.md) - [Login as Customer](login-as-customer/index.md) From f320232926a921c84f4c21e31a2d066f7fcb43c6 Mon Sep 17 00:00:00 2001 From: Sangmi Lee Date: Thu, 1 Oct 2026 12:13:07 +0200 Subject: [PATCH 2/5] docs: clarify catalog rule create and update requirements --- .../saas-integrations/catalog-price-rules/index.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/pages/rest/saas-integrations/catalog-price-rules/index.md b/src/pages/rest/saas-integrations/catalog-price-rules/index.md index ce8344608..56be9db87 100644 --- a/src/pages/rest/saas-integrations/catalog-price-rules/index.md +++ b/src/pages/rest/saas-integrations/catalog-price-rules/index.md @@ -29,7 +29,7 @@ Content-Type: application/json Store: all ``` -Do not include `/rest` or a store view code in the URL. The `Store` header specifies the request scope, while the rule's `website_ids` specifies the websites where the discount applies. Include `website_ids` in the rule payload. +Do not include `/rest` or a store view code in the URL. The `Store` header specifies the request scope, while the rule's `website_ids` specifies the websites where the discount applies. Include `website_ids` when creating a rule. On update, omit it or send `null` to preserve the existing websites. ## REST API reference @@ -92,17 +92,17 @@ Use option values, not option labels, in conditions for select and multiselect a ## Rule fields -Create and update requests wrap the rule fields in a `rule` object. The following requirements and defaults apply when creating a rule. Updates preserve omitted or null fields. +Create and update requests wrap the rule fields in a `rule` object. Defaults apply when creating a rule. On update, omitted or null fields preserve their existing values. | Field | Type | Description | | --- | --- | --- | | `rule_id` | Integer | The generated rule ID returned by the API. For updates, use the ID in the URL. | -| `name` | String | Required. Must not be blank. | +| `name` | String | Required on create; optional on update. Must not be blank. | | `description` | String | Optional rule description. | -| `website_ids` | Integer array | Required. A nonempty list of existing storefront website IDs. Website ID `0` is not supported. | -| `customer_group_ids` | Integer array | Required. A nonempty list of existing customer group IDs. | -| `simple_action` | String | Required. One of the four supported discount actions. | -| `discount_amount` | Number | Required. Must be nonnegative. Percentage actions accept values from 0 to 100. | +| `website_ids` | Integer array | Required on create; optional on update. A nonempty list of existing storefront website IDs. Website ID `0` is not supported. | +| `customer_group_ids` | Integer array | Required on create; optional on update. A nonempty list of existing customer group IDs. | +| `simple_action` | String | Required on create; optional on update. One of the four supported discount actions. | +| `discount_amount` | Number | Required on create; optional on update. Must be nonnegative. Percentage actions accept values from 0 to 100. | | `is_active` | Integer | `0` for inactive or `1` for active. Defaults to `0`. | | `stop_rules_processing` | Integer | `1` prevents subsequent rules from applying to matching products. `0` allows further rule processing. Defaults to `1`. | | `sort_order` | Integer | Nonnegative rule priority. Lower values have higher priority. Defaults to `0`. | From bee9d3c41b436ef2b1c13d7de53f709fc59c4f7b Mon Sep 17 00:00:00 2001 From: Sangmi Lee Date: Thu, 1 Oct 2026 12:50:19 +0200 Subject: [PATCH 3/5] docs: simplify catalog price rule guide --- .../catalog-price-rules/index.md | 94 ++++++------------- 1 file changed, 30 insertions(+), 64 deletions(-) diff --git a/src/pages/rest/saas-integrations/catalog-price-rules/index.md b/src/pages/rest/saas-integrations/catalog-price-rules/index.md index 56be9db87..f4e01c2eb 100644 --- a/src/pages/rest/saas-integrations/catalog-price-rules/index.md +++ b/src/pages/rest/saas-integrations/catalog-price-rules/index.md @@ -10,31 +10,18 @@ keywords: # Catalog price rule API -The catalog price rule REST API lets integrations manage product discounts without creating or editing each rule in the Admin. Use the API to discover supported conditions, create rules, and manage existing rules with the same nested condition logic available in the Admin. - -Catalog price rules apply to products for the specified websites and customer groups. For cart price rules, which apply discounts during checkout, use the [salesRules API](https://adobe-commerce-saas.redoc.ly/tag/salesRules/). The two APIs use different condition payloads. +Use these REST endpoints to create, retrieve, update, delete, and search catalog price rules in Adobe Commerce as a Cloud Service. Rules apply product discounts to the specified websites and customer groups and support nested conditions. ## Authentication and scope Authenticate each request with an Adobe Identity Management Service (IMS) access token. The associated Admin role must include the `Magento_CatalogRule::promo_catalog` Access Control List (ACL) resource. Customer and guest access is not supported. -See [REST authentication](../../authentication/index.md) for user and server-to-server authentication. - -Use the Adobe Commerce as a Cloud Service URL structure: - -```http -GET https://.api.commerce.adobe.com//V1/catalogPriceRules/metadata -Authorization: Bearer -Content-Type: application/json -Store: all -``` +See [REST authentication](../../authentication/index.md) for user and server-to-server authentication, and [REST API overview](../../index.md) for the SaaS URL format. -Do not include `/rest` or a store view code in the URL. The `Store` header specifies the request scope, while the rule's `website_ids` specifies the websites where the discount applies. Include `website_ids` when creating a rule. On update, omit it or send `null` to preserve the existing websites. +The `Store` header specifies the request scope. The rule's `website_ids` specifies the websites where the discount applies. Include `website_ids` when creating a rule. On update, omit it or send `null` to preserve the existing websites. ## REST API reference -All six endpoints require the `Magento_CatalogRule::promo_catalog` ACL resource. - | Method | Endpoint | Description | | --- | --- | --- | | `GET` | `/V1/catalogPriceRules/metadata` | Discover discount actions and attributes available for conditions. | @@ -44,7 +31,7 @@ All six endpoints require the `Magento_CatalogRule::promo_catalog` ACL resource. | `PUT` | `/V1/catalogPriceRules/{ruleId}` | Update a rule. | | `DELETE` | `/V1/catalogPriceRules/{ruleId}` | Delete a rule. | -## Discover available conditions +### Discover available conditions Before creating a rule, retrieve the metadata: @@ -52,7 +39,7 @@ Before creating a rule, retrieve the metadata: GET /V1/catalogPriceRules/metadata ``` -The response contains `simple_actions`, the supported discount actions, and `condition_attributes`, the attributes that can be used in rule conditions. Each attribute includes its `attribute_code`, `label`, `input_type`, supported `operators`, and a `value_source` endpoint when values must be retrieved separately. +The response lists supported discount actions and condition attributes, including their operators and value-source endpoints. The following response excerpt shows the category condition: @@ -76,7 +63,7 @@ The following response excerpt shows the category condition: } ``` -The available product attributes depend on the instance's attribute configuration. Use the returned metadata instead of assuming that an attribute or operator is supported. +Available attributes depend on your instance's configuration. Use the attributes and operators returned by the metadata endpoint. Retrieve the IDs needed for rule scope and condition values using the following endpoints. These endpoints have their own permission requirements. @@ -90,7 +77,7 @@ Retrieve the IDs needed for rule scope and condition values using the following Use option values, not option labels, in conditions for select and multiselect attributes. -## Rule fields +### Rule fields Create and update requests wrap the rule fields in a `rule` object. Defaults apply when creating a rule. On update, omitted or null fields preserve their existing values. @@ -110,7 +97,7 @@ Create and update requests wrap the rule fields in a `rule` object. Defaults app | `to_date` | String | Optional end date or UTC datetime. Must not precede `from_date`. | | `condition` | Object | Optional root condition group containing leaf conditions or nested groups. Omitting it on create targets all products within the rule's website and customer group scope. | -### Discount actions +#### Discount actions The `simple_action` determines how `discount_amount` changes the price: @@ -121,7 +108,7 @@ The `simple_action` determines how `discount_amount` changes the price: | `to_percent` | Set the price to the specified percentage. | An amount of `20` produces a price of 20. | | `to_fixed` | Set the price to the specified fixed amount. | An amount of `20` produces a price of 20. | -### Schedule dates +#### Schedule dates Both `from_date` and `to_date` accept: @@ -130,7 +117,7 @@ Both `from_date` and `to_date` accept: 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. -## Create a rule +### 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`. Replace these IDs with existing values from your instance. @@ -144,7 +131,6 @@ Request body: { "rule": { "name": "Category discount", - "description": "Ten percent off products in the selected category.", "website_ids": [1], "customer_group_ids": [1], "simple_action": "by_percent", @@ -164,37 +150,26 @@ Request body: } ``` -The response returns the saved rule object, including its generated `rule_id` and default values: +The response returns the saved rule object. This excerpt shows the generated ID and default values: ```json { "rule_id": 42, "name": "Category discount", - "description": "Ten percent off products in the selected category.", "is_active": 0, - "website_ids": [1], - "customer_group_ids": [1], - "simple_action": "by_percent", "discount_amount": 10, "stop_rules_processing": 1, - "sort_order": 0, - "condition": { - "aggregator": "all", - "match": true, - "conditions": [ - { - "attribute_code": "category_ids", - "operator": "==", - "value": "12" - } - ] - } + "sort_order": 0 } ``` Review the saved rule before activating it with `is_active: 1`. You can also set `is_active` explicitly when creating a rule. -## Build nested conditions + + +Rule changes may take time to appear in storefront prices. + +### Build nested conditions The `condition` object is a root group. Each group has a `conditions` array containing leaf conditions, nested groups, or both. @@ -249,7 +224,9 @@ Condition trees support up to 10 levels and 100 total nodes, including the root 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. -## Retrieve and update a rule +Boolean condition values use `"0"` or `"1"`. Date condition values accept `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`. + +### Retrieve and update a rule Retrieve a rule by its ID: @@ -278,6 +255,8 @@ Request body: 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: ```json @@ -294,17 +273,15 @@ If you provide `condition`, it replaces the entire condition tree. Omitting `con 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 +### Search rules -Use `/V1/catalogPriceRules/search`, not the collection URL, to list and filter rules. The following request finds active rules, sorts them by ID, and returns the first page of 20 results: +Use `/V1/catalogPriceRules/search` to list and filter rules. The following request returns the first page of 20 active rules: ```text 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[sortOrders][0][field]=rule_id - &searchCriteria[sortOrders][0][direction]=ASC &searchCriteria[pageSize]=20 &searchCriteria[currentPage]=1 ``` @@ -321,7 +298,7 @@ Increase `searchCriteria[currentPage]` to retrieve subsequent pages. An omitted See [Search using REST endpoints](../../use-rest/performing-searches.md) for filter groups, comparison operators, sorting, and pagination. -## Delete a rule +### Delete a rule ```http DELETE /V1/catalogPriceRules/42 @@ -333,20 +310,9 @@ The response confirms deletion: true ``` -## Validation - -Invalid rule input returns HTTP `400`. Validation checks required fields, discount actions and amounts, flags, schedule dates, and the existence of referenced websites and customer groups. - -Conditions are checked against the metadata's allowed attributes and operators. Referenced categories, product attribute sets, and option values must be valid. Boolean condition values use `"0"` or `"1"`, and date condition values accept `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`. - -A supplied root `condition` must be an object with a `conditions` array. Malformed nodes, empty nested groups, and condition trees that exceed the depth or node limits are rejected. - -Updates that activate a rule or keep it active also validate its existing conditions. If a referenced category, attribute set, or option has been removed, correct the condition before activating or updating the rule. +## Error handling -Retrieving, updating, or deleting a nonexistent rule returns HTTP `404`. - -## Storefront price updates - -Only active rules within their schedule affect storefront prices for the specified websites and customer groups. - -Price updates are asynchronous. A successful create, update, or delete response confirms the rule operation, not that storefront prices have already changed. Allow time for the price update to complete before checking prices through Catalog Service GraphQL, using the applicable customer group context. +| Status code | Condition | +| --- | --- | +| `400` | Invalid rule input, including malformed conditions or invalid references. | +| `404` | The requested rule does not exist. | From 61f236dc95cdd93de81d9e76deeeb2464a25c79d Mon Sep 17 00:00:00 2001 From: Sangmi Lee Date: Thu, 1 Oct 2026 14:43:46 +0200 Subject: [PATCH 4/5] docs: shorten authentication and website scope guidance --- .../rest/saas-integrations/catalog-price-rules/index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/pages/rest/saas-integrations/catalog-price-rules/index.md b/src/pages/rest/saas-integrations/catalog-price-rules/index.md index f4e01c2eb..f5ba79e93 100644 --- a/src/pages/rest/saas-integrations/catalog-price-rules/index.md +++ b/src/pages/rest/saas-integrations/catalog-price-rules/index.md @@ -12,13 +12,13 @@ keywords: Use these REST endpoints to create, retrieve, update, delete, and search catalog price rules in Adobe Commerce as a Cloud Service. Rules apply product discounts to the specified websites and customer groups and support nested conditions. -## Authentication and scope +## Authentication -Authenticate each request with an Adobe Identity Management Service (IMS) access token. The associated Admin role must include the `Magento_CatalogRule::promo_catalog` Access Control List (ACL) resource. Customer and guest access is not supported. +These endpoints require an [IMS access token](../../authentication/index.md). Your Admin role must include `Magento_CatalogRule::promo_catalog`. -See [REST authentication](../../authentication/index.md) for user and server-to-server authentication, and [REST API overview](../../index.md) for the SaaS URL format. +## Website scope -The `Store` header specifies the request scope. The rule's `website_ids` specifies the websites where the discount applies. Include `website_ids` when creating a rule. On update, omit it or send `null` to preserve the existing websites. +Set the rule's target websites with `website_ids`. The `Store` header controls the REST request scope. See the [REST API overview](../../index.md) for URL and header details. ## REST API reference From 9fff4010f9df3ae9c81edd5f88774a64c85d15b6 Mon Sep 17 00:00:00 2001 From: Sangmi Lee Date: Fri, 2 Oct 2026 17:42:23 +0200 Subject: [PATCH 5/5] docs: apply feedback --- .../catalog-price-rules/index.md | 230 +++++++++--------- 1 file changed, 109 insertions(+), 121 deletions(-) diff --git a/src/pages/rest/saas-integrations/catalog-price-rules/index.md b/src/pages/rest/saas-integrations/catalog-price-rules/index.md index f5ba79e93..4eb040695 100644 --- a/src/pages/rest/saas-integrations/catalog-price-rules/index.md +++ b/src/pages/rest/saas-integrations/catalog-price-rules/index.md @@ -1,5 +1,5 @@ --- -title: Catalog Price Rule REST Endpoints +title: Catalog Price Rules description: Learn how to create, retrieve, update, delete, and search catalog price rules with REST APIs in Adobe Commerce as a Cloud Service. keywords: - REST @@ -8,13 +8,13 @@ keywords: -# Catalog price rule API +# Catalog price rules -Use these REST endpoints to create, retrieve, update, delete, and search catalog price rules in Adobe Commerce as a Cloud Service. Rules apply product discounts to the specified websites and customer groups and support nested conditions. +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](../../authentication/index.md). Your Admin role must include `Magento_CatalogRule::promo_catalog`. +These endpoints require an [IMS access token](../../authentication/index.md). To access them, you must have the `Magento_CatalogRule::promo_catalog` permission. ## Website scope @@ -31,55 +31,9 @@ Set the rule's target websites with `website_ids`. The `Store` header controls t | `PUT` | `/V1/catalogPriceRules/{ruleId}` | Update a rule. | | `DELETE` | `/V1/catalogPriceRules/{ruleId}` | Delete a rule. | -### Discover available conditions +## Rule fields -Before creating a rule, retrieve the metadata: - -```http -GET /V1/catalogPriceRules/metadata -``` - -The response lists supported discount actions and condition attributes, including their operators and value-source endpoints. - -The following response excerpt shows the category condition: - -```json -{ - "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. - -Retrieve the IDs needed for rule scope and condition values using the following endpoints. These endpoints have their own permission requirements. - -| Values | Endpoint | -| --- | --- | -| Website IDs | `GET /V1/store/websites` | -| Customer group IDs | `GET /V1/customerGroups/search` | -| Category IDs | `GET /V1/categories` | -| Product attribute set IDs | `GET /V1/products/attribute-sets/sets/list` | -| Attribute option values | `GET /V1/products/attributes/{attributeCode}/options` | - -Use option values, not option labels, in conditions for select and multiselect attributes. - -### Rule fields - -Create and update requests wrap the rule fields in a `rule` object. Defaults apply when creating a rule. On update, omitted or null fields preserve their existing values. +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. | Field | Type | Description | | --- | --- | --- | @@ -88,16 +42,16 @@ Create and update requests wrap the rule fields in a `rule` object. Defaults app | `description` | String | Optional rule description. | | `website_ids` | Integer array | Required on create; optional on update. A nonempty list of existing storefront website IDs. Website ID `0` is not supported. | | `customer_group_ids` | Integer array | Required on create; optional on update. A nonempty list of existing customer group IDs. | -| `simple_action` | String | Required on create; optional on update. One of the four supported discount actions. | -| `discount_amount` | Number | Required on create; optional on update. Must be nonnegative. Percentage actions accept values from 0 to 100. | +| `simple_action` | String | Required on create; optional on update. One of the four supported [discount actions](#discount-actions). | +| `discount_amount` | Number | Required on create; optional on update. Percentage actions accept values from 0 to 100. Fixed-amount actions accept values of 0 or greater. | | `is_active` | Integer | `0` for inactive or `1` for active. Defaults to `0`. | | `stop_rules_processing` | Integer | `1` prevents subsequent rules from applying to matching products. `0` allows further rule processing. Defaults to `1`. | | `sort_order` | Integer | Nonnegative rule priority. Lower values have higher priority. Defaults to `0`. | -| `from_date` | String | Optional start date or UTC datetime. | -| `to_date` | String | Optional end date or UTC datetime. Must not precede `from_date`. | -| `condition` | Object | Optional root condition group containing leaf conditions or nested groups. Omitting it on create targets all products within the rule's website and customer group scope. | +| `from_date` | String | Optional start date or UTC datetime. See [Schedule dates](#schedule-dates). | +| `to_date` | String | Optional end date or UTC datetime. Must not precede `from_date`. See [Schedule dates](#schedule-dates). | +| `condition` | Object | Optional root condition group containing leaf conditions or nested groups. Omitting it on create targets all products within the rule's website and customer group scope. See [Conditions](#conditions). | -#### Discount actions +### Discount actions The `simple_action` determines how `discount_amount` changes the price: @@ -108,7 +62,7 @@ The `simple_action` determines how `discount_amount` changes the price: | `to_percent` | Set the price to the specified percentage. | An amount of `20` produces a price of 20. | | `to_fixed` | Set the price to the specified fixed amount. | An amount of `20` produces a price of 20. | -#### Schedule dates +### Schedule dates Both `from_date` and `to_date` accept: @@ -117,71 +71,105 @@ Both `from_date` and `to_date` accept: 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. -### Create a rule +### Conditions -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`. Replace these IDs with existing values from your instance. +The `condition` object is a root group. Each group has a `conditions` array containing leaf conditions, nested groups, or both. -```http -POST /V1/catalogPriceRules -``` +- `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. -Request body: +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. ```json { - "rule": { - "name": "Category discount", - "website_ids": [1], - "customer_group_ids": [1], - "simple_action": "by_percent", - "discount_amount": 10, - "condition": { - "aggregator": "all", + "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" } ] } - } + ] } ``` -The response returns the saved rule object. This excerpt shows the generated ID and default values: +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](#condition-attributes). 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. + +```http +GET /V1/catalogPriceRules/metadata +``` + +The following response is shortened to show only the category condition: ```json { - "rule_id": 42, - "name": "Category discount", - "is_active": 0, - "discount_amount": 10, - "stop_rules_processing": 1, - "sort_order": 0 + "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" + } + ] } ``` -Review the saved rule before activating it with `is_active: 1`. You can also set `is_active` explicitly when creating a rule. +Available attributes depend on your instance's configuration. Use the attributes and operators returned by the metadata endpoint. - +### Lookup values -Rule changes may take time to appear in storefront prices. +Retrieve the IDs needed for rule scope and condition values using the following endpoints. Each endpoint requires the permission shown next to it. -### Build nested conditions +- 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`. -The `condition` object is a root group. Each group has a `conditions` array containing leaf conditions, nested groups, or both. +Use option values, not option labels, in conditions for select and multiselect attributes. -- `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 all or any 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. +## Manage rules + +### Create a rule -The following update targets products in attribute set `4` that belong to either category `12` or category `13`. Replace these IDs with valid values from your instance. +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`. ```http -PUT /V1/catalogPriceRules/42 +POST /V1/catalogPriceRules ``` Request body: @@ -189,30 +177,19 @@ Request body: ```json { "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": "attribute_set_id", + "attribute_code": "category_ids", "operator": "==", - "value": "4" - }, - { - "aggregator": "any", - "match": true, - "conditions": [ - { - "attribute_code": "category_ids", - "operator": "==", - "value": "12" - }, - { - "attribute_code": "category_ids", - "operator": "==", - "value": "13" - } - ] + "value": "12" } ] } @@ -220,15 +197,26 @@ Request body: } ``` -Condition trees support up to 10 levels and 100 total nodes, including the root group. Nested groups must contain at least one child. +The response returns the saved rule object. The following response is shortened to show the generated ID and default values: + +```json +{ + "rule_id": 42, + "name": "Category discount", + "is_active": 0, + "discount_amount": 10, + "stop_rules_processing": 1, + "sort_order": 0 +} +``` -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. +Review the saved rule before activating it with `is_active: 1`. -Boolean condition values use `"0"` or `"1"`. Date condition values accept `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`. + -### Retrieve and update a rule +Rule changes may take time to affect storefront prices. -Retrieve a rule by its ID: +### Retrieve a rule ```http GET /V1/catalogPriceRules/42 @@ -236,6 +224,8 @@ 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: ```http @@ -290,13 +280,11 @@ The query parameters are shown on separate lines for readability. Send them as o 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. - -Increase `searchCriteria[currentPage]` to retrieve subsequent pages. An omitted or zero page size defaults to 200. Values above 500 are capped at 500. Negative page sizes and current pages below 1 are rejected. +- `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](../../use-rest/performing-searches.md) for filter groups, comparison operators, sorting, and pagination. +See [Search using REST endpoints](../../use-rest/performing-searches.md) for filter groups, comparison operators, sorting, and pagination. This endpoint returns 200 rules per page by default and at most 500. ### Delete a rule