openapi: 3.1.0
info:
  version: 25.1126.6886238
  x-version-timestamp: 2025-11-26 19:10:23+00:00
  title: Addresses Introduction Account Addresses Rule Promotions API
  description: 'The Addresses API allows you to organize account addresses. Addresses are a sub-resource of `account` resources, an account can have multiple addresses, such as home, work, and neighbour.


    You can use an account address with either [client_credentials access token](/docs/api/authentication/create-an-access-token) or a combination of [implicit access token](/docs/api/authentication/create-an-access-token) and [Account Management authentication](/docs/api/accounts/post-v-2-account-members-tokens) token.

    '
  contact:
    name: Elastic Path
    url: https://www.elasticpath.com
    email: support@elasticpath.com
  license:
    url: https://elasticpath.dev
    name: MIT
servers:
- url: https://useast.api.elasticpath.com
  description: US East
- url: https://euwest.api.elasticpath.com
  description: EU West
security:
- BearerToken: []
tags:
- name: Rule Promotions
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. \nPromotions can apply fixed or percentage-based discounts, apply automatically or via codes, and have eligibility rules \nbased on product attributes, cart total, SKU conditions, custom attributes, and more.\n\nThis endpoint supports a variety of promotion types, such as:\n- **Cart-wide discounts**\n- **Item-specific discounts**\n- **Shipping discounts**\n- **Combinations thereof**\n\n:::note\n\nThe minimum item discount amount is zero, both for amounts and percentages.\n\nA store can have a maximum of **50 active and future automatic rule promotions**.\n\n:::\n"
      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, \nand configuration details. This endpoint supports filtering to refine results based on specific promotion attributes.\n\nUse query parameters to filter promotions by:\n- **Code** – Retrieve a specific promotion by its code.\n- **Promotion name** – Search for promotions by name.\n- **Activation status** – Filter by whether a promotion is active or not.\n- **Stackability** – Identify promotions that can or cannot be combined with others.\n- **Start and end dates** – Retrieve promotions based on their validity periods.\n"
      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.  \n\n\nThe following operators and attributes are available when filtering on this endpoint. See [Supported Filtering Characters](/guides/Getting-Started/filtering#supported-characters).\n\n| Attribute                 | Type               | Operator                     | Example                                                               |\n|:--------------------------|:-------------------|:-----------------------------|:----------------------------------------------------------------------|\n| `code`                    | `string`, `number` | `eq`                         | `eq(code,summer2024)`                                                 |\n| `name`                    | `string`           | `like`,`ilike`               | `ilike(name,'Summer *')`                                              |\n| `enabled`                 | `boolean`          | `eq`                         | `eq(enabled, true)`                                                   |\n| `stackable`               | `boolean`          | `eq`                         | `eq(stackable, true)`                                                 |\n| `override_stacking`       | `boolean`          | `eq`                         | `eq(override_stacking, true)`                                         |\n| `start`                   | `date`             | `lt`, `le`, `eq`, `gt`, `ge` | `gt(start, 2025-01-01T00:00:00.000Z)`                                 |\n| `end`                     | `date`             | `lt`, `le`, `eq`, `gt`, `ge` | `lt(end, 2025-01-01T00:00:00.000Z)`                                   |\n| `rule_set.rules.strategy` | `string`           | `eq`, `in`                   | `eq(rule_set.rules.strategy,account_tags)`                            |\n| `rule_set.rules.args`     | `string`           | `contains`                   | `contains(rule_set.rules.args, 11111111-1111-4111-1111-111111111111)` |\n| `account_tags`            | `string`           | `contains`                   | `contains(account_tags, 11111111-1111-4111-1111-111111111111)`              |\n\nSome notes about filters:\n1. The `code` filter is case-insensitive. You can search for codes using only `numbers` or codes containing both `string` and `numbers`.\n2. The `rule_set.rules.*` filters do not search child conditions at present        \n3. The `account_tags` filter will essentially search for any rule or child rule that has an `account_tags` strategy and the associated accounts.\n"
      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
components:
  parameters:
    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
    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
    Authorization:
      name: Authorization
      in: header
      description: The Bearer token required to get access to the API.
      required: true
      schema:
        type: string
        format: Bearer
  schemas:
    OrCondition:
      type: object
      description: 'Logical OR condition requiring ANY child condition to be satisfied. Only valid at the top level of a `cart_discount` action condition.

        The primary use case is combining cart-level strategies — for example, `or(cart_total gte 5000, cart_total lt 500)` to apply a discount when the cart total falls into one of multiple ranges.

        Children must all be the same level (all cart-level or all item-level). Mixing cart-level and item-level children is not allowed.

        For item-level targeting, prefer using `item_identifier` directly as the top-level condition rather than wrapping it in an `or`.'
      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
    RulePromotionResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/RulePromotionItem'
    CartTotalArg:
      type: array
      summary: The minimum and maximum value of the cart, both are inclusive.
      minItems: 2
      maxItems: 2
      items:
        type: number
    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)).
    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
    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
    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.
    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.
    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
    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)
    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.
    CartTotalCondition:
      type: object
      description: 'Cart total condition for gating a `cart_discount` action. The action is applied only when the cart total (or the total of a filtered subset of items) meets the threshold. When the condition passes, the discount applies to all cart items.

        **Placement rules:**

        - Valid as the top-level condition strategy. - Valid as a direct child of `and`/`or` (when all siblings are also cart-level). - **Not valid** inside item-level condition children.

        **Children (optional):** item-level strategies that filter which items count toward the total check. For example, a `cart_total(gte 10000)` with an `item_identifier` child means "apply this action if the total of matching items is at least $100". The discount itself still applies to all cart items once the gate passes.'
      properties:
        strategy:
          type: string
          const: cart_total
          description: Cart total condition strategy
        operator:
          type: string
          enum:
          - gte
          - gt
          - lte
          - lt
          - eq
          - range
          description: Comparison operator for the cart total threshold.
          x-enumDescriptions:
            gte: Cart total must be greater than or equal to the value in `args`
            gt: Cart total must be greater than the value in `args`
            lte: Cart total must be less than or equal to the value in `args`
            lt: Cart total must be less than the value in `args`
            eq: Cart total must be equal to the value in `args`
            range: Cart total must be between the first and second values in `args` (both inclusive)
        args:
          oneOf:
          - $ref: '#/components/schemas/CartTotalArg'
          - $ref: '#/components/schemas/CartTotalRangeArg'
        children:
          type: array
          description: Optional item-level conditions that filter which items count toward the total threshold check. Only leaf item strategies are allowed here — no `and`/`or` combinators and no nested `cart_total`.
          items:
            $ref: '#/components/schemas/BaseCondition'
      required:
      - strategy
      - operator
      - args
    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
    CartTotalRangeArg:
      type: array
      summary: The total value of the cart.
      minItems: 1
      maxItems: 1
      items:
        type: number
    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
    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
    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
    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'
    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
    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.
    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'
    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
    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
    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
    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.
    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'
    RulePromotionListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/RulePromotionItem'
        links:
          $ref: '#/components/schemas/PaginationLinks'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    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
    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.
    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. '
    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
    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'
    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
    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)
    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
    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
    AndCondition:
      type: object
      description: 'Logical AND condition requiring ALL child conditions to be satisfied. Only valid at the top level of an action condition.

        Children must all be the same level — either all item-level strategies (e.g. `item_sku`, `item_price`) or all cart-level strategies (e.g. `cart_total`). Mixing cart-level and item-level children is not allowed.'
      properties:
        strategy:
          type: string
          const: and
          description: Logical AND strategy
        children:
          type: array
          items:
            $ref: '#/components/schemas/BaseCondition'
    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')
    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
    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
    Condition:
      type: object
      description: "The condition that gates this action. When present, the action is applied only if the condition is satisfied.\n**Valid top-level strategies:**\n- `cart_total` — gates the action based on the cart total (or filtered item total).\n  Supported on `cart_discount` actions only.\n- `and` / `or` — logical combinators. Children must all be the same level (all\n  cart-level or all item-level). `and`/`or` is only valid at the top level.\n- Item-level strategies (`item_identifier`, `item_price`, `item_quantity`,\n  `item_category`, `item_attribute`, `item_custom_attribute`) — filter which\n  items the cart discount applies to.\n\n**Placement rules for `cart_total`:**\n- Valid at the top level or as a direct child of `and`/`or` (all-cart siblings). - Not valid inside item-level condition children."
      discriminator:
        propertyName: strategy
      oneOf:
      - $ref: '#/components/schemas/AndCondition'
      - $ref: '#/components/schemas/OrCondition'
      - $ref: '#/components/schemas/CartTotalCondition'
      - $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'
    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.
    FixedArg:
      type: array
      description: Apply a fixed discount to the amount.
      minItems: 2
      maxItems: 2
      prefixItems:
      - type: string
        const: fixed
      - type: integer
        minimum: 0
    RulePromotionItem:
      allOf:
      - $ref: '#/components/schemas/RulePromotionBaseAttributes'
      - $ref: '#/components/schemas/RulePromotionBaseRuleSetBaseAttributes'
  securitySchemes:
    BearerToken:
      type: http
      scheme: bearer