openapi: 3.1.0 info: title: Rule Promotions API description: | Rule Promotions provide the flexibility to offer diverse discounts to shoppers. This functionality supports discounts of varying complexities, from code-based customer discounts, to "Buy X Get Y" scenarios, fixed price promotions, and more based on your business needs. You can create a Rule Promotion using the Rule Promotions API or through the Promotions Builder in Commerce Manager. To apply Rule Promotions in carts and orders across an entire store, please enable the `use_rule_promotions` configuration in Cart Settings. You can also update a specific cart to use Rule Promotions by updating the cart's specific discount settings. Please see [Update A Cart](/docs/api/carts/update-a-cart) for more details. Enabling Rule Promotions enacts Hybrid Mode, allowing simultaneous use of both Promotions Standard and Rule Promotions discounts. For example, let's say a store provides the following promotions: - A Promotions Standard discount for 10% off the shopping cart - A Rule Promotion offering for a 20% discount on the shopping cart If a cart qualifies for both discounts based on the respective eligibility criteria, the system applies both types of discounts to the shopping cart, starting with Promotions Standard definitions before applying Rule Promotions. In this case, the application results in a 10% discount from the Promotions Standard definition and a 20% discount from the Rule Promotion. ### Rule Set A rule set is the criteria that determine when and how promotions get applied. Rule Sets consist of rule conditions and corresponding actions, which define eligibility and application details, respectively. Rule Sets may also contain targeted catalogs and currencies for further application granularity. **Example** Buy an apple, get an orange 50% off. Here, buying an apple is the rule and the 50% discount on an orange is the action. #### Rules Rules describe the conditions necessary for promotion eligibility. In our apple-orange example above, the rule indicates the shopper must buy an apple to get the discount on an orange. In other words, the buying of an apple is the condition which determines eligibility for the corresponding discount. **Condition Architecture:** All conditions follow a consistent structure with three primary components: - **`strategy`**: Defines the type of condition (e.g., `cart_total`, `item_category`) - **`operator`**: Specifies how the condition is evaluated (e.g., `gte`, `in`, `contains_all`) - **`args`**: Contains the values to evaluate against Some conditions support additional components for complex scenarios: - **`children`**: Sub-conditions that provide additional specificity - **`condition`**: Used in actions to define item-specific restrictions **Condition Categories:** - **Cart-level**: Evaluate entire cart properties (total, custom attributes) - **Account-level**: Consider customer account characteristics (tags, segments) - **Item-level**: Target specific products, categories, or attributes - **Bundle conditions**: Complex multi-item requirements for "Buy X, Get Y" scenarios - **Logical operators**: AND/OR logic for sophisticated eligibility rules **Key Design Considerations:** - **Performance**: Order conditions from most to least restrictive for optimal evaluation - **Maintainability**: Use `item_identifier` instead of legacy `item_sku`/`item_product_id` strategies - **Complexity**: Limit nesting depth and consider evaluation costs for complex bundle conditions - **Business Logic**: Ensure condition combinations align with promotion goals and margin requirements #### Actions Actions describe how discounts apply to eligible carts and orders. These signify the discount type, level, configurations, and any limitations or restrictions when applying. Actions can also include: - Action conditions: specify which items should be included or excluded when applying the discounts. These can be based on factors such as item SKUs, product attributes, quantities, or categories. - Action limitations: impose restrictions on the number of products eligible for discounts, maximum discount amounts, and/or total applications for discounts. In the apple-orange example, the action denotes the system applies a 50% discount to an orange, assuming the eligibility rules are met. For more complex scenarios, the action might say to provide a 50% discount on up to three oranges or might provide a fixed $1 discount on the two most expensive items from the "fruit" category. :::note For promotions that include a mix of item and cart rules or actions, we recommend including the specific item conditions in all item strategies to ensure desired discount applications. For complex promotions in general, we recommend including specific item conditions on all item strategies to ensure the appropriate items receive discounts. Please see the [Create a Rule Promotion API Request Examples](/docs/api/promotions-builder/create-rule-promotion) for more details on specifying conditions, restrictions, and inclusions. ::: #### Action Limitations Action limitations define constraints or rules that govern how a promotion's action is applied. While actions specify what discount is given (e.g., 10% off the cart), limitations control how much, to which items, and under what circumstances that action is applied. Limitations include: - **`max_discount`**: Caps the total value of the discount. - **`max_quantity`**: Limits the number of discounted units per item. - **`items`**: Restricts how many and which items are eligible, and in what order (e.g., max_items, price_strategy). - **`max_items`**: Specifies the maximum number of items eligible for the discount. - **`price_strategy`**: Determines how eligible items are selected based on price: - **Cheapest (default)**: The discount is applied to the cheapest item(s) in the cart. - **Expensive**: The discount applies to the most expensive item(s) in the cart. Some limitations, like auto_add, influence the application behavior of the action rather than its scope. - **`auto_add`**: Automatically adds items to the cart once conditions are met, providing additional configuration for the promotion’s application mode. - **`show_suggestions`**: A flag indicating whether to show suggestions for eligible items in the cart if the item is not in the cart. In this way, limitations can affect either the scope of the discount or the manner in which it is applied, providing both technical and user-facing boundaries around a promotion’s behavior. For example, consider a **50% discount on items from a category**, with the following limitations: - **Applies to a maximum of two items (`max_items: 2`)** - **Only applies to the two cheapest eligible items (`price_strategy: cheapest`)** - **Limits the total discount to $10 (`max_discount: 1000`)** - **Ensures a maximum of two units per eligible item receive the discount (`max_quantity: 2`)** #### Catalogs and Currencies As part of the Rule Set, you can also specify the catalogs and currencies for a given Rule Promotion. With catalogs defined, the promotion only considers items from the identified catalogs and therefore will not consider custom items or items from other catalogs. With no catalogs defined, the promotion considers all items, including custom items. Specifying a currency for a Rule Promotion restricts it to carts using that currency. Rule Promotions support multiple currencies when using a percent discount. If no currencies are defined, the discount applies to carts in any currency. ### Building Blocks #### Strategies Strategies describe the types of condition criteria or application actions used to build a promotion. A given promotion can be comprised of several strategies in its rules and actions. These might include several instances of similar strategies, different strategies, or some combination thereof. Think of these as building blocks that can be applied together to provide a functional discount. - Rule strategies define the types of conditions that need to be met for eligibility. These might include cart total amount, item prices, cart custom attributes, and more. - Action strategies refer to the type of action execution run when the eligibility criteria are met. For actions, the possible strategies are `cart_discount`, `item_discount`, `item_bundle_discount` and `shipping_discount`. For more information, please see [Promotions Builder API Overview](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview). #### Operators and Args Operators determine how to evaluate a given strategy, while `args` define the value threshold to measure against. For example, please consider the following condition strategy: ``` { "strategy": "cart_total", "operator": "gte", "args": [ 10000 ] } ``` In this example, the strategy is `cart_total`, telling the system to assess eligibility based on the total cart value. The operator is a greater-than-or-equal-to (`gte`) evaluation, indicating the candidate value (in this case, cart total) becomes eligible once it reaches or exceeds the threshold. Finally, the `args` value provides the threshold value to compare against, 10000. Taken together, then, this strategy looks for cart totals greater than or equal to 10000. ::: note Different strategies support different operators. For more information, please see [Rule Promotions API Overview](/docs/promotions-builder/promotions-builder-api/promotions-builder-api-overview). ::: #### Children and Sub-Conditions For additional promotion granularity, some strategies support additional specifications via `children` and `condition` fields. These fields contain strategies, which provide further specifications around their parent strategy evaluations. In other words, sub-conditions refer to additional criteria or conditions that must be met for a particular promotion to be applied. The following strategies support children/sub-conditions: - `item_price` - `item_quantity` - `item_category` - `item_attribute` - `and` - `or` Notably, when multiple sub-condition siblings exist, they are combined together, such that all sub-conditions must be met to fulfill eligibility. ### Stacking Promotion stacking and priority are key elements in managing discounts, ensuring promotions are applied as intended. Stacking allows multiple promotions to be applied to a single cart, either targeting the same items or different ones. The `stackable` flag determines whether a promotion can stack with others, defaulting to `true`. If set to `false`, no other promotion can stack on top, and the highest-priority promotion takes precedence. Priority settings dictate the order in which promotions are applied, with higher numbers indicating higher priorities. By default, promotions without assigned priorities are applied in reverse order of creation, with newer promotions applied first and calculated against any existing discounted prices. Hybrid Mode enables the coexistence of Standard Promotions and those configured in the Promotions Builder, with each functioning independently. This means Standard Promotions can stack alongside non-stackable Builder promotions, and their stackability and priority settings remain unaffected by Standard Promotions. Override stacking, set using the `override_stacking` flag, provides an additional layer of control over how promotions interact. This flag determines whether the promotion can stack with other promotions that are typically non-stackable and defaults to `false` when not set. When set to `true`, the promotion can stack with promotions configured as non-stackable, unless those non-stackable promotions also override stacking. ### Shipping Rule Promotions support shipping discounts, identified by the corresponding strategies during promotion creation. Shipping discounts apply to shipping group base prices and do not impact shipping taxes or configured shipping fees. Please see [Shipping Groups](/docs/ship-groups/shipping-groups/index) for more information on creating and interacting with shipping groups. ### Items Bundle You can promote and discount groups of items together using the `items_bundle` rule strategy and the `items_bundle_discount` action strategy. When these strategies are applied, the cart must contain items that meet all specified criteria to qualify for the discount. - The `items_bundle` rule strategy defines the required group of items for discount eligibility. - The `items_bundle_discount` action strategy specifies how the discount is applied to the qualifying group. - The `items_bundle` strategy requires **at least one** requirement that defines which items are eligible. Bundle items can be mixed across categories or attributes to form a valid bundle. - The `item_quantity` can be used with any of the bundling strategies, including `item_category`, `item_identifier`, `item_attribute`, etc. - `item_quantity` only support `eq` operator when configuring `items_bundle` strategy. - For instance, targeting a category with `item_quantity` with operator `eq` 2 means any two items from that category can form a bundle. The system will prioritize individual line items with sufficient quantity first before combining quantities of separate line items. ``` { "strategy": "items_bundle", "children": [ { "strategy": "and", "children": [ { "strategy": "item_category", "operator": "in", "args": [ "667d9fae-d8c7-4941-b556-70cb4b8612f1" ] }, { "strategy": "item_quantity", "operator": "gte", "args": [ 2 ] } ] } ] } ``` - When using `item_quantity` to target specific items or categories, the required quantity can be fulfilled by a combination of eligible items. - For example, if the rule is `item_quantity` with operator `eq` 3 for products in the "Office Supplies" category, the discount will apply when the cart includes any of the following combinations: - 2 packs of printer paper + 1 box of pens - 1 stapler + 2 notepad - 1 box of pens + 1 notepad + 1 pack of printer paper - 3 identical items, such as 3 boxes of pens - **Please Note**: the system considers line items sequentially based on their quantities, using the order of addition to the cart as a fallback tie-breaker. If the first eligible item has sufficient quantity to fulfill the bundle criteria, it will consume the required quantity and complete the evaluation for that criteria. The system does not re-evaluate these processed items to share any remaining quantities with other items. This behaviour may result in differing total discount amounts for two shopping carts with the same items added in a different order if those items have the same quantity values. Available discount types: - `fixed_price` – Sets a fixed total price for the group (e.g., If the fixed price is set at $100, then the group's subtotal is exactly $100) - `percent` – Applies a percentage-based discount to the group. - `fixed` – Deducts a fixed amount from the group's total price. version: 26.0226.7253317 x-version-timestamp: 2026-02-26T20:26:06Z contact: name: Elastic Path url: https://elasticpath.com license: name: MIT url: assets/LICENSE servers: - url: https://useast.api.elasticpath.com description: US East Production Server variables: {} - url: https://euwest.api.elasticpath.com description: EU West Production Server variables: {} paths: /v2/rule-promotions: post: tags: - Rule Promotions summary: Create a Rule Promotion description: | Creates a new rule-based promotion, allowing flexible discount strategies based on cart or item conditions. Promotions can apply fixed or percentage-based discounts, apply automatically or via codes, and have eligibility rules based on product attributes, cart total, SKU conditions, custom attributes, and more. This endpoint supports a variety of promotion types, such as: - **Cart-wide discounts** - **Item-specific discounts** - **Shipping discounts** - **Combinations thereof** :::note The minimum item discount amount is zero, both for amounts and percentages. A store can have a maximum of **50 active and future automatic rule promotions**. ::: operationId: createRulePromotion security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/Authorization' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RulePromotionItem' examples: CartPercentDiscount: summary: Create a Cart Percent Discount Promotion based on cart total value value: data: type: rule_promotion name: Cart 20% discount when total is at least $100 description: 20% discount applying to the cart total enabled: false automatic: false start: '2024-01-01' end: '2025-01-01' rule_set: rules: strategy: cart_total operator: gte args: - 10000 actions: - strategy: cart_discount args: - percent - 20 BXGYPromotion: summary: Create a BXGY Promotion. Buy an item and get the other item with discount. value: data: type: rule_promotion name: Buy X get Y 50% description: Buy item SKU-X Get item SKU-Y 50% off. enabled: true automatic: true start: '2024-02-01' end: '2024-02-27' rule_set: rules: strategy: item_sku operator: in args: - SKU-X actions: - strategy: item_discount args: - percent - 50 condition: - strategy: item_sku operator: in args: - SKU-Y ItemPercentWithProductAttribute: summary: Create an Item Percent Discount with Product Attribute value: data: type: rule_promotion name: 20% off items with attribute brand EP description: All items with attribute brand EP get 20% discount. enabled: true automatic: true start: '2024-02-01' end: '2050-01-01' rule_set: rules: strategy: item_attribute operator: in args: - products(product_template) - brand - string - EP actions: - strategy: item_discount args: - percent - 20 MixedCartAndItemDiscount: summary: Create a Mix of Cart and Item Percent Discount Promotions. Applying multiple discounts to the eligible cart. value: data: type: rule_promotion name: Buy sku1 and get cart 20% off and item sku1 50% description: Buy sku1 get cart 20% off plus item discount 50%. enabled: true automatic: true start: '2024-02-01' end: '2024-02-10' rule_set: rules: - strategy: item_sku operator: in args: - sku1 actions: - strategy: item_discount args: - percent - 50 condition: - strategy: item_sku operator: in args: - sku1 - strategy: cart_discount args: - percent - 20 FixedItemDiscount: summary: Create an Item Fixed Discount Promotion value: data: type: rule_promotion name: Buy item get $10 off description: Eligible item gets a fixed discount value of $10. enabled: true automatic: true start: '2024-02-10' end: '2024-02-22' rule_set: rules: strategy: item_sku operator: in args: - sku1 actions: - strategy: item_discount args: - fixed - 1000 FixedPriceItemDiscount: summary: Create an Item Fixed Price Discount Promotion. Item price is discounted at a fixed quantity and amount. value: data: type: rule_promotion name: Buy 2 items for $100 description: 2 sku1 for $100 enabled: true automatic: true start: '2024-02-01' end: '2050-01-01' rule_set: rules: strategy: item_sku operator: in args: - sku1 actions: - strategy: item_discount args: - fixed_price - 2 - 10000 FixedDiscountWithCatalogAndCurrencyConditions: summary: Create a Cart Fixed Discount Promotion for a Specified Catalog and Currencies. value: data: type: rule_promotion name: $5 off cart when cart is $100 or more description: Cart items from specific catalog with CAD or USD currency can get discount. enabled: true automatic: true start: '2023-12-01' end: '2024-01-01' rule_set: catalog_ids: - 09b9359f-897f-407f-89a2-702e167fe781 currencies: - CAD - USD rules: strategy: cart_total operator: gte args: - 10000 actions: - strategy: cart_discount args: - fixed - 500 CartCustomAttributePromotion: summary: Create a Cart Percent Discount for any cart with custom attribute can get discount. value: data: type: rule_promotion name: 50 percent off cart with custom attribute description: Cart with specific custom attribute can get discount. enabled: true automatic: true start: '2024-01-01' end: '2024-01-26' rule_set: rules: strategy: cart_custom_attribute operator: in args: - member_status - string - gold - platinum actions: - strategy: cart_discount args: - percent - 50 CartCustomAttributeEqualPromotion: summary: Create a Cart Discount for carts where a custom attribute equals a specific value. value: data: type: rule_promotion name: VIP customer discount description: 15 percent off for VIP customers enabled: true automatic: true start: '2025-01-01' end: '2030-12-31' rule_set: rules: strategy: cart_custom_attribute operator: eq args: - is_vip - boolean - true actions: - strategy: cart_discount args: - percent - 15 CartCustomAttributeGreaterThanPromotion: summary: Create a Cart Discount for carts where a custom attribute is greater than a value. value: data: type: rule_promotion name: Loyal customer reward description: $5 off for customers with more than 5 previous checkouts enabled: true automatic: true start: '2025-01-01' end: '2030-12-31' rule_set: rules: strategy: cart_custom_attribute operator: gt args: - checkout_count - integer - 5 actions: - strategy: cart_discount args: - fixed - 500 CartCustomAttributeLessThanOrEqualPromotion: summary: Create a Cart Discount for carts where a custom attribute is less than or equal to a value. value: data: type: rule_promotion name: New customer discount description: 20 percent off for customers with 3 or fewer checkouts enabled: true automatic: true start: '2025-01-01' end: '2030-12-31' rule_set: rules: strategy: cart_custom_attribute operator: lte args: - checkout_count - integer - 3 actions: - strategy: cart_discount args: - percent - 20 CartCustomAttributeFloatComparisonPromotion: summary: Create a Cart Discount for carts where a float custom attribute exceeds a threshold. value: data: type: rule_promotion name: High loyalty score bonus description: 25 percent off for customers with loyalty score above 75.5 enabled: true automatic: true start: '2025-01-01' end: '2030-12-31' rule_set: rules: strategy: cart_custom_attribute operator: gt args: - loyalty_score - float - 75.5 actions: - strategy: cart_discount args: - percent - 25 CartPercentDiscountExcludingItem: summary: Create a Cart Percent Discount Excluding Specific Item. value: data: type: rule_promotion name: 50 percent off cart excluding excluded item description: 50 percent off your order excluding excluded item enabled: true automatic: true start: '2024-02-01' end: '2050-01-01' rule_set: rules: strategy: cart_total operator: gte args: - 10000 children: - strategy: item_sku operator: nin args: - excludedItemSku actions: - strategy: cart_discount args: - percent - 50 condition: strategy: item_sku operator: nin args: - excludedItemSku ItemDiscountWithLimitations: summary: Create Item Discount Promotion with Max Quantity Limitation. value: data: type: rule_promotion name: Buy a shirt and get max of one hat for free description: Buy a shirt and get max of 1 hat free enabled: true automatic: true start: '2024-02-01' end: '2050-01-01' rule_set: rules: strategy: item_sku operator: in args: - shirt-sku actions: - strategy: item_discount args: - percent - 100 limitations: max_quantity: 1 condition: - strategy: item_sku operator: in args: - hat-sku ItemDiscountWithSkuOrId: summary: Create an Item Percent Discount targeting SKU or Product ID. value: data: type: rule_promotion name: Buy an item with SKU or Product ID get item 20% discount description: Buy sku1 or item with productID get 20% discount enabled: true automatic: false start: '2025-02-01' end: '2050-01-01' rule_set: rules: strategy: item_identifier operator: in args: - skus: - sku1 ids: - 44d8077f-8fa3-4780-9df5-91d052be583f actions: - strategy: item_discount args: - percent - 20 condition: strategy: item_identifier operator: in args: - skus: - sku1 ids: - 44d8077f-8fa3-4780-9df5-91d052be583f ItemDiscountExcludingSkuOrId: summary: Create an item discount excluding SKU or Product ID value: data: type: rule_promotion name: Get discount from category excluding sku or id description: Promotion excluding items with SKU or Product ID. enabled: true automatic: false start: '2025-02-01' end: '2050-01-01' rule_set: rules: strategy: item_category operator: in args: - 667d9fae-d8c7-4941-b556-70cb4b8612f1 children: - strategy: item_identifier operator: nin args: - skus: - nike_running1 ids: - 44d8077f-8fa3-4780-9df5-91d052be583f actions: - strategy: item_discount args: - percent - 50 condition: strategy: item_category operator: in args: - 667d9fae-d8c7-4941-b556-70cb4b8612f1 children: - strategy: item_identifier operator: nin args: - skus: - nike_running1 ids: - 44d8077f-8fa3-4780-9df5-91d052be583f ItemDiscountWithRuleAndActionSubConditions: summary: Create Item Promotion with category and attribute subconditions value: data: type: rule_promotion name: Items discount for a category excluding items with sale attribute description: 50% item discount excluding items with attribute when eligible items exceed $100. enabled: true automatic: true start: '2024-02-01' end: '2050-01-01' rule_set: rules: strategy: cart_total operator: gte args: - 10000 children: - strategy: item_category operator: in args: - category-id-1 - strategy: item_attribute operator: nin args: - products(product_template) - sales - string - sale2024 actions: - strategy: item_discount args: - percent - 50 condition: strategy: item_category operator: in args: - category-id-1 children: - strategy: item_attribute operator: nin args: - products(product_template) - sales - string - sale2024 CategoryItemDiscountWithLimitations: summary: Create Item Promotion targeting a category excluding some items from discount value: data: type: rule_promotion name: 50% max $10 max 2 items 2 quantities from category description: Items from category 50% off max $10 off 2 cheapest items with max quantity of 2 excluding one item. enabled: true automatic: true start: '2024-02-01' end: '2050-01-01' rule_set: rules: strategy: and children: - strategy: item_category operator: in args: - e3807d4d-010e-494c-8227-9a5cfd8f1177 - strategy: item_sku operator: nin args: - exclude_item_sku actions: - strategy: item_discount args: - percent - 50 limitations: max_quantity: 2 max_discount: 1000 items: max_items: 2 price_strategy: cheapest FreeShippingForCartOver100: summary: Create a Free Shipping Promotion value: data: type: rule_promotion name: Free FedEx Ground shipping when cart is $100 or more description: Free FedEx Ground shipping when cart is $100 or more. enabled: true automatic: false start: '2024-08-01' end: '2050-12-31' rule_set: rules: strategy: cart_total operator: gte args: - 10000 actions: - strategy: shipping_discount args: - percent - 100 condition: strategy: shipping_type operator: in args: - fedex_ground ItemsBundleDiscount: summary: Create a Bundle Promotion for specific item skus with specific quantity requirement value: data: type: rule_promotion name: Buy 2 tennis rackets and 3 tennis balls, get fixed price bundle discount description: Bundle items targeting specific item skus and quantity values. enabled: true automatic: false start: '2025-02-01' end: '2025-03-31' rule_set: rules: strategy: items_bundle children: - strategy: and children: - strategy: item_sku operator: in args: - tennis_racket - strategy: item_quantity operator: eq args: - 2 - strategy: and children: - strategy: item_sku operator: in args: - tennis_balls - strategy: item_quantity operator: eq args: - 3 actions: - strategy: items_bundle_discount args: - fixed_price - 20000 condition: strategy: items_bundle children: - strategy: and children: - strategy: item_sku operator: in args: - tennis_racket - strategy: item_quantity operator: eq args: - 2 - strategy: and children: - strategy: item_sku operator: in args: - tennis_balls - strategy: item_quantity operator: eq args: - 3 ItemsBundleWithSingleCondition: summary: Create a Bundle Promotion with single condition. Bundle items can be selected from a single category with a required minimum quantity. This can be either a single item meeting the quantity requirement or multiple items whose combined quantity satisfies the requirement. value: data: type: rule_promotion name: Buy any 2 or more items from shoes category, get 50% off description: Buy any 2 shoes get 50% off. enabled: true automatic: false start: '2025-05-01' end: '2025-05-31' rule_set: rules: strategy: items_bundle children: - strategy: and children: - strategy: item_category operator: in args: - 667d9fae-d8c7-4941-b556-70cb4b8612f1 - strategy: item_quantity operator: eq args: - 2 actions: - strategy: items_bundle_discount args: - percent - 50 condition: strategy: items_bundle children: - strategy: and children: - strategy: item_category operator: in args: - 667d9fae-d8c7-4941-b556-70cb4b8612f1 - strategy: item_quantity operator: eq args: - 2 BundleWithMixedItemsAcrossCategories: summary: Create a Bundle Promotion with mixed category and item quantity requirements. A bundle promotion that requires items from two categories, allowing the total quantity to be fulfilled by a mix of eligible items. value: data: type: rule_promotion name: Buy 2 items each from the "Shoes" and "Socks" categories to get a 50% bundle discount description: Buy 2 items from shoes and socks to get 50% bundle discount. enabled: true automatic: false start: '2025-05-01' end: '2025-05-31' rule_set: rules: strategy: items_bundle children: - strategy: and children: - strategy: item_category operator: in args: - 667d9fae-d8c7-4941-b556-70cb4b8612f1 - strategy: item_quantity operator: eq args: - 2 - strategy: and children: - strategy: item_category operator: in args: - 7700645a-55bd-4159-a8f3-ade7fed387c4 - strategy: item_quantity operator: eq args: - 2 actions: - strategy: items_bundle_discount args: - percent - 50 condition: strategy: items_bundle children: - strategy: and children: - strategy: item_category operator: in args: - 667d9fae-d8c7-4941-b556-70cb4b8612f1 - strategy: item_quantity operator: eq args: - 2 - strategy: and children: - strategy: item_category operator: in args: - 7700645a-55bd-4159-a8f3-ade7fed387c4 - strategy: item_quantity operator: eq args: - 2 AccountTagsPromotion: summary: Create a Cart Percent Discount with Account Tags Rule Promotion. Account must contain all account tags to be eligible for the discount. value: data: type: rule_promotion name: 50 percent off cart with account tags description: Account contains all matching account tags get 50 percent cart discount enabled: true automatic: true start: '2025-06-01' end: '2026-06-30' rule_set: rules: strategy: account_tags operator: contains_all args: - 3fa12770-cdf5-4168-a893-9a29eb1b43cc - 31d60110-d492-4f93-983a-7cc466f12c54 actions: - strategy: cart_discount args: - percent - 50 AccountTagsNotContainsAnyPromotion: summary: Create a promotion excluding accounts with any restricted tags. Eligible if account has none of the specified tags. value: data: type: rule_promotion name: 10 percent off for non-denylisted accounts description: Accounts without any of the restricted tags (denylist or fraud) receive a 10% cart discount enabled: true automatic: false start: '2025-06-01' end: '2026-06-30' rule_set: rules: strategy: account_tags operator: not_contains_any args: - 3fa12770-cdf5-4168-a893-9a29eb1b43cc - 31d60110-d492-4f93-983a-7cc466f12c54 actions: - strategy: cart_discount args: - percent - 10 AccountTagsNotContainsAllPromotion: summary: Create a promotion excluding accounts with all restricted tags. Eligible if account is missing at least one of the specified tags. value: data: type: rule_promotion name: 15 percent off for partially restricted accounts description: Accounts that don't have ALL of the specified tags receive a 15% cart discount. Eligible if missing at least one tag. enabled: true automatic: false start: '2025-06-01' end: '2026-06-30' rule_set: rules: strategy: account_tags operator: not_contains_all args: - 3fa12770-cdf5-4168-a893-9a29eb1b43cc - 31d60110-d492-4f93-983a-7cc466f12c54 actions: - strategy: cart_discount args: - percent - 15 AutoAddGiftPromotion: summary: Create an auto add gift promotion. When cart has eligible item, the discounted item is automatically added to cart. value: data: type: rule_promotion name: Buy shoes and get socks for free description: Buy shoes and automatically get socks for free enabled: true automatic: true start: '2025-06-01' end: '2025-06-30' rule_set: rules: strategy: item_identifier operator: in args: - skus: - shoes actions: - strategy: item_discount args: - percent - 100 condition: strategy: item_identifier operator: in args: - skus: - socks limitations: items: auto_add: true CartTotalRangeDiscount: summary: Create a Cart Percent Discount Promotion based on an inclusive cart total range value: data: type: rule_promotion name: Cart 20% discount when total is between $100 and $200, inclusive description: 20% discount applying to carts between $100 and $200, inclusive enabled: false automatic: false start: '2024-01-01' end: '2025-01-01' rule_set: rules: strategy: cart_total operator: range args: - 10000 - 20000 actions: - strategy: cart_discount args: - percent - 20 responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/RulePromotionResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Response.Error' examples: TooManyAutomaticRulePromotions: summary: Error When Attempting to Create an Automatic Rule Promotion While Limit is Reached description: | This error occurs when attempting to **create an automatic rule promotion while the store has already reached the maximum limit** of 50 active and future automatic rule promotions. value: errors: - status: '400' title: Too many automatic rule promotions detail: Only 50 active automatic rule promotions are allowed per store '422': description: Duplicate Priority content: application/json: schema: $ref: '#/components/schemas/Response.Error' get: tags: - Rule Promotions summary: Get Rule Promotions description: | Retrieves a list of rule-based promotions, including information such as discount type, eligibility criteria, and configuration details. This endpoint supports filtering to refine results based on specific promotion attributes. Use query parameters to filter promotions by: - **Code** – Retrieve a specific promotion by its code. - **Promotion name** – Search for promotions by name. - **Activation status** – Filter by whether a promotion is active or not. - **Stackability** – Identify promotions that can or cannot be combined with others. - **Start and end dates** – Retrieve promotions based on their validity periods. operationId: getRulePromotions security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/Authorization' - $ref: '#/components/parameters/PageLimit' - $ref: '#/components/parameters/PageOffset' - name: filter in: query schema: type: string description: | This parameter accepts a filtering expression that uses specific operators and attributes. The following operators and attributes are available when filtering on this endpoint. See [Supported Filtering Characters](/guides/Getting-Started/filtering#supported-characters). | Attribute | Type | Operator | Example | |:--------------------------|:-------------------|:-----------------------------|:----------------------------------------------------------------------| | `code` | `string`, `number` | `eq` | `eq(code,summer2024)` | | `name` | `string` | `like`,`ilike` | `ilike(name,'Summer *')` | | `enabled` | `boolean` | `eq` | `eq(enabled, true)` | | `stackable` | `boolean` | `eq` | `eq(stackable, true)` | | `override_stacking` | `boolean` | `eq` | `eq(override_stacking, true)` | | `start` | `date` | `lt`, `le`, `eq`, `gt`, `ge` | `gt(start, 2025-01-01T00:00:00.000Z)` | | `end` | `date` | `lt`, `le`, `eq`, `gt`, `ge` | `lt(end, 2025-01-01T00:00:00.000Z)` | | `rule_set.rules.strategy` | `string` | `eq`, `in` | `eq(rule_set.rules.strategy,account_tags)` | | `rule_set.rules.args` | `string` | `contains` | `contains(rule_set.rules.args, 11111111-1111-4111-1111-111111111111)` | | `account_tags` | `string` | `contains` | `contains(account_tags, 11111111-1111-4111-1111-111111111111)` | Some notes about filters: 1. The `code` filter is case-insensitive. You can search for codes using only `numbers` or codes containing both `string` and `numbers`. 2. The `rule_set.rules.*` filters do not search child conditions at present 3. The `account_tags` filter will essentially search for any rule or child rule that has an `account_tags` strategy and the associated accounts. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RulePromotionListResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Response.Error' /v2/rule-promotions/{promotionID}: get: tags: - Rule Promotions summary: Get a Rule Promotion by ID description: | Retrieves a single Rule Promotion by the promotion ID. Responses include promotion specifications such as discount type, eligibility criteria, and configuration details. operationId: getRulePromotionById security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/Authorization' - name: promotionID in: path required: true schema: type: string description: The unique identifier of the rule promotion. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RulePromotionResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Response.Error' put: tags: - Rule Promotions summary: Update a Rule Promotion description: | Updates an existing Rule Promotion specified by its promotion ID. This includes both **semantic and syntactic validation** to ensure correctness. For example, the start date must be earlier than the end date. Editable fields include: - `name` - `description` - `enabled` - `start` - `end` - `automatic` - `stackable` - `override_stacking` - `rule_set` :::note When updating the `automatic` field from `false` to `true`, the store must not exceed the maximum limit of **50 active and future automatic rule promotions**. ::: operationId: updateRulePromotion security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/Authorization' - name: promotionID in: path required: true schema: type: string description: The unique identifier of the promotion to be updated. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RulePromotionItem' examples: UpdateCartPercentDiscount: summary: Update a Cart Percent Discount Rule Promotion value: data: type: rule_promotion name: $10 off cart rule - updated description: updated cart rule $10 off your order! enabled: false automatic: false rule_set: rules: - strategy: cart_total operator: lt args: - 1000 actions: - strategy: cart_discount args: - percent - 10 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/RulePromotionResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Response.Error' examples: TooManyAutomaticRulePromotions: summary: Error When Attempting to Update a Manual Promotion to Automatic While Limit is Reached description: | This error occurs when attempting to **update a manual rule promotion to automatic while the store has already reached the maximum limit** of 50 active and future automatic rule promotions. value: errors: - status: '400' title: Too many automatic rule promotions detail: Only 50 active and future automatic rule promotions are allowed per store '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/Response.Error' examples: UnprocessableEntity: summary: Unprocessable Entity value: errors: - title: Unprocessable Entity status: '422' detail: '' DuplicatePriority: summary: Two codes cannot have the same priority value: errors: - title: Duplicate Priority status: '422' detail: Priority already in use in another running or scheduled promotion delete: tags: - Rule Promotions summary: Delete a Rule Promotion description: | Deletes an existing Rule Promotion identified by its promotion ID. - This action **permanently removes** the promotion and cannot be undone. - If the promotion is active, please ensure that its removal does not impact ongoing campaigns. A successful request returns a `204 No Content` response, indicating that the promotion has been deleted. operationId: deleteRulePromotion security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/Authorization' - name: promotionID in: path required: true schema: type: string description: The unique identifier of the promotion. responses: '204': description: No Content /v2/rule-promotions/{promotionID}/codes: post: tags: - Rule Promotion Codes summary: Create Rule Promotion Codes description: | Creates new promotion codes for a specific rule promotion, allowing customers to redeem discounts based on predefined conditions. - Supports bulk creation of multiple promotion codes in a single request. - Each code can have individual usage limits. - Can optionally assign codes to specific users to enforce targeted promotions. - The promotion codes are case-insensitive. :::note Regarding first time shopper limitations: - Orders without payment transactions do not count as completed purchases. - Canceling or refunding an order does not reinstate first-time shopper status. - A first-time shopper coupon code cannot have limited uses or be assigned to specific users, meaning the code cannot be restricted by the number of times it can be used or tied to a specific customer ID. ::: A successful request returns a `201 Created` response with details of the generated promotion codes. ### Duplicate Codes Duplicate promotion codes **are supported across different promotions** in the store, regardless of their statuses and validity dates. However, **duplicate codes cannot be created within the same promotion**. This means that shoppers can apply a single coupon code to trigger multiple promotions if those promotions share common coupon codes. Codes that share the same name can serve different purposes. For example, one code may have `per_application` with a limited number of uses, while another identical code can have `per_checkout` with unlimited use. **Duplicate Code Handling:** - If a duplicate code is detected **within the same promotion**, the request will return a `422 Duplicate code` error. - When creating duplicate codes, a message appears with the successful response indicating the duplication. Please refer to the **OpenAPI examples** section on this page for sample request structures. operationId: createRulePromotionCodes security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/Authorization' - name: promotionID in: path required: true schema: type: string description: The unique identifier of the rule promotion. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PromotionCodesRequest' examples: CreateCodes: summary: Create Rule Promotion Codes value: data: type: promotion_codes codes: - code: spring2024 - code: summer2024 consume_unit: per_checkout - code: summer2024_limited consume_unit: per_application uses: 5 - code: summer2024_memberOnly consume_unit: per_application uses: 1 user: vip_shopper@email.com SingleUsePerShopperIncludingGuests: summary: Create a Promotion Code Usable Once Per Shopper, Including Guest Shoppers with Emails Associated with their Carts value: data: type: promotion_codes codes: - code: one_per_shopper consume_unit: per_checkout max_uses_per_shopper: includes_guests: true max_uses: 1 MaxUsesLimitWithPerShopperRestriction: summary: Create a Promotion Code with a Total Usage Limit and Per Shopper Restriction description: | Create a promotion code that allows up to **10 total uses** and allows each individual shopper to use the code **once**. - The `uses` field is set to `10`, meaning the promotion code can be redeemed a maximum of **10 times across all shoppers**. - The `max_uses_per_shopper` field sets `max_uses: 1`, ensuring **each shopper can only redeem the code once**. - The `includes_guests` field is set to `true`, allowing **both registered and guest shoppers** to use the promotion code. - The `consume_unit` is set to `per_checkout`, meaning the code is **consumed once per successful checkout**. This setup is useful for **one-time promotions** where a **limited number of shoppers can redeem the code** but prevents any single shopper from claiming multiple redemptions. value: data: type: promotion_codes codes: - code: one_time_use consume_unit: per_checkout uses: 10 max_uses_per_shopper: includes_guests: true max_uses: 1 MaxUsesForSpecificShopper: summary: Limit Promotion Code Usage to a Specific Shopper description: | Create a promotion which **limits the maximum usage of a promotion code to a specific shopper** based on their `customerID`. - The `uses` field is set to `1`, meaning **this promotion code can only be used once by the identified shopper**. - The `user` field is set to `customer-id-123`, ensuring the **code is only valid when the cart is checked out by the specified customer**. - The `consume_unit` is set to `per_checkout`, meaning the code is **redeemed upon a successful checkout**. **Important Notes:** - This method is useful for **targeted, personalized promotions** where only a specific shopper should receive the discount. - The promotion code **cannot be used by any other shopper**. - **Account user IDs are currently not supported**. This setup is ideal for **single-use, customer-specific promotions**, such as loyalty rewards or personalized discount offers. value: data: type: promotion_codes codes: - code: one_per_shopper consume_unit: per_checkout uses: 1 user: customer-id-123 MaxUsesForSpecificRegisteredShopper: summary: Limit Promotion Code Usage to a Specific Registered Shopper description: | This example demonstrates how to **restrict a promotion code to a specific registered shopper** using their `customerID`, with a limit on how many times they can redeem the code. - The `user` field is set to `customer-id-123`, ensuring **only the specified shopper can use the promotion code**. - The `max_uses_per_shopper.max_uses` field is set to `1`, meaning **this shopper can only redeem the code once**. - The `max_uses_per_shopper.includes_guests` field is set to `false`, meaning **guest shoppers cannot use this code**. - The `consume_unit` is set to `per_checkout`, meaning **the code is consumed once per successful checkout**. **Key Differences from Other Shopper-Specific Limits:** - Unlike a `uses: 1` setup, which sets a global limit for the code, this method **explicitly enforces per-shopper usage limits**. - This approach is ideal for **exclusive promotions targeting specific registered shoppers**, ensuring that only they can redeem the discount and preventing usage by guest shoppers. - **Account user IDs are currently not supported**. This setup is useful for **member-only discounts, personalized promotional offers, or exclusive VIP rewards**. value: data: type: promotion_codes codes: - code: one_per_shopper consume_unit: per_checkout user: customer-id-123 max_uses_per_shopper: includes_guests: false max_uses: 1 FirstTimeShopperCodeRequest: summary: Create a Promotion Code for First-Time Shoppers description: | Create a **promotion code that is only applicable to first-time shoppers**. Here, the `is_for_new_shopper` field is set to `true`, indicating that **only first-time shoppers can use this code**. **Important Notes:** - Promotion codes with `is_for_new_shopper: true` **cannot have usage limits** (`uses`) or be assigned to specific users. - If usage limits or shopper assignments are included, a **400 Invalid Code error** will be returned. value: data: type: promotion_codes codes: - code: first_time is_for_new_shopper: true responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/CreatePromotionCodesResponse' examples: PromotionCodeCreatedResponse: summary: Response When a Promotion Code is Successfully Created value: data: - id: 8a1c73bc-7c15-41c3-a3ed-a0aa398c3984 code: one_per_shopper user: 5abb8d4e-57c0-459b-91d5-c4e6f77e9c5e max_uses_per_shopper: max_uses: 1 includes_guests: false consume_unit: per_checkout FullyConsumedPromotionCodeResponse: summary: Response When a Promotion Code Has Been Fully Used description: | Response indicating that a **promotion code has already been fully consumed** by the shopper and is no longer valid for use. - The `source.id` field provides the unique identifier of the promotion. - The `source.code` field specifies the exact promotion code that has been fully consumed. - The `title` field (`"Fully Consumed"`) serves as a user-friendly summary of the issue. - The `description` field provides a clear explanation: `"You've already fully consumed this promotion code"`. This response is useful for handling **errors when applying promotion codes**, ensuring that customers receive **clear feedback** if they attempt to reuse a code that has reached its usage limit. value: messages: - source: type: promotion_codes id: 38861a5c-81bb-43bc-8934-e30cde108579 code: one_per_shopper title: Fully Consumed description: You've already fully consumed this promotion code DuplicateCodeNameResponse: summary: Message Response When Creating a Duplicate Promotion Code Name value: messages: - source: type: promotion_codes codes: - duplicate-code title: Duplicate code names description: Code names duplicated in other promotions '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: status: type: integer example: 400 source: type: string example: data.codes.0.max_uses_per_shopper title: type: string example: missing_dependency detail: type: string example: Has a dependency on max_uses examples: MissingMaxUsesDependencyError: summary: Error When `max_uses_per_shopper.includes_guests` is Provided Without `max_uses` description: | This error occurs when `max_uses_per_shopper.includes_guests` is provided **without specifying** `max_uses`. value: errors: - status: 400 source: data.codes.0.max_uses_per_shopper title: missing_dependency detail: Has a dependency on max_uses FirstTimeShopperCodeError: summary: Error When Setting Usage Limits While Assigning First-Time Shopper Codes description: | This error occurs when a **first-time shopper promotion code** is created **with restricted uses (`uses`) or assigned to specific users (`user`)**. value: errors: - status: 400 source: '' title: Invalid Code detail: Code - first_time_uses can't have limited uses or assigned to users since it's for first-time shoppers. '422': description: Unprocessable Entity content: application/json: schema: type: object properties: errors: type: array items: type: object properties: status: type: string example: '422' source: type: string example: '' title: type: string example: Unsupported consume unit detail: type: string example: Consume unit 'per_application' is not supported when using 'max_uses_per_shopper' features. examples: UnsupportedConsumeUnitError: summary: Error When `max_uses_per_shopper.max_uses` is Used with `per_application` description: | This error occurs when `max_uses_per_shopper.max_uses` is set while using `consume_unit: per_application`, which is not supported. value: errors: - status: '422' source: '' title: Unsupported consume unit detail: Consume unit 'per_application' is not supported when using 'max_uses_per_shopper' features. NoCodesAllowedForAutomaticPromotion: summary: Error When Attempting to Create Promotion Codes for Automatic Promotions value: errors: - status: '422' title: No codes allowed detail: Cannot add codes to automatic promotion DuplicatePromotionCodeError: summary: Error When Creating a Promotion Code That Already Exists description: | This error occurs when attempting to create a promotion code that already exists within the same Rule Promotion. value: errors: - status: '422' title: Duplicate code detail: Promotion code already in use get: tags: - Rule Promotion Codes summary: Get Rule Promotion Codes description: | Retrieves the list of promotion codes associated with a specific Rule Promotion. - Returns all codes generated for the given promotion ID, including details on usage limits and redemption status. - Supports both automatically generated and manually created promotion codes. - Can be used to verify whether a promotion code is still valid or has reached its usage limit. operationId: getRulePromotionCodes security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/Authorization' - name: promotionID in: path required: true schema: type: string description: The unique identifier of the rule promotion. - name: filter in: query schema: type: string description: | This parameter accepts a filtering expression that uses specific operators and attributes. Promotion codes are case-insensitive. The following operators and attributes are available when filtering on this endpoint. See [Supported Filtering Characters](/guides/Getting-Started/filtering#supported-characters). | Attribute | Type | Operator | Example | |:--------- |:---------|:------------|:---------------| | `code` | `string`, `number` | `eq`, `gt` | `eq(code,summer2024)`, `gt(code,2024)` | - name: sort in: query schema: type: string enum: - code - '-code' x-enumDescriptions: code: Sort in increasing order of code, case-insensitively. '-code': Sort in decreasing order of code, case-insensitively. description: | Specifies the order of the codes that will be returned. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GetPromotionCodesResponse' delete: tags: - Rule Promotion Codes summary: Delete Rule Promotion Codes description: | Deletes one or more promotion codes from a specific rule promotion. - Supports **bulk deletion**, allowing multiple codes to be removed in a single request. - Removes promotion codes permanently, making them unavailable for future use. - If a code has already been redeemed, it will be removed from the system but may still reflect in historical transactions. A successful request returns a `204 No Content` response, indicating the specified promotion codes have been deleted. operationId: deleteRulePromotionCodes security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/Authorization' - name: promotionID in: path required: true schema: type: string description: The unique identifier of the rule promotion. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PromotionCodesRequest' examples: DeleteCodes: summary: Delete Rule Promotion Codes value: data: type: promotion_codes codes: - code: spring2024 - code: summer2024 consume_unit: per_checkout - code: summer2024_limited consume_unit: per_application uses: 5 - code: summer2024_memberOnly consume_unit: per_application uses: 1 user: vip_shopper@email.com responses: '204': description: No Content '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Response.Error' /v2/rule-promotions/{promotionID}/codes/{codeID}: delete: tags: - Rule Promotion Codes summary: Delete A Single Rule Promotion Code description: | Deletes a single promotion code from a specific rule promotion. - Permanently removes the specified promotion code, making it unavailable for future use. - Can be used to **revoke a specific code** without affecting other codes under the same promotion. - If the code has already been redeemed, it will still be removed from the system but may still reflect in historical transactions. A successful request returns a `204 No Content` response, indicating the specified promotion code has been deleted. operationId: deleteSingleRulePromotionCode security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/Authorization' - name: promotionID in: path required: true schema: type: string description: The unique identifier of the rule promotion. - name: codeID in: path required: true schema: type: string description: The unique identifier of the rule promotion code. responses: '204': description: No Content /v2/rule-promotions/{uuid}/jobs: post: operationId: createRulePromotionJob summary: Create a Rule Promotion Job description: | Creates an asynchronous job for a specific Rule Promotion. Jobs are used to generate or export promotion codes in bulk. The following job types are supported: - **`code_generate`**: Generates a batch of unique promotion codes. - **`code_export`**: Exports all existing promotion codes as a downloadable CSV file. Job processing occurs asynchronously. The job request is queued, and its status must be checked separately. ### Job Processing Status Jobs can have the following statuses: - `pending`: Job is in the queue, waiting to be processed. - `processing`: Job is actively being processed. - `completed`: Job completed successfully. - `failed`: Job encountered an error and did not complete. - `cancelling`: Cancellation in progress (for long-running jobs). - `cancelled`: Job was successfully cancelled. Please refer to the **OpenAPI examples** section on this page for sample job creation requests. tags: - Rule Promotion Jobs parameters: - name: uuid in: path required: true schema: type: string description: The unique identifier of the rule promotion. requestBody: required: true content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/PromotionJob' examples: GenerateBulkPromotionCodes: summary: Create a Job to Generate 100 Bulk Promotion Codes description: | Create an asynchronous job to generate **100 unique promotion codes** with specific parameters. - The `job_type` is `"code_generate"`, meaning this job will generate new promotion codes. - The `parameters` field defines: - `number_of_codes: 100`, meaning **100 unique codes will be generated**. - `max_uses_per_code: 1`, restricting **each code to a single use**. - `consume_unit: per_checkout`, meaning **each code is consumed once per successful checkout**. - `code_prefix: "summer-"`, ensuring that **each generated code starts with "summer-"**. - `code_length: 8`, specifying that **each code will have 8 characters after the prefix**. **Job Processing:** - The job will run asynchronously, and the status must be checked separately. - You can retrieve the job's status and results using the **Get Rule Promotion Jobs** endpoint. value: data: type: promotion_job job_type: code_generate name: Demo bulk code generate parameters: number_of_codes: 100 max_uses_per_code: 1 consume_unit: per_checkout code_prefix: summer- code_length: 8 ExportPromotionCodes: summary: Create a Rule Promotion Job to Export All Promotion Codes description: | Create an asynchronous job to export all **existing promotion codes** as a downloadable CSV file. **Job Processing:** - The job runs asynchronously, and its status must be checked separately. - Once the job completes, the exported file will be available for download. - You can track the job's status using the **Get Rule Promotion Jobs** endpoint. value: data: type: promotion_job job_type: code_export name: Demo export codes responses: '201': description: Promotion job created content: application/json: schema: type: object description: Promotion job response properties: data: $ref: '#/components/schemas/PromotionJobResponse' '400': description: Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: status: type: string example: '400' title: type: string example: Too many jobs detail: type: string example: Only 1 pending or processing job is allowed per promotion. examples: TooManyJobsError: summary: Error When Attempting to Create a Job While Another Job is Still Processing description: | This error occurs when a **new job is requested while another job is still pending or processing** for the same promotion. value: errors: - status: '400' title: Too many jobs detail: Only 1 pending or processing job is allowed per promotion. security: - bearerAuth: [] get: operationId: getRulePromotionJobs summary: Get Rule Promotion Jobs description: | Retrieves a list of jobs associated with a specific rule promotion. Each job represents an asynchronous operation such as promotion code generation or export. The response includes details such as: - **Job type** (`code_generate` or `code_export`) - **Job status** (`pending`, `processing`, `completed`, `failed`, `cancelling`, or `cancelled`) - **Parameters used** (such as number of codes generated) - **Results** (such as number of codes successfully generated or deleted) ### Filtering You can filter jobs by: - **Job Type** (`eq(job_type, code_export)`) - **Status** (`eq(status, complete)`) tags: - Rule Promotion Jobs parameters: - name: uuid in: path required: true schema: type: string description: The unique identifier of a rule promotion. - name: filter in: query required: false schema: type: string description: Specifies filter attributes. responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PromotionJobsListResponse' security: - bearerAuth: [] /v2/rule-promotions/{uuid}/jobs/{job-uuid}/file: get: operationId: getRulePromotionJobFile summary: Get Rule Promotion Code Exported File description: | Retrieves the exported promotion codes for a rule promotion job in a CSV format. - The file contains the generated codes along with relevant metadata. - This endpoint is applicable only for jobs of type `code_export`. - The job must be in a `completed` state before the file can be retrieved. tags: - Rule Promotion Jobs parameters: - name: uuid in: path required: true schema: type: string description: The unique identifier of the rule promotion. - name: job-uuid in: path required: true schema: type: string description: The unique identifier of the job associated with the file. responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/PromotionCodeExportedFileResponse' security: - bearerAuth: [] /v2/rule-promotions/{uuid}/jobs/{job-uuid}/cancel: post: operationId: cancelRulePromotionJob summary: Cancel a Rule Promotion Job description: | Cancels an asynchronous job for a rule promotion if its status is `pending` or `processing`. - Only jobs that have not yet completed can be canceled. - Once canceled, no further processing occurs, and partially completed results may be deleted. tags: - Rule Promotion Jobs parameters: - name: uuid in: path required: true schema: type: string description: The unique identifier of the rule promotion. - name: job-uuid in: path required: true schema: type: string description: The unique identifier of the job to be canceled. responses: '200': description: Successfully Canceled the Rule Promotion Job content: application/json: schema: type: object description: Promotion job response properties: data: $ref: '#/components/schemas/PromotionJobResponse' examples: PromotionJobCancellingResponse: summary: Successful Cancellation Request for a Rule Promotion Job description: | This response indicates that the **job cancellation request was successfully submitted**, and the job is now in the `"cancelling"` state. - The job has entered the **cancelling state**, meaning the system is stopping it. - To check the job's final status, use the **Get Rule Promotion Jobs** endpoint. - If the job successfully cancels, it will transition to `"cancelled"`. - If cancellation fails (e.g., the job completes before being stopped), it may remain `"completed"`. value: data: type: promotion_job id: 9bc1391c-1b65-419e-940e-66ed86c07001 rule_promotion_id: 8c150382-b258-4c88-a2d4-b9ea0be74a07 job_type: code_generate name: Demo bulk code generate parameters: number_of_codes: 100 max_uses_per_code: 1 consume_unit: per_checkout code_prefix: summer- code_length: 8 status: cancelling meta: timestamps: created_at: '2024-12-03T23:31:40.962680423Z' updated_at: '2024-12-03T23:31:40.962680423Z' '422': description: Unprocessable Entity content: application/json: schema: type: object properties: errors: type: array items: type: object properties: status: type: string example: '422' title: type: string example: Unprocessable Entity detail: type: string example: Only pending or processing jobs can be cancelled. examples: CannotCancelCompletedJobError: summary: Error When Attempting to Cancel a Job That Is Not Pending or Processing description: | This error occurs when a **job cancellation request** is made for a job that **is not in a `pending` or `processing` state**. **Possible Causes:** - Attempting to cancel a job that has already **completed**, **failed**, or was **previously cancelled**. - The job may have already transitioned out of `pending` or `processing` by the time the request was made. value: errors: - status: '422' title: Unprocessable Entity detail: Only pending or processing jobs can be cancelled. security: - bearerAuth: [] /v2/rule-promotions/usages/anonymize: post: tags: - Rule Promotion Usages summary: Anonymize Rule Promotion Usages description: | Anonymizes user-related data in Rule Promotion usage records. This operation is typically used for GDPR compliance or privacy-related requests. - This process replaces identifiable user data with anonymized placeholders. - Affects all recorded promotion usages where customer data is stored. - Does not impact historical transaction records or applied discounts. A successful request returns a `200 OK` response with the anonymized usage records. operationId: anonymizeRulePromotionUsages security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: data: type: object properties: usage_ids: type: array items: type: string description: | The unique identifiers of the usages to be anonymized. Multiple usage IDs can be provided to anonymize in bulk. required: - data example: data: usage_ids: - ca4385ec-7fb2-4a95-8690-f752c508d68a - d4e5f6g7-h8i9-0j1k-2l3m-4n5o6p7q8r9s responses: '200': description: OK content: application/json: schema: allOf: - type: object properties: data: type: array items: $ref: '#/components/schemas/RulePromotionUsage' - $ref: '#/components/schemas/Response.Error' example: data: - id: ca4385ec-7fb2-4a95-8690-f752c508d68a order_id: 8edd5ca8-39b7-468d-aea9-a470690ca98d code_id: 00fc633b-9932-4e18-b122-fd5c3173caa3 code: node1off times_used: 1 used_on: '2023-06-19T18:05:20.846Z' customer_id: 9ef25142-d67a-41d3-99b2-4d30aeef6c9d customer_email: '**' meta: timestamps: updated_at: '2023-06-19T18:05:39.141Z' updated_by: Key-2439657140697170361 anonymized: true '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Response.Error' example: errors: - status: 400 title: Invalid Request detail: The request payload is malformed or missing required fields. '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Response.Error' example: errors: - status: 401 title: Unauthorized detail: Authentication credentials were missing or incorrect. '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Response.Error' example: errors: - status: 404 title: Usages Not Found detail: Some usage IDs could not be found. meta: usage_ids: - invalid-usage-id-1 - invalid-usage-id-2 /v2/rule-promotions/{promotionID}/usages: get: tags: - Rule Promotion Usages summary: Get Rule Promotion Usages description: | Retrieves a list of usage records for a specific Rule Promotion. - Provides details about when and how a promotion was used. - Can be filtered and paginated to refine results. - Useful for analyzing promotion effectiveness and customer engagement. operationId: getRulePromotionUsages security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/Authorization' - name: promotionID in: path required: true schema: type: string description: The unique identifier of the rule promotion. - name: filter in: query required: false schema: type: string description: | Filter attributes to refine the usage records. Supported attributes: - `id`: Filter by usage ID. - `code`: Filter by promotion code. - `used_on`: Filter by usage date with operators `gt`, `ge`, `le`, `lt`. example: eq(code,cart1off) - name: page[limit] in: query required: false schema: type: integer description: The number of records per page. example: 10 - name: page[offset] in: query required: false schema: type: integer description: The number of records to offset the results by. example: 0 responses: '200': description: Successful response content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/RulePromotionUsage' links: $ref: '#/components/schemas/PaginationLinks' meta: $ref: '#/components/schemas/PaginationMeta' example: data: - id: a9b73e4d-637f-4f1c-9b3e-2de1f8a70351 order_id: e3d7b9fa-4a90-4e98-bac2-d7a4b4f2f63f code_id: 8a2c3f47-9d3b-4562-8392-4e5e6cda3d2b code: cart10off times_used: 1 used_on: '2024-02-20T15:42:00.000Z' customer_id: 4f3e8c5d-37e4-43fb-9276-d1b76f0c3a2a customer_email: shopper@example.com meta: timestamps: updated_at: '2024-02-20T15:45:00.000Z' updated_by: Admin-User-123 links: first: https://useast.api.elasticpath.com/v2/rule-promotions/123/usages?page%5Boffset%5D=0&page%5Blimit%5D=10 last: https://useast.api.elasticpath.com/v2/rule-promotions/123/usages?page%5Boffset%5D=90&page%5Blimit%5D=10 prev: null next: https://useast.api.elasticpath.com/v2/rule-promotions/123/usages?page%5Boffset%5D=10&page%5Blimit%5D=10 meta: pagination: total: 100 limit: 10 offset: 0 current: 1 '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Response.Error' example: errors: - status: 401 title: Unauthorized detail: Authentication is required to access this resource. '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Response.Error' example: errors: - status: 404 title: Promotion Not Found detail: No usages found for the specified promotion ID. /v2/rule-promotions/{promotionID}/codes/{code}/usages: get: tags: - Rule Promotion Usages summary: Get Rule Promotion Code Usages description: | Retrieves a list of usage records for a specific Rule Promotion code. - Provides insights into how many times a specific code was used. - Can be filtered and paginated to refine results. - Useful for tracking the performance of individual promotion codes. operationId: getRulePromotionCodeUsages security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/Authorization' - name: promotionID in: path required: true schema: type: string description: The unique identifier of the rule promotion. - name: code in: path required: true schema: type: string description: The specific promotion code for which to retrieve usage records. - name: filter in: query required: false schema: type: string description: | Filter attributes to refine the results. Supported attributes: - `id`: Filter by usage ID. - `used_on`: Filter by date with operators `gt`, `ge`, `le`, `lt`. example: gt(used_on,2024-02-01T00:00:00Z) - name: page[limit] in: query required: false schema: type: integer description: The number of records per page. example: 10 - name: page[offset] in: query required: false schema: type: integer description: The number of records to offset the results by. example: 0 responses: '200': description: Successful response content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/RulePromotionUsage' links: $ref: '#/components/schemas/PaginationLinks' meta: $ref: '#/components/schemas/PaginationMeta' example: data: - id: c2f45a8d-6ebf-4b6a-8b1c-d2e7c9e0f45f order_id: 1a3b5c7d-9e2f-4a5b-8c1d-6e3f9b0d4c5f code_id: 5d7e9f2b-3c4a-6b8d-1e9f-0a2b3c4d5e6f code: holiday50 times_used: 2 used_on: '2024-02-18T10:30:00.000Z' customer_id: 7e6c5d4b-3a2f-1e9d-8b0c-9f4e7d6c3b5a customer_email: vipuser@example.com meta: timestamps: updated_at: '2024-02-18T10:35:00.000Z' updated_by: Admin-User-456 links: first: https://useast.api.elasticpath.com/v2/rule-promotions/123/codes/holiday50/usages?page%5Boffset%5D=0&page%5Blimit%5D=10 last: https://useast.api.elasticpath.com/v2/rule-promotions/123/codes/holiday50/usages?page%5Boffset%5D=10&page%5Blimit%5D=10 prev: null next: https://useast.api.elasticpath.com/v2/rule-promotions/123/codes/holiday50/usages?page%5Boffset%5D=10&page%5Blimit%5D=10 meta: pagination: total: 20 limit: 10 offset: 0 current: 1 '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Response.Error' example: errors: - status: 401 title: Unauthorized detail: Authentication is required to access this resource. '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Response.Error' example: errors: - status: 404 title: Promotion Code Not Found detail: No usages found for the specified promotion code. components: schemas: RulePromotionItem: allOf: - $ref: '#/components/schemas/RulePromotionBaseAttributes' - $ref: '#/components/schemas/RulePromotionBaseRuleSetBaseAttributes' RulePromotionResponse: type: object properties: data: $ref: '#/components/schemas/RulePromotionItem' RulePromotionListResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/RulePromotionItem' links: $ref: '#/components/schemas/PaginationLinks' meta: $ref: '#/components/schemas/PaginationMeta' RulePromotionUsage: type: object description: Represents a single rule promotion usage record. properties: id: type: string description: The unique identifier of the usage record. order_id: type: - string - 'null' description: The associated order ID, if applicable. code_id: type: string description: The unique identifier of the promotion code. code: type: string description: The promotion code used. times_used: type: integer description: The number of times the promotion code has been used. used_on: type: string format: date-time description: The timestamp when the promotion was applied. customer_id: type: - string - 'null' description: The customer identifier who used the promotion, if applicable. account_id: type: - string - 'null' description: The account identifier associated with the promotion usage, if applicable. customer_email: type: - string - 'null' description: The email of the customer who used the promotion, if applicable. meta: type: object properties: timestamps: type: object properties: updated_at: type: string format: date-time description: The timestamp when the usage record was last updated. updated_by: type: string description: Identifier of the user or system that last updated the record. anonymized: type: boolean description: Indicates whether the usage record has been anonymized. RulePromotionBaseAttributes: type: object properties: type: type: string const: rule_promotion name: type: string description: Specifies a name for the promotion. description: type: string description: Specifies a description for the rule promotion. priority: type: integer description: Specifies the priority order of a promotion, with larger numbers indicating higher priorities. enabled: type: boolean description: Specifies whether the promotion is enabled. The options are true or false, and the default setting is false. automatic: type: boolean description: Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is false. When this value is set to true, a code is autogenerated. If this value is set to false, you must create the code manually. stackable: type: boolean description: Specifies whether this promotion can stack with other promotions. override_stacking: type: boolean description: Enables a promotion to be stacked with an otherwise non-stackable promotion. start: type: string format: date-time description: Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format. If no time is specified, the default start and end time is set to 00:00. end: type: string format: date-time description: Specifies the end date and time of the promotion or the end date of the promotion. id: type: string format: uuid description: Unique identifier for the promotion. store_id: type: string format: uuid description: Store identifier for the promotion. created_by: type: string description: User or system that created the promotion. updated_by: type: string description: User or system that last updated the promotion. meta: type: object properties: timestamps: type: object properties: created_at: type: string format: date-time description: Timestamp when the promotion was created. updated_at: type: string format: date-time description: Timestamp when the promotion was last updated. required: - created_at - updated_at required: - timestamps RulePromotionBaseRuleSetBaseAttributes: type: object properties: rule_set: type: object description: Controls the applicability of the promotion as well as the specific benefit or mechanic of the promotion. properties: catalog_ids: type: array items: type: string format: uuid description: Specifies the [catalogs](https://elasticpath.dev/docs/api/pxm/catalog/catalogs) that are eligible for the promotion. By default, the promotion applies to all items, including custom items. However, when catalog_ids is defined, the promotion is only applied to items within the specified catalogs. If catalog IDs are specified, custom items cannot be applied as part of the promotion. currencies: type: array items: type: string description: Specifies [currencies](https://elasticpath.dev/docs/api/pxm/currencies/currencies) that are applied for the promotion rules: type: object description: The scope or applicability of the promotion (i.e., specifies what conditions must be true for a cart to be eligible for the promotion). oneOf: - $ref: '#/components/schemas/AccountTags' - $ref: '#/components/schemas/And' - $ref: '#/components/schemas/CartCustomAttributes' - $ref: '#/components/schemas/CartItemCustomAttributes' - $ref: '#/components/schemas/CartTotal' - $ref: '#/components/schemas/ItemAttribute' - $ref: '#/components/schemas/ItemCategory' - $ref: '#/components/schemas/ItemIdentifier' - $ref: '#/components/schemas/ItemPrice' - $ref: '#/components/schemas/ItemProductId' - $ref: '#/components/schemas/ItemQuantity' - $ref: '#/components/schemas/ItemsBundle' - $ref: '#/components/schemas/ItemSku' - $ref: '#/components/schemas/Or' actions: type: array description: Describes how this promotion should be applied to the cart and order. items: oneOf: - $ref: '#/components/schemas/CartDiscount' - $ref: '#/components/schemas/ItemDiscount' - $ref: '#/components/schemas/ShippingDiscount' - $ref: '#/components/schemas/BundleDiscount' PromotionCodesRequest: type: object properties: data: type: object properties: type: type: string const: promotion_codes codes: type: array description: Specifies the code details in an array of objects. items: type: object properties: code: type: string description: Specifies the string to use as a code for the promotion. uses: type: integer description: Specifies the number of times the code can be used. If no value is set, the customer can use the code any number of times. user: type: string description: Specifies the customer ID of the shopper who can use the code. For more information, see the [Create a customer](/docs/customer-management/customer-management-api/create-a-customer) section. consume_unit: type: string enum: - per_application - per_checkout description: | Specifies whether the code is consumed per application or per checkout. With `per_checkout`, the code is used once for each checkout, regardless of the number of items in the cart. When set to `per_application`, the code is used per application. For cart discounts, each application counts as one usage. For item discounts, each application to either a single quantity or a bundle is counted as one usage. For example, in a store that offers 50% off on SKU1, SKU2, and SKU3, and limits the maximum usage of the promotion code to two, a shopper can apply the promotion up to two quantities. If the cart contains two or more quantities of SKU1, the promotion is applied 2 times to SKU1, and other quantities and items are at the regular price. If the cart contains one quantity of SKU1, one quantity of SKU2, and one quantity of SKU3, the promotion is applied once to SKU1 and once to SKU2. The code usage is applied at checkout and the code is considered consumed at that point. max_uses_per_shopper: $ref: '#/components/schemas/MaxUsesPerShopper' is_for_new_shopper: type: boolean description: A flag indicating whether the coupon is for first-time shoppers. If set to `true`, the discount will only apply if the shopper has never made a payment on any order in the store. If set to `false` or left unset, it will be a regular discount that applies to all shoppers. When this flag is set to `true`, the coupon cannot have usage limitations or be assigned to specific users. CreatePromotionCodesResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/CreatePromotionCodeResponse' messages: type: array items: $ref: '#/components/schemas/PromotionCodeMessage' GetPromotionCodesResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/GetPromotionCodeResponse' links: $ref: '#/components/schemas/PaginationLinks' meta: $ref: '#/components/schemas/PaginationMeta' GetPromotionCodeResponse: type: object properties: type: type: string const: promotion_codes id: type: string format: uuid description: Unique identifier for the promotion code code: type: string uses: type: integer user: type: string consume_unit: type: string enum: - per_application - per_checkout description: | Specifies whether the code is consumed per application or per checkout. With `per_checkout`, the code is used once for each checkout, regardless of the number of items in the cart. When set to `per_application`, the code is used per application. For cart discounts, each application counts as one usage. For item discounts, each application to either a single quantity or a bundle is counted as one usage. For example, in a store that offers 50% off on SKU1, SKU2, and SKU3, and limits the maximum usage of the promotion code to two, a shopper can apply the promotion up to two quantities. If the cart contains two or more quantities of SKU1, the promotion is applied 2 times to SKU1, and other quantities and items are at the regular price. If the cart contains one quantity of SKU1, one quantity of SKU2, and one quantity of SKU3, the promotion is applied once to SKU1 and once to SKU2. The code usage is applied at checkout and the code is considered consumed at that point. max_uses: type: integer max_uses_per_shopper: $ref: '#/components/schemas/MaxUsesPerShopper' is_for_new_shopper: type: boolean created_by: type: string meta: type: object properties: timestamps: type: object properties: created_at: type: string format: date-time CreatePromotionCodeResponse: type: object properties: id: type: string format: uuid type: type: string const: promotion_codes code: type: string uses: type: integer user: type: string consume_unit: type: string enum: - per_application - per_checkout max_uses: type: integer max_uses_per_shopper: $ref: '#/components/schemas/MaxUsesPerShopper' is_for_new_shopper: type: boolean PromotionCodeMessage: type: object properties: source: type: object description: Information about the affected promotion codes. properties: type: type: string const: promotion_codes description: Indicates that the affected entity is a promotion code. codes: type: array description: A list of promotion codes that triggered the message. items: type: string example: spring2024 title: type: string description: A brief title summarizing the message. example: Duplicate code names description: type: string description: A detailed explanation of the message. example: Code names duplicated in other promotions PromotionCodeExportedFileResponse: type: object description: Successful response properties: href: type: string description: URL to download the CSV file. MaxUsesPerShopper: type: object description: Object for setting max uses per shopper. Only include this object, when you want to set limit per shopper. properties: max_uses: type: integer description: Sets max number of times the code can be used by a shopper. NOTE - This cannot be set with `per_application` consume unit. includes_guests: type: boolean default: false description: The flag to include guest shoppers for the discount with max use restriction. **If this field is provided, the max_uses value is required.** When set to `true`, guest shoppers must have an email associated with the cart to use the code. A guest cart without an email cannot use the code. When set to `false`, guest shoppers cannot use the promo code, even if the cart has an associated guest email. PromotionJob: type: object properties: job_type: description: The type of job to run. For example, `code_generate` to generate codes or `code_export` to export codes. type: string enum: - code_generate - code_export x-enumDescriptions: code_generate: Generates a batch of unique promotion codes with specified parameters such as code length, prefix, and usage limits. code_export: Exports all existing promotion codes for the promotion as a downloadable CSV file. name: type: string description: Represents the name of the job. The maximum allowed length is 50 characters. maxLength: 50 parameters: type: object properties: number_of_codes: type: integer description: Specifies the number of codes to be generated. maximum: 1000 max_uses_per_code: type: integer description: Specifies the maximum number of usages per code. If set to zero, you cannot use this promotion. If no value is set, it can be used unlimited times. consume_unit: type: string enum: - per_application - per_checkout description: | Specifies whether the promotion code is consumed per application or per checkout. This determines how usage limits are applied when a code is used multiple times. x-enumDescriptions: per_application: The code is consumed per application. For cart discounts, each application counts as one usage. For item discounts, each application to either a single quantity or a bundle is counted as one usage. per_checkout: The code is consumed once per checkout, regardless of the number of items in the cart or how many times the promotion is applied within that checkout. code_prefix: type: string description: Prefix for generated promotion codes (e.g., `SUMMER-`). code_length: type: integer description: Code length. maximum: 16 minimum: 8 default: 8 id: type: string description: A unique ID generated when a job is created. type: type: string const: promotion_job rule_promotion_id: description: A unique ID of a promotion. type: string PromotionJobsListResponse: type: object description: Successful response properties: data: type: array items: $ref: '#/components/schemas/PromotionJobResponse' links: $ref: '#/components/schemas/PaginationLinks' meta: $ref: '#/components/schemas/PaginationMeta' Response.Error: type: object properties: errors: type: array items: type: object properties: status: type: - string - integer description: HTTP status code. title: type: string description: Error title. detail: type: string description: Error details. source: type: string description: Source of the error (e.g., which field or parameter caused the error) meta: type: object properties: usage_ids: type: array items: type: string GenerateResult: type: object description: | Represents the result of a promotion job, including the number of generated and deleted promotion codes. - `generated`: Total number of successfully generated codes. - `deleted`: Number of codes that were deleted during job cancellation, if applicable. properties: generated: type: integer description: Number of successfully generated promotion codes. example: 1000 deleted: type: - integer - 'null' description: Number of codes deleted due to job cancellation. example: 50 ItemDiscount: type: object summary: Item Discount properties: strategy: type: string const: item_discount description: Applies a discount to particular items in the cart matching the supplied conditions. args: oneOf: - $ref: '#/components/schemas/FixedArg' - $ref: '#/components/schemas/PercentArg' - $ref: '#/components/schemas/FixedPriceQuantityArg' condition: $ref: '#/components/schemas/Condition' description: Specifies which items are eligible for the discount. Supports logical operations (and/or) and various item targeting strategies. limitations: type: object properties: max_discount: type: integer description: Specifies the maximum amount of discount applied to the shopping cart. max_quantity: type: integer description: Specifies the maximum quantity of each eligible item to which the promotion is applied. items: type: object properties: max_items: type: integer description: Specifies the maximum number of items eligible for the discount. max_units: type: integer minimum: 1 description: 'Specifies the maximum total quantity of units eligible for the discount across all selected items. Units are sorted by price before selection, defaulting to cheapest first. Use `price_strategy` to change the sort order. For example, with `max_units: 2` and `price_strategy: expensive`, the 2 most expensive units across all eligible items receive the discount, regardless of which SKUs they belong to.' price_strategy: type: string x-enumDescriptions: cheapest: The discount is applied to the cheapest item in the cart. expensive: The discount is applied to the most expensive item in the cart. enum: - cheapest - expensive description: Specifies the strategy for determining which items to discount based on their individual prices. auto_add: type: boolean description: 'This flag determines whether eligible items should be automatically added to the cart. This can only be set to `true` when the target item discount is 100% and the promotion is **automatic**. Otherwise, the API returns a validation error. NOTE: Item to be auto added should be from PXM catalog.' show_suggestions: type: boolean description: A flag indicating whether to show suggestions for eligible items in the cart if the item is not in the cart. CartDiscount: type: object summary: Cart Discount properties: strategy: type: string const: cart_discount description: Applies a discount across the entire cart. args: oneOf: - $ref: '#/components/schemas/FixedArg' - $ref: '#/components/schemas/PercentArg' condition: $ref: '#/components/schemas/Condition' description: Specifies which items are eligible for the cart-wide discount. Supports all item-based targeting strategies and logical operations. limitations: type: object properties: max_discount: type: integer description: Specifies the maximum amount of discount applied to the shopping cart. BundleDiscount: type: object summary: Items Bundle Discount properties: strategy: type: string const: items_bundle_discount description: Applies a discount to specific combinations of items purchased together. args: oneOf: - $ref: '#/components/schemas/FixedArg' - $ref: '#/components/schemas/PercentArg' - $ref: '#/components/schemas/FixedPriceArg' condition: $ref: '#/components/schemas/Condition' limitations: type: object properties: max_discount: type: integer description: Specifies the maximum amount of discount applied to the shopping cart. ShippingDiscount: type: object summary: Shipping Discount properties: strategy: type: string const: shipping_discount description: Applies a discount to the shipping costs on a cart args: oneOf: - $ref: '#/components/schemas/FixedArg' - $ref: '#/components/schemas/PercentArg' - $ref: '#/components/schemas/FixedPriceArg' condition: $ref: '#/components/schemas/Condition' description: Specifies which shipping types are eligible for the discount. Only shipping_type strategy is supported for shipping discounts. Condition: type: object discriminator: propertyName: strategy oneOf: - $ref: '#/components/schemas/AndCondition' - $ref: '#/components/schemas/OrCondition' - $ref: '#/components/schemas/ItemIdentifierCondition' - $ref: '#/components/schemas/ItemPriceCondition' - $ref: '#/components/schemas/ItemQuantityCondition' - $ref: '#/components/schemas/ItemCategoryCondition' - $ref: '#/components/schemas/ItemAttributeCondition' - $ref: '#/components/schemas/CartItemCustomAttributeCondition' - $ref: '#/components/schemas/ShippingTypeCondition' - $ref: '#/components/schemas/ItemsBundleCondition' AndCondition: type: object description: Logical AND condition requiring ALL child conditions to be satisfied. Useful for combining multiple targeting criteria in action conditions. properties: strategy: type: string const: and description: Logical AND strategy children: type: array items: $ref: '#/components/schemas/BaseCondition' OrCondition: type: object description: Logical OR condition requiring ANY child condition to be satisfied. Provides flexible targeting options in action conditions. properties: strategy: type: string const: or description: Logical OR strategy children: type: array items: $ref: '#/components/schemas/BaseCondition' description: Array of child conditions where ANY one can satisfy the requirement ItemIdentifierCondition: type: object description: Identifies specific items by SKU or Product ID for targeted discounting. This is the recommended approach for precise item targeting in action conditions. properties: strategy: type: string const: item_identifier description: Strategy for matching items by SKU or Product ID operator: type: string enum: - in - nin description: Whether items must match (in) or not match (nin) the specified identifiers args: type: array minItems: 1 maxItems: 1 items: type: object properties: skus: type: array items: type: string maxItems: 400 description: SKUs to match against cart items ids: type: array items: type: string format: uuid maxItems: 400 description: Product IDs to match against cart items additionalProperties: false description: Object containing arrays of identifiers to match children: type: array description: Optional nested conditions to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions. items: $ref: '#/components/schemas/CartItemCustomAttributes' ItemPriceCondition: type: object description: Price-based condition for targeting items based on their unit price. Allows filtering by price ranges using comparison operators. properties: strategy: type: string const: item_price description: Strategy for matching items by price operator: type: string enum: - gt - gte - lt - lte - eq - ne description: Comparison operator for price evaluation args: type: array minItems: 1 maxItems: 1 items: type: number minimum: 0 description: Price value for comparison (in minor currency units) ItemQuantityCondition: type: object description: Quantity-based condition for targeting items based on their cart quantity. Useful for bulk discount requirements or minimum quantity thresholds. properties: strategy: type: string const: item_quantity description: Strategy for matching items by quantity operator: type: string enum: - gt - gte - lt - lte - eq - ne description: Comparison operator for quantity evaluation args: type: array minItems: 1 maxItems: 1 items: type: number minimum: 0 description: Quantity value for comparison ItemCategoryCondition: type: object description: Category-based condition for targeting items by their category breadcrumbs (i.e., the [hierarchies or nodes](/docs/api/pxm/products/hierarchies) associated with the item). Matches against any category in the item's hierarchical category path. properties: strategy: type: string const: item_category description: Strategy for matching items by category operator: type: string enum: - in - nin x-enumDescriptions: in: The item hierarchy breadcrumbs must include the supplied value. nin: The item hierarchy breadcrumbs must **NOT** include the supplied value. description: Whether items must be in (in) or not in (nin) the specified categories args: type: array minItems: 1 maxItems: 400 items: type: string description: Category names to match against item breadcrumbs ItemAttributeCondition: type: object description: Attribute-based condition for targeting items by their custom attributes. Allows complex filtering based on product metadata and characteristics. properties: strategy: type: string const: item_attribute description: Strategy for matching items by attributes operator: type: string enum: - in - nin description: Whether items must have (in) or not have (nin) the specified attribute values x-enumDescriptions: in: The item attributes must include the supplied value nin: The item attributes must **NOT** include the supplied value. args: type: array minItems: 4 maxItems: 23 prefixItems: - type: string summary: The product template (e.g., `product(book)`) minLength: 1 maxLength: 255 - type: string summary: The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template). minLength: 1 maxLength: 255 - type: string summary: The [`field_type`](/docs/api/flows/fields) of the product template attribute. enum: - string - boolean - integer - float - date items: summary: The values to check (either match in the case of `in`, or exclude in the case of `nin`). type: - string - boolean - integer - number ShippingTypeCondition: type: object description: Shipping type condition for targeting discounts based on shipping method. Only supported in shipping discount actions. properties: strategy: type: string const: shipping_type description: Strategy for matching shipping types operator: type: string const: in description: Must match one of the specified shipping types args: type: array minItems: 1 maxItems: 400 items: type: string description: Shipping type identifiers to match against ItemsBundleCondition: type: object description: Bundle condition for targeting specific item combinations. Only supported in items bundle discount actions for defining required item groups. properties: strategy: type: string const: items_bundle description: Strategy for matching item bundles children: type: array items: $ref: '#/components/schemas/BaseCondition' description: Child conditions defining the required items in the bundle BaseCondition: type: object description: Specifies which items should be included or excluded when applying the discount. Can be based on factors such as item SKUs, product attributes, quantities, or categories. properties: strategy: type: string description: The condition strategy type (e.g., item_identifier, item_category, or) operator: type: string description: The evaluation operator for the condition args: type: array items: additionalProperties: true description: Arguments/values for the condition evaluation children: type: array description: Nested conditions for complex targeting requirements (level 1) items: type: object properties: strategy: type: string operator: type: string args: type: array items: additionalProperties: true children: type: array description: Nested conditions (level 2) items: type: object properties: strategy: type: string operator: type: string args: type: array items: additionalProperties: true children: type: array description: Nested conditions (level 3) items: type: object properties: strategy: type: string operator: type: string args: type: array items: additionalProperties: true And: type: object properties: strategy: type: string const: and description: Logical AND operator that requires ALL child conditions to be satisfied for the promotion to apply. Use when multiple criteria must be met simultaneously (e.g., minimum cart total AND specific customer segment). children: type: array items: type: object properties: strategy: type: string operator: type: string args: type: array items: additionalProperties: true children: type: array items: additionalProperties: true description: Array of child conditions that must ALL be satisfied. Or: type: object properties: strategy: type: string const: or description: Logical OR operator that requires ANY child condition to be satisfied for the promotion to apply. Provides flexible eligibility pathways, allowing multiple ways to qualify for a promotion. children: type: array items: type: object properties: strategy: type: string operator: type: string args: type: array items: additionalProperties: true children: type: array items: additionalProperties: true ItemSku: type: object properties: strategy: type: string const: item_sku description: Considers products by matching against their SKU. The `item_identifier` strategy is more flexible and recommended instead of this strategy. operator: type: string enum: - in - nin description: Specifies the operators used for the rule strategy. x-enumDescriptions: in: The sku must match the supplied values. nin: The sku must **NOT** match the supplied values. args: type: array items: type: string minItems: 1 maxItems: 400 description: 'The sku of the item to match, can be the sku of a [product](/docs/api/pxm/products/get-product) or a custom item. ' ItemIdentifier: type: object properties: strategy: type: string const: item_identifier description: Considers cart items matching by either SKU or Product ID. This strategy is preferred over `item_sku` and `item_product_id`, as it is more flexible. operator: type: string enum: - in - nin x-enumDescriptions: in: The product must match either the supplied `sku` or `ids`. nin: The product must **NOT** match either the supplied `sku` or `ids`. description: Specifies the operators used for the rule strategy. args: type: array minItems: 1 maxItems: 1 items: type: object properties: skus: type: array summary: List of SKUs to match maxItems: 400 items: type: string description: SKU identifiers for specific product variants. Supports both catalog and custom items. ids: type: array summary: List of Product IDs to match maxItems: 400 items: type: string format: uuid description: Product UUID identifiers for broader product targeting. Includes all variants of a product. additionalProperties: false children: type: array description: Optional nested rules to further refine item matching. Only `item_custom_attribute` strategies are allowed as children. When children are specified, items must match both the identifier (SKU/Product ID) AND all child conditions. items: $ref: '#/components/schemas/CartItemCustomAttributes' ItemProductId: type: object properties: strategy: type: string const: item_product_id description: |- Considers products by matching against their product ID. Can be used for items without a SKU like skuless bundles. The `item_identifier` strategy is more flexible and recommended instead of this strategy. operator: type: string enum: - in - nin description: Specifies the operators used for the rule strategy. x-enumDescriptions: in: The product must match the supplied values. nin: The product must **NOT** match the supplied values. args: type: array items: type: string format: uuid minItems: 1 maxItems: 400 description: The `id` of the [products](/docs/api/pxm/products/get-product) to match. ItemCategory: type: object properties: strategy: type: string const: item_category description: Considers the item categories (i.e., the [hierarchy or node](/docs/api/pxm/products/hierarchies)) associated with the item. For particular items, the check is against the node of that item, and all parent nodes. operator: type: string enum: - in - nin x-enumDescriptions: in: The product is in a node or a sub-node that matches one of the supplied values. nin: The product is **NOT** in a node or a sub-node that matches one of the supplied values. description: Specifies the operators used for the rule strategy. args: type: array items: type: string format: uuid minItems: 1 maxItems: 400 description: An array of `id` values for [nodes or hierarchies](/docs/api/pxm/products/get-hierarchy-node) children: type: array items: type: object properties: strategy: type: string operator: type: string args: type: array ItemAttribute: type: object properties: strategy: type: string const: item_attribute description: Considers the [Product Templates](/docs/api/pxm/products/extending-products-with-templates) associated with cart items. operator: type: string enum: - in - nin x-enumDescriptions: in: The value of the product template for the item must match one of the specified values. nin: The value of the product template for the item must **NOT** match one of the specified values. description: Specifies how the arguments are evaluated against the item. args: type: array minItems: 4 maxItems: 23 prefixItems: - type: string summary: The product template (e.g., `product(book)`) minLength: 1 maxLength: 255 - type: string summary: The [slug](/docs/api/flows/fields) in the product template (e.g., `isbn`, `condition` or another field associated with the template). minLength: 1 maxLength: 255 - type: string summary: The [`field_type`](/docs/api/flows/fields) of the product template attribute. enum: - string - boolean - integer - float - date items: summary: The values to check (either match in the case of `in`, or exclude in the case of `nin`). type: - string - boolean - integer - number children: type: array items: type: object properties: strategy: type: string operator: type: string args: type: array ItemPrice: type: object properties: strategy: type: string const: item_price description: Considers the price of items in the cart (after discount) operator: type: string enum: - gte - gt - lte - lt - eq description: Specifies the kind of restriction on the price. x-enumDescriptions: gte: The discounted value of the item must be greater than or equal to the value specified in `args` gt: The discounted value of the item must be greater than the value specified in `args` lte: The discounted value of the item must be less or equal to than the value specified in `args` lt: The discounted value of the item must be less than the value specified in `args` eq: The discounted value of the item must be equal to the value specified in `args` args: type: array minItems: 1 maxItems: 1 items: type: number description: The which we evaluate the rule against. children: type: array items: type: object properties: strategy: type: string operator: type: string args: type: array ItemQuantity: type: object properties: strategy: type: string const: item_quantity description: Considers the quantity of individual items. operator: type: string enum: - gte - gt - lte - lt - eq description: Specifies the kind of restriction on the quantity. x-enumDescriptions: gte: The quantity of the item must be greater than or equal to the value specified in `args`. gt: The quantity of the item must be greater than the value specified in `args`. lte: The quantity of the item must be less or equal to than the value specified in `args`. lt: The quantity of the item must be less than the value specified in `args`. eq: The quantity of the item must be equal to the value specified in `args`. When used with `items_bundle`, only this operator is valid. args: type: array minItems: 1 maxItems: 1 items: type: number summary: The value to check against the quantity of the item. (This is the value of `quantity` on a [Cart Item](https://elasticpath.dev/docs/api/carts/get-cart-items)). ItemsBundle: type: object properties: strategy: type: string const: items_bundle description: Matches multiple sets of conditions against distinct cart items. children: type: array items: type: object properties: strategy: type: string operator: type: string args: type: array children: type: array CartTotal: type: object properties: strategy: const: cart_total description: Considers the total value of items in the shopping cart. operator: type: string enum: - gte - gt - lte - lt - eq - range description: Specifies the kind of restriction on the total amount of the cart. x-enumDescriptions: gte: The total value of the cart must be greater than or equal to the value specified in `args` gt: The total value of the cart must be greater than the value specified in `args` lte: The total value of the cart must be less or equal to than the value specified in `args` lt: The total value of the cart must be less than the value specified in `args` eq: The total value of the cart must be equal to the value specified in `args` range: The total value of the cart must be between the first and second values specified in `args` (both inclusive) args: oneOf: - $ref: '#/components/schemas/CartTotalRangeArg' - $ref: '#/components/schemas/CartTotalArg' AccountTags: type: object properties: strategy: type: string const: account_tags description: Considers the tags of the account associated with the cart. operator: type: string x-enumDescriptions: contains_all: All tags must be present in the account. contains_any: At least one tag must be present in the account. not_contains_any: None of the specified tags must be present in the account (eligible if account has none of these tags). not_contains_all: All of the specified tags must not be present in the account (eligible if account is missing at least one tag). enum: - contains_all - contains_any - not_contains_any - not_contains_all description: Specifies how the arguments are evaluated against the account tags. args: type: array minItems: 1 maxItems: 25 items: type: string format: uuid description: The `id` of an account tag [Account Tag](/docs/api/accounts/list-account-tags) CartCustomAttributes: type: object properties: strategy: type: string const: cart_custom_attribute description: Considers custom attributes associated with the entire shopping cart. operator: type: string enum: - in - nin - eq - gt - lt - gte - lte x-enumDescriptions: in: The custom attribute on the cart must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical. nin: The custom attribute on the cart must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour. eq: The custom attribute on the cart must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value]. gt: The custom attribute on the cart must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value]. lt: The custom attribute on the cart must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value]. gte: The custom attribute on the cart must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]. lte: The custom attribute on the cart must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]. description: |- Specifies the restriction on cart custom_attributes for this rule promotion. **Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments args: type: array minItems: 3 maxItems: 22 description: |- Arguments for the cart custom attribute rule. The structure depends on the operator: - For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments prefixItems: - type: string pattern: ^[A-Za-z0-9_-]{1,255}$ description: The custom attribute key specified on the cart (in the `custom_attributes` field). - type: string description: The type of the custom attribute on the cart. enum: - string - boolean - integer - float items: description: The remaining arguments are specific values for the `custom_attributes` on a cart, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed. type: - string - boolean - integer - number CartItemCustomAttributes: type: object properties: strategy: type: string const: item_custom_attribute description: Considers custom attributes associated with individual cart items. operator: type: string enum: - in - nin - eq - gt - lt - gte - lte x-enumDescriptions: in: The custom attribute on the cart item must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical. nin: The custom attribute on the cart item must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour. eq: The custom attribute on the cart item must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value]. gt: The custom attribute on the cart item must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value]. lt: The custom attribute on the cart item must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value]. gte: The custom attribute on the cart item must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]. lte: The custom attribute on the cart item must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]. description: |- Specifies the restriction on cart item custom_attributes for this rule promotion. **Operator-Type Compatibility:** - `in` and `nin`: Support all types (string, boolean, integer, float). *Float matching is exact; floating-point precision can cause unexpected non-matches—use `gt`/`lt` for ranges when practical.* - `eq`: Supports string, boolean, and integer types with exactly 3 arguments - `gt` and `lt`: Support integer and float types with exactly 3 arguments - `gte` and `lte`: Support integer type only with exactly 3 arguments args: type: array minItems: 3 maxItems: 22 description: |- Arguments for the cart item custom attribute rule. The structure depends on the operator: - For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments prefixItems: - type: string pattern: ^[A-Za-z0-9_-]{1,255}$ description: The custom attribute key specified on the cart item (in the `attributes` field). - type: string description: The type of the custom attribute on the cart item. enum: - string - boolean - integer - float items: description: The remaining arguments are specific values for the `attributes` on a cart item, and should be of the same type specified in the second argument. For comparison operators (eq, gt, lt, gte, lte), only one value is allowed. type: - string - boolean - integer - number children: type: array items: type: object properties: strategy: type: string operator: type: string args: type: array description: Optional nested rules that further refine the cart item custom attribute condition. Cart item custom attribute rules can have children to create more complex conditions. CartTotalRangeArg: type: array summary: The total value of the cart. minItems: 1 maxItems: 1 items: type: number CartTotalArg: type: array summary: The minimum and maximum value of the cart, both are inclusive. minItems: 2 maxItems: 2 items: type: number FixedArg: type: array description: Apply a fixed discount to the amount. minItems: 2 maxItems: 2 prefixItems: - type: string const: fixed - type: integer minimum: 0 PercentArg: type: array description: Apply a percentage based discount to the amount. minItems: 2 maxItems: 2 prefixItems: - type: string const: percent - type: number minimum: 0 maximum: 100 CartItemCustomAttributeCondition: type: object description: Custom attribute-based condition for targeting cart items by their custom attributes. Allows complex filtering based on item-level custom metadata. properties: strategy: type: string const: item_custom_attribute description: Strategy for matching cart items by custom attributes operator: type: string enum: - in - nin - eq - gt - lt - gte - lte description: Operator for comparing custom attribute values x-enumDescriptions: in: The cart item custom attribute must match one of the values specified in arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact (equality); floating-point representation can cause unexpected non-matches—prefer `gt`/`lt` for numeric ranges where practical. nin: The cart item custom attribute must **NOT** match one of the values specified in the arguments. Supports all types with multiple values. **Note:** For type `float`, matching is exact; floating-point precision may lead to unexpected behaviour. eq: The cart item custom attribute must equal the specified value. Supports string, boolean, and integer types. Requires exactly 3 arguments [key, type, value]. gt: The cart item custom attribute must be greater than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value]. lt: The cart item custom attribute must be less than the specified value. Supports integer and float types. Requires exactly 3 arguments [key, type, value]. gte: The cart item custom attribute must be greater than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]. lte: The cart item custom attribute must be less than or equal to the specified value. Supports integer type only. Requires exactly 3 arguments [key, type, value]. args: type: array minItems: 3 maxItems: 22 description: |- Arguments for the cart item custom attribute condition. The structure depends on the operator: - For `in` and `nin`: [key, type, value1, value2, ...valueN] where N can be 1-20 values - For comparison operators (`eq`, `gt`, `lt`, `gte`, `lte`): [key, type, value] - exactly 3 arguments **Float with `in`/`nin`:** Matching uses exact equality. Floating-point representation can cause values that look equal (e.g. after arithmetic) to not match; use `gt`/`lt` for numeric ranges when possible. prefixItems: - type: string pattern: ^[A-Za-z0-9_-]{1,255}$ summary: The custom attribute key specified on the cart item minLength: 1 maxLength: 255 - type: string summary: The type of the custom attribute value enum: - string - boolean - integer - float items: summary: The values to check (either match in the case of `in`, or exclude in the case of `nin`, or compare in the case of comparison operators). type: - string - boolean - integer - number FixedPriceQuantityArg: type: array minItems: 3 maxItems: 3 description: Set the amount to this fixed value. prefixItems: - type: string const: fixed_price - type: integer description: quantity of eligible units to include in the fixed price assignment minimum: 1 - type: integer description: total assigned price minimum: 0 FixedPriceArg: type: array description: Set the amount to this fixed value. minItems: 2 maxItems: 2 prefixItems: - type: string const: fixed_price - type: integer minimum: 0 PaginationLinks: type: object properties: current: type: string format: uri description: URL for the current page of results first: type: string format: uri description: URL for the first page of results last: type: string format: uri description: URL for the last page of results next: type: string format: uri description: URL for the next page of results prev: type: string format: uri description: URL for the previous page of results PaginationMeta: type: object properties: page: type: object properties: current: type: integer description: Current page number limit: type: integer description: Number of items per page offset: type: integer description: Offset from the first result total: type: integer description: Total number of pages results: type: object properties: total: type: integer description: Total number of results total_method: type: string description: Method used to calculate the total (e.g., 'exact') PromotionJobResponse: allOf: - $ref: '#/components/schemas/PromotionJob' - type: object properties: status: description: The status of the job. type: string enum: - pending - processing - completed - failed - cancelling - cancelled x-enumDescriptions: pending: Commerce Cloud has received the request but is currently busy processing other requests. processing: Commerce Cloud has initiated processing the job. completed: The job is successfully completed. failed: The job has failed. cancelling: The job is currently in the process of being canceled. You need to wait for the cancellation process to complete. cancelled: The job request is canceled. error: description: The error encountered during job execution, if applicable. type: string meta: type: object properties: timestamps: type: object properties: created_at: description: The creation date of the job. type: string format: date-time updated_at: description: The last updated date of the job. type: string format: date-time result: $ref: '#/components/schemas/GenerateResult' securitySchemes: bearerAuth: type: http scheme: bearer parameters: Authorization: name: Authorization in: header description: The Bearer token required to get access to the API. required: true schema: type: string format: Bearer PageLimit: name: page[limit] description: The maximum number of records per page for this response. You can set this value up to 100. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used. in: query required: false schema: type: integer format: int64 minimum: 0 example: 100 PageOffset: name: page[offset] description: The current offset by number of records, not pages. Offset is zero-based. The maximum records you can offset is 10,000. If no page size is set, the [page length](/docs/commerce-cloud/global-project-settings/settings-overview#page-length) store setting is used. in: query required: false schema: type: integer format: int64 minimum: 0 maximum: 10000 example: 10