This endpoint allows you to create a new cart promotion. Cart promotions can be configured with different conditions, actions, and restrictions. You can define conditions based on cart subtotal, item counts, specific products, and tender types.

Example request

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmRvY2RlbW86MmQ1OTNZTk=' \
--header 'Cookie: _cfuvid=YpGNgiRLeLVURs3BaON5u5yvlKJ031kZrvv7e3ePAEc-1759774707339-0.0.1.1-604800000' \
--data '{
  "name": "Combo Product promotion ",
  "type": "CUSTOMER",
  "messageLabel": "Get 15% off combo products",
  "active": true,
  "priority": 0,
  "isStackable": false,
  "startDate": 1759363200000,
  "endDate": 1790985600000,
  "campaignId": "286038",
  "condition": {
    "type": "COMBO_PRODUCT",
    "comboProductCondition": {
      "productConditions": [
        {
          "kpi": "QUANTITY",
          "operator": "GREATER_THAN_OR_EQUAL",
          "value": "1.000000",
          "criteriaList": [
            {
              "entity": "SKU",
              "operator": "IN",
              "values": [
                "SKU001",
                "SKU002"
              ]
            }
          ]
        },
        {
          "kpi": "QUANTITY",
          "operator": "GREATER_THAN_OR_EQUAL",
          "value": "1.000000",
          "criteriaList": [
            {
              "entity": "BRAND",
              "operator": "IN",
              "values": [
                "BRAND_A"
              ]
            }
          ]
        }
      ]
    }
  },
  "action": {
    "type": "PRODUCT_BASED",
    "productBasedAction": {
      "type": "PERCENTAGE",
      "value": "15.000000",
      "productBasedCondition": {
        "type": "COMBO_PRODUCT",
        "comboProductCondition": {
          "productConditions": [
            {
              "kpi": "QUANTITY",
              "operator": "GREATER_THAN_OR_EQUAL",
              "value": "1.000000",
              "criteriaList": [
                {
                  "entity": "SKU",
                  "operator": "IN",
                  "values": [
                    "SKU001",
                    "SKU002"
                  ]
                }
              ]
            },
            {
              "kpi": "QUANTITY",
              "operator": "GREATER_THAN_OR_EQUAL",
              "value": "1.000000",
              "criteriaList": [
                {
                  "entity": "BRAND",
                  "operator": "IN",
                  "values": [
                    "BRAND_A"
                  ]
                }
              ]
            }
          ]
        }
      }
    }
  },
  "customerActivationRequired": true,
  "maxIssuancePerCustomer": 1,
  "promotionRestrictions": {
    "Promotion": [
      {
        "kpi": "REDEMPTION",
        "limit": "5000.000000"
      }
    ],
    "Customer": [
      {
        "kpi": "TRANSACTION",
        "frequency": "WEEKS",
        "minTimeBetweenRepeat": 604800000,
        "limit": "2.000000"
      },
      {
        "kpi": "DISCOUNT",
        "limit": "200.000000"
      },
      {
        "kpi": "REDEMPTION",
        "frequency": "DAYS",
        "minTimeBetweenRepeat": 86400000,
        "limit": "3.000000"
      }
    ],
    "Cart": [
      {
        "kpi": "DISCOUNT",
        "limit": "50.000000"
      }
    ]
  },
  "customFieldValues": {
    "Age": 25
  }
}'

API Quick Reference

{{https://eu.api.capillarytech.com/api_gateway/v1/promotions}}
   └─ {{promotions}}
      ├─ {{createCartPromotion}}({{CartPromotionRequest}}) -> {{CartPromotionResponse}}
      ├─ {{CartPromotionRequest}}
      │   ├─ {{Name}} (string)
      │   ├─ {{Type}} (enum)
      │   ├─ {{MessageLabel}} (string)
      │   ├─ {{Active}} (boolean)
      │   ├─ {{Priority}} (integer)
      │   ├─ {{IsStackable}} (boolean)
      │   ├─ {{StartDate}} (long)
      │   ├─ {{EndDate}} (long)
      │   ├─ {{CampaignId}} (string)
      │   ├─ {{Mode}} (enum)
      │   ├─ {{Condition}}
      │   │   ├─ {{ConditionType}} (enum)
      │   │   ├─ {{CartCondition}}
      │   │   │   ├─ {{CartKpi}} (enum)
      │   │   │   ├─ {{CartOperator}} (enum)
      │   │   │   └─ {{CartValue}} (number)
      │   │   ├─ {{TenderCondition}}
      │   │   │   └─ {{TenderModes}} []
      │   │   │       ├─ {{TenderType}} (string)
      │   │   │       ├─ {{TenderIdentifiers}} []
      │   │   │       └─ {{NestedCondition}} (Object)
      │   │   ├─ {{ProductCondition}}
      │   │   │   ├─ {{CriteriaList}} []
      │   │   │   │   ├─ {{Entity}} (string)
      │   │   │   │   ├─ {{EntityOperator}} (enum)
      │   │   │   │   └─ {{EntityValues}} []
      │   │   │   ├─ {{ProductKpi}} (enum)
      │   │   │   ├─ {{ProductOperator}} (enum)
      │   │   │   └─ {{ProductValue}} (string)
      │   │   ├─ {{ComboProductCondition}}
      │   │   │   └─ {{ProductConditions}} []
      │   │   │       ├─ {{ComboCriteriaList}} []
      │   │   │       ├─ {{ComboKpi}} (enum)
      │   │   │       ├─ {{ComboOperator}} (enum)
      │   │   │       └─ {{ComboValue}} (string)
      │   │   ├─ {{PaymentModeScopeConditionRO}}
      │   │   │   ├─ {{PaymentModeConditionRO}}
      │   │   │   │   └─ {{PaymentModeSelectionCriteriaRO}}
      │   │   │   │       ├─ {{SelectionOperator}} (enum)
      │   │   │   │       └─ {{SelectionValues}} []
      │   │   │   └─ {{ScopeCondition}} (Object)
      │   │   └─ {{PaymentComboProductConditionRO}}
      │   │       ├─ {{PaymentTenderCondition}} (Object)
      │   │       └─ {{PaymentComboProductCondition}} (Object)
      │   ├─ {{Action}}
      │   │   ├─ {{ActionType}} (enum)
      │   │   ├─ {{CartBasedAction}}
      │   │   │   ├─ {{CartActionType}} (enum)
      │   │   │   └─ {{CartActionValue}} (number)
      │   │   ├─ {{TenderBasedAction}}
      │   │   │   ├─ {{TenderActionType}} (enum)
      │   │   │   └─ {{TenderActionValue}} (string)
      │   │   ├─ {{ProductBasedAction}}
      │   │   │   ├─ {{ProductActionType}} (enum)
      │   │   │   ├─ {{ProductActionValue}} (number)
      │   │   │   ├─ {{IncludeItemsFromConditionSet}} (boolean)
      │   │   │   └─ {{ProductBasedCondition}}
      │   │   │       ├─ {{TargetType}} (enum)
      │   │   │       ├─ {{TargetProductCondition}} (Object)
      │   │   │       └─ {{TargetComboProductCondition}} (Object)
      │   │   ├─ {{FreeProductAction}}
      │   │   │   ├─ {{FreeIncludeItemsFromConditionSet}} (boolean)
      │   │   │   └─ {{FreeProductBasedCondition}} (Object)
      │   │   ├─ {{FixedPriceAction}}
      │   │   │   ├─ {{FixedPriceValue}} (number)
      │   │   │   ├─ {{FixedIncludeItemsFromConditionSet}} (boolean)
      │   │   │   └─ {{FixedProductBasedCondition}} (Object)
      │   │   └─ {{PerUnitAction}}
      │   │       ├─ {{PerUnitKpi}} (enum)
      │   │       ├─ {{PerUnitDivider}} (string)
      │   │       └─ {{RewardAction}}
      │   │           ├─ {{RewardActionType}} (enum)
      │   │           ├─ {{RewardProductBasedAction}} (Object)
      │   │           ├─ {{RewardFreeProductAction}} (Object)
      │   │           └─ {{RewardFixedPriceAction}} (Object)
      │   ├─ {{CustomerActivationRequired}} (boolean)
      │   ├─ {{MaxIssuancePerCustomer}} (integer)
      │   ├─ {{PromotionRestrictions}}
      │   │   ├─ {{PromotionLevel}} []
      │   │   │   ├─ {{RestrictionKpi}} (enum)
      │   │   │   ├─ {{RestrictionFrequency}} (enum)
      │   │   │   ├─ {{MinTimeBetweenRepeat}} (long)
      │   │   │   └─ {{RestrictionLimit}} (string)
      │   │   ├─ {{CustomerLevel}} []
      │   │   ├─ {{CartLevel}} []
      │   │   ├─ {{CodeLevel}} []
      │   │   └─ {{EarnLevel}} []
      │   ├─ {{CustomFieldValues}} (Object)
      │   ├─ {{IsLoyaltyOnly}} (boolean)
      │   ├─ {{EarningCriteria}}
      │   │   ├─ {{CriteriaActive}} (boolean)
      │   │   ├─ {{CriteriaDsl}} (string)
      │   │   ├─ {{CriteriaDslJson}} (string)
      │   │   ├─ {{CriteriaName}} (string)
      │   │   ├─ {{EarnedFromType}} (enum)
      │   │   ├─ {{EventType}} (enum)
      │   │   ├─ {{GroupId}} (integer)
      │   │   └─ {{MilestoneId}} (integer)
      │   ├─ {{MaxEarningPerCustomer}} (integer)
      │   ├─ {{StoreCriteria}}
      │   │   ├─ {{StoreType}} (enum)
      │   │   ├─ {{StoreValues}} []
      │   │   └─ {{StoreOperator}} (enum)
      │   ├─ {{TimeCriteria}}
      │   │   ├─ {{StartTime}} (string)
      │   │   ├─ {{DurationInHours}} (string)
      │   │   ├─ {{RepeatFrequency}} (enum)
      │   │   └─ {{WeeklyValues}} []
      │   └─ {{SupplementaryCriteria}}
      │       ├─ {{LoyaltyProgramId}} (integer)
      │       ├─ {{ProgramType}} (enum)
      │       └─ {{PartnerProgramId}} (integer)
      └─ {{CartPromotionResponse}}
          ├─ {{Data}}
          │   ├─ {{ResponseId}} (string)
          │   ├─ {{ResponseName}} (string)
          │   ├─ {{ResponseOrgId}} (integer)
          │   ├─ {{ResponseType}} (string)
          │   ├─ {{ResponseActive}} (boolean)
          │   ├─ {{CreatedBy}} (long)
          │   ├─ {{CreatedOn}} (long)
          │   └─ {{LastUpdatedOn}} (long)
          ├─ {{Errors}} []
          │   ├─ {{ErrorCode}} (integer)
          │   └─ {{ErrorMessage}} (string)
          └─ {{Warnings}} []
              └─ {{WarningMessage}} (string)

Prerequisites

Authentication: Basic or OAuth authentication.
Default access group

Body parameters

This table describes the top-level fields required to create any type of cart promotion.

Field	Type	Required	Description
name	String	Yes	Indicates a unique name of the cart promotion. Character limit: 1-50.
type	Enum	Yes	Specifies the type of cart promotion. Supported values are: • POS (Point of Sale): Applies automatically at checkout when cart or purchase conditions are met. Constrain: If a POS cart promotion is not restricted to loyal customers(isLoyaltyOnly is false), it cannot have Customer level restrictions. • CODE: Requires the customer to enter a cart promotion code for redemption. Constrain: Code cart promotions cannot have Customer level restrictions. They also require Code level restrictions to be present. • CUSTOMER: Targets specific customer segments or individuals based on attributes or behaviour. • EARNING: Grants rewards (such as points or benefits) when earning conditions are fulfilled. • REWARD: Offers a direct reward, such as a discount or complimentary item, upon meeting specific conditions.
messageLabel	String	Optional	Specifies a label for the cart promotion message. There is no character limit set for labels. Example: SummerSale2025.
active	Boolean	Yes	Indicates if the cart promotion is active. Supported values: true, false. Default value is true.
priority	Integer	Yes	Specifies the order in which cart promotions are applied. Lower numbers have higher priority, with 0 being the highest. Example: If there are three promotions—A (priority 0), B (priority 1), and C (priority 2), the order of application will be A, then B, then C. Note: If customerActivationRequired is enabled, the priority order does not apply until the customer activates the promotion.
isStackable	Boolean	Yes	Indicates whether this cart promotion can be used with other cart promotions. Supported values: true, false. Default: false.
startDate	Long	Yes	Specifies the date and time when the cart promotion becomes active, as a Unix epoch timestamp in milliseconds (UTC). Example: 1757388651000 corresponds to 2025-09-12 06:30:51 UTC. Note: This field will be deprecated in the future and is being replaced by `startDateISO`
startDateISO	String		Defines the date and time when the cart promotion becomes active in ISO 8601 format, including the region offset. For example: The start date is at 14:30:45 on December 16, 2025, in India. Format for the request parameter: 2025-12-16T14:30:45+05:30.
endDate	Long	Yes	Specifies the end date and time when the cart promotion expires, as a Unix epoch timestamp in milliseconds (UTC). Example: 1726123456789 corresponds to 2024-09-12 10:24:16 UTC. Note: This field will be deprecated in the future and is being replaced by `endDateISO`
endDateISO	String		Defines the end date and time when the cart promotion expires in ISO 8601 format, including the region offset.For example: The expiration date is at 14:30:45 on December 16, 2025, in India.Format for the request parameter:2025-12-16T14:30:45+05:30.
campaignId	String	Yes	Specifies the unique identifier of the campaign that the cart promotion is linked to. Example: 12345. There is no validation for the campaign ID.
mode	Enum	Optional	Specifies the application mode of the promotion. Supported values: `DISCOUNT` : A price reduction applied directly to items or the total cart during checkout. Example: A "Buy One, Get One Free" offer at Starbucks that applies when you add two eligible drinks to your order. `PAYMENT_VOUCHER` :A specific code with a fixed monetary value (e.g., ₹50) that a customer must enter to redeem its value against their bill. Example: Using a "ZOMATO50" voucher code on Zomato to get a flat ₹50 off the total food bill. if the field is omitted , it defaults to "DISCOUNT"
condition	Object	Yes	Specifies the rules that determine how the cart promotion applies.
..type	Enum	Yes	CART : Conditions based on the entire shopping cart's properties, like its total value or item count. Example: “Get $10 off when your subtotal is over $100.” TENDER : Conditions based on the customer's specific method of payment. Constrain: A TENDER condition must be paired with a TENDER action, and vice-versa. You cannot have a tender-based condition with a cart-based action. Example: “Receive 5% cashback when you pay with a Visa card.” COMBO_PRODUCT : Conditions based on the presence of multiple, specific products or product groups being purchased together. Example: “Buy a laptop and a mouse to get $50 off your total purchase.” PRODUCT : Conditions based on a specific group of products, evaluated by their quantity or total value. Example: “Buy at least two items from the 'Beverages' category to get 10% off.” PAYMENT_MODE_SCOPE: Conditions based on a specific payment method like points, cash being used in combination with a nested PRODUCT or CART condition. Example: "Get 50% off on a 'ChocoBrand' when you pay with Points. Constraints: The promotion's top-level mode must be DISCOUNT. The nested condition.type must be PRODUCT or CART. This condition cannot be paired with a simple CART_BASED action. It must use a product-focused action like PRODUCT_BASED or PER_UNIT. Note: This condition is for promotions like: "Pay with Points and get 50% off this specific item, not applicable for promotions like: "Pay with Points and get $5 off your total bill. PAYMENT_MODE_COMBO_PRODUCT: Conditions based on a specific payment method like points, card or cash being used in combination with a nested `COMBO_PRODUCT` condition. Example: "Buy a Coke and a 'ChocoBrand' and pay with Points to get 50% off a Maggi." Constrains: The promotion's top-level mode must be `DISCOUNT`. This condition cannot be paired with a simple `CART_BASED` action.It must use a product-focused action like `PRODUCT_BASED`, `FREE_PRODUCT`, `FIXED_PRICE`, or `PER_UNIT`. Note: This constraint means the promotion must reward the customer with a specific product, so an offer like "Buy a Burger + Fries and pay with Points to get a free Soda" is allowed, but an offer like "Buy a Burger + Fries and pay with Points to get $2 off your total bill" is not allowed because it gives a general discount on the whole cart. See the "Condition Objects" tables below for the full structure.
action	Object	Yes	Specifies what happens when the cart promotion is applied.
..type	Enum	Yes	Specifies the scope of the action when the cart promotion is applied. Supported values: • CART_BASED : Applies to the entire cart. • PRODUCT_BASED : Applies to specific items in the cart. • TENDER : Applies a discount based on payment method. Constrain: A TENDER condition must be paired with a TENDER action, and vice-versa. You cannot have a tender-based condition with a cart-based action. • PER_UNIT : Applies a discount for every X units.FREE_PRODUCT : Makes a specific item in the cart free of charge. • FIXED_PRICE : Changes the price of a specific item to a set amount. Constrain: If you use a FIXED_PRICE action, the associated condition must be a PRODUCT or COMBO_PRODUCT type. A CART or TENDER condition is not supported for this action. • FREE_PRODUCT: Makes a specific item in the cart free of charge. Constraint: The freeProductAction object requires a nested productBasedCondition to define which specific product (or group of products) is made free. This action is inherently product-focused and is used to target specific items. See the "Action Objects" tables below for the full structure.
customerActivationRequired	Boolean	Optional	Indicates if a customer must opt-in for a cart promotion before it can be redeemed. If true, the cart promotion is issued as `INACTIVE` and requires a customer action to become `ACTIVE`.
maxIssuancePerCustomer	Integer	Optional	Defines the total number of times this cart promotion can be issued to a single customer.
promotionRestrictions	Object	Optional	Defines usage limits on the cart promotion, grouped by level : `Customer`, `Cart`, `Promotion`, `Code` and `Earn`. See the "Promotion Restrictions Object" table below for the full structure.
customFieldValues	Object	Optional	Defines a key-value map for storing custom metadata. The structure is user-defined (e.g., {"key": "value"}).
isLoyaltyOnly	Boolean	Optional	Indicates if a POS promotion should apply only to identified loyalty members. Supported values: • `true`: The promotion applies only to loyalty customers. • `false`: The promotion applies to all customers (anonymous users). Constraint: This field is only valid when the `type` is `POS`.
earningCriteria	Object	Conditional	Defines the conditions for earning a reward. Required when the type is EARNING. See the "Earning Criteria Object" table below for the full structure.
maxEarningPerCustomer	Integer	Optional	Specifies the maximum number of times a customer can earn the reward from an EARNING type cart promotion.
storeCriteria	Object	Optional	Limits the promotion to specific stores, zones, or concepts. See the "Store Criteria Object" section for the full structure.
timeCriteria	Object	Optional	Restricts the promotion to specific days of the week or hours of the day. See the "Time Criteria Object" section for the full structure.
supplementaryCriteria	Object	Optional	Targets the promotion to customers in a specific loyalty tier or subscription program. See the "Supplementary Criteria Object" section for the full structure.

Condition Objects (Rules that determine how the cart promotion applies)

The condition object must contain a type field (CART, TENDER, or COMBO_PRODUCT) which determines its structure.

Cart promotion with the cart promotions condition type as `CART`

Field	Type	Required	Description
.cartCondition	Object	Yes	Defines rules that apply to the entire shopping cart.
..kpi	Enum	Yes	Metric to evaluate. Supported: `SUBTOTAL`,`ITEMCOUNT`.
..operator	Enum	Yes	Comparison operator. Supported: `EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`.
..value	Number	Yes	The number to compare against. Example: 250.

Example request

Requirement: The brand wants to set up a cart promotion, "Spend $100, Get $10 Off," with the condition that if the cart's subtotal is greater than or equal to $100, a fixed discount of $10 is applied to the entire cart.

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmRvY2RlbW86MmQ1OTNhAxMzU5NGIwNDllZTk=' \
--header 'Cookie: _cfuvid=5O_PtucI3YnfDUgjgMPnHbPeEKcKJjaHWDOkNDip3Po-1760116657904-0.0.1.1-604800000' \
--data '{
  "name": "Spend 100 Get 10 Off12",
  "orgId": 100737,
  "type": "CUSTOMER",
  "messageLabel": "Get $10 off on orders over $100!",
  "active": true,
  "priority": 0,
  "isStackable": false,
  "startDate": 1759363200000,
  "endDate": 1790985600000,
  "campaignId": "286039",
  "condition": {
    "type": "CART",
    "cartCondition": {
      "kpi": "SUBTOTAL",
      "operator": "GREATER_THAN_OR_EQUAL",
      "value": 100
    }
  },
  "action": {
    "type": "CART_BASED",
    "cartBasedAction": {
      "type": "ABSOLUTE",
      "value": 10
    }
  },
  "customerActivationRequired": true,
  "maxIssuancePerCustomer": 1,
  "promotionRestrictions": {},
  "customFieldValues": {}
}'

Cart promotion with the cart promotions condition type as `TENDER`

Field	Type	Required	Description
.tenderCondition	Object	Yes	Defines rules based on the customer's method of payment. You can use this to set a condition based on the payment type, such as Card, Cash or gift voucher.
..tenderModes	Array	Yes	Lists specific payment modes that trigger this condition.
...type	String	Yes	Specifies the payment category. Supported values: `CARD`, `CASH` , `PAYMENT_VOUCHER`.
...identifiers	Array	Conditional	The identifiers used for the `CARD` and `PAYMENT_VOUCHER` payment category.
..condition	Object	Yes	Defines an additional condition that must also be met for this rule to apply. Example - You want a cart promotion to apply only when a customer pays by card and the cart subtotal is greater than $500.
...type	Enum	Yes	Specifies the type of nested condition. Supported values: `CART`, `PRODUCT`.
...cartCondition	Object	Conditional	Defines rules based on specific products. Required when condition.type is `CART`. Example: You want a cart promotion to apply only when the customer pays by cash and buys at least 2 units of a specific product. Defines rules based on the overall cart, such as subtotal or item count. Example: Apply a $20 discount when the customer pays with a credit card and the cart subtotal ≥ $50.
....kpi	Enum	Yes	Defines the metric to evaluate the cart. Supported values: `SUBTOTAL`, `ITEMCOUNT`.
....operator	Enum	Yes	Defines how to compare the metric. Supported values: `EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`.
....value	Number	Yes	The number to compare against.
...productCondition	Object	Conditional	Defines rules based on specific products. Required when condition.type is `PRODUCT`. Example: Apply a $100 discount when the customer pays with a VISA card and buys at least 2 items from the “Paint Supplies” category.
....criteriaList	Array	Yes	Lists criteria that identify the products targeted by this condition.
....kpi	Enum	Yes	Specifies the product-level metric. Supported values: `NONE`, `QUANTITY` ,`AMOUNT`.
....operator	Enum	Conditional	Defines how to compare the product metric. Supported value: `EQUALS`.
....value	String	Conditional	Specifies the target value for the comparison. Supports up to 100 values in a single array.

Example request

Requirement: 1 The brand wants to set up a cart promotion, "Pay with VISA, Get $20 Off on Orders Above $100," with conditions that if a customer's cart subtotal is greater than or equal to $100 AND they pay with a VISA card, an absolute discount of $20 is applied.

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Cookie: _cfuvid=9769067-0.0.1.1-604800000; _cfuvid=5O_PtucI3YnfDUgjgMPnHbPeEKcKJjaHWDOkNDip3Po-1760116657904-0.0.1.1-604800000' \
--header 'Authorization: Basic Z2VvcmdlLmRvY2RlbW86MmQ1OTNhMjI2MTk1OGE2NWI5ZjAxMzU5NGIwNDllZTk=' \
--data '{
  "name": "Cash Discount on Paint Supplies5",
  "orgId": 100737,
  "type": "CUSTOMER",
  "messageLabel": "Pay with Cash and Get $5 Off Paint Supplies",
  "active": true,
  "priority": 0,
  "isStackable": false,
  "startDate": 1759363200000,
  "endDate": 1790985600000,
  "campaignId": "286039",
  "condition": {
    "type": "TENDER",
    "tenderCondition": {
      "tenderModes": [
        {
          "type": "CASH"
        }
      ],
      "condition": {
        "type": "PRODUCT",
        "productCondition": {
          "criteriaList": [
            {
              "entity": "CATEGORY",
              "values": [
                "Paint Supplies"
              ],
              "operator": "IN"
            }
          ],
          "kpi": "QUANTITY",
          "operator": "GREATER_THAN_OR_EQUAL",
          "value": "1"
        }
      }
    }
  },
  "action": {
    "type": "TENDER",
    "tenderBasedAction": {
      "type": "ABSOLUTE",
      "value": "5"
    }
  },
  "customerActivationRequired": false,
  "maxIssuancePerCustomer": 1,
  "promotionRestrictions": {},
  "customFieldValues": {}
}'

Requirement 2: The brand wants to set up a cart promotion, "Pay with Cash, Get $5 Off Paint Supplies," with conditions that if a customer buys at least one item from the "Paint Supplies" category AND they pay with cash, an absolute discount of $5 is applied.

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmRvY2RlbW86MmQ1OMzU5NGIwNDllZTk=' \
--header 'Cookie: _cfuvid=5O_PtucI3YnfDUgjgMPnHbPeEKcKJjaHWDOkNDip3Po-1760116657904-0.0.1.1-604800000' \
--data '{
  "name": "Cash Discount on Paint Supplies21",
  "orgId": 100737,
  "type": "CUSTOMER",
  "messageLabel": "Pay with Cash and Get $5 Off Paint Supplies",
  "active": true,
  "priority": 0,
  "isStackable": false,
  "startDate": 1759363200000,
  "endDate": 1790985600000,
  "campaignId": "286039",
  "condition": {
    "type": "TENDER",
    "tenderCondition": {
      "tenderModes": [
        {
          "type": "CASH"
        }
      ],
      "condition": {
        "type": "PRODUCT",
        "productCondition": {
          "criteriaList": [
            {
              "entity": "CATEGORY",
              "values": [
                "Paint Supplies"
              ],
              "operator": "IN"
            }
          ],
          "kpi": "QUANTITY",
          "operator": "GREATER_THAN_OR_EQUAL",
          "value": "1"
        }
      }
    }
  },
  "action": {
    "type": "TENDER",
    "tenderBasedAction": {
      "type": "ABSOLUTE",
      "value": "5"
    }
  },
  "customerActivationRequired": false,
  "maxIssuancePerCustomer": 1,
  "promotionRestrictions": {},
  "customFieldValues": {}
}'

Requirement 3: The brand has previously issued a specific set of high-value gift vouchers (e.g., "Holiday Bonus Vouchers") to select customers. For the redemption of these specific vouchers, they want to run a special promotion. The condition is: if a customer pays using one of these specific "Holiday Bonus Vouchers" (identified by its unique ID), the system will apply an additional $100 absolute discount to their transaction.

Example Payload

{
  "name": "Gift voucher promotion test 5",
  "orgId": 100458,
  "type": "REWARD",
  "messageLabel": "Gift voucher test",
  "active": true,
  "priority": 0,
  "isStackable": false,
  "startDate": 1761105600000,
  "endDate": 1764565199999,
  "campaignId": "286039",
  "condition": {
    "type": "TENDER",
    "tenderCondition": {
      "tenderModes": [
        {
          "type": "PAYMENT_VOUCHER",
          "identifiers": [
            "68f73e2d4a314550c4b458a3"
          ]
        }
      ]
    }
  },
  "action": {
    "type": "TENDER",
    "tenderBasedAction": {
      "type": "ABSOLUTE",
      "value": "100"
    }
  },
  "customerActivationRequired": false,
  "maxIssuancePerCustomer": 1,
  "maxEarningPerCustomer": 100,
  "promotionRestrictions": {},
  "customFieldValues": {}
}

Requirement 4: The brand wants to offer a special redemption rate for loyalty members. The promotion is: "Redeem 2 KitKat items for only 200 points (usual 400 points)." This special rate is only triggered if the customer has chosen to pay using "Points" as their payment method.

Example Payload

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmJ1a2w6NzYzN4ZjY3MmNhZjY1ZmY=' \
--header 'Cookie: _cfuvid=mhzUbsb0moSA\vZgzvXzivXm5uY-1761199170391-0.0.1.1-604800000' \
--data '{
  "name": "Preferential Redemption - KitKat Bundle",
  "orgId": 100458,
  "type": "REWARD",
  "messageLabel": "Special Offer: 2 KitKats for 200 Points!",
  "active": true,
  "priority": 0,
  "isStackable": false,
  "startDate": 1759363200000,
  "endDate": 1790985600000,
  "campaignId": "293076",
  "condition": {
    "type": "TENDER",
    "tenderCondition": {
      "tenderModes": [
        {
          "type": "CARD",
          "identifiers": [
            "Points"
          ]
        }
      ],
      "condition": {
        "type": "PRODUCT",
        "productCondition": {
          "criteriaList": [
            {
              "entity": "SKU",
              "values": [
                "KITKAT_SKU"
              ],
              "operator": "IN"
            }
          ],
          "kpi": "QUANTITY",
          "operator": "GREATER_THAN_OR_EQUAL",
          "value": "2"
        }
      }
    }
  },
  "action": {
    "type": "TENDER",
    "tenderBasedAction": {
      "type": "ABSOLUTE",
      "value": "200"
    }
  },
  "customerActivationRequired": false,
  "maxIssuancePerCustomer": 10,
  "promotionRestrictions": {},
  "customFieldValues": {}
}'

Cart promotion with the cart promotions condition type as `COMBO_PRODUCT`

Field	Type	Required	Description
.comboProductCondition	Object	Yes	Defines rules that require specific product combinations to qualify for the cart promotion. Example: A customer must buy one brush and one tube of Brand A toothpaste.
..productConditions	Array	Yes	List of product condition objects. All listed conditions must be met for the cart promotion to apply. The maximum number of product conditions that you can set is 100.
...kpi	Enum	Yes	Metric used to evaluate each condition. Supported values: `NONE`, `QUANTITY`, `AMOUNT`. QUANTITY checks how many qualifying products are in the cart.
...operator	Enum	Conditional	Comparison logic for evaluating the metric. Supported values: `EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`.
...value	String	Conditional	Target value for the comparison. The value should be in number. If kpi is `QUANTITY`, operator is `GREATER_THAN_OR_EQUAL`, and value is 2, the condition applies when the cart contains two or more qualifying products.
...criteriaList	Array	Yes	Defines which products or attributes are part of the condition. Example: Products where entity = PRODUCT_NAME and values = ["Paint Brush"].
....entity	String	Yes	Product attribute to evaluate. Example: `PRODUCT_NAME`, `BRAND`, or `CATEGORY`. This should match with the line item names in the Add Transaction API payload.
....operator	Enum	Yes	Defines how attribute values are compared. Supported values: `IN`, `NOT_IN`. Example: IN checks if the product belongs to the specified brand or category.
....values	Array	Yes	List of attribute values to match against the entity.

Example request

Requirement: The brand wants to set up a cart promotion, "Buy a Burger and Fries, Get 15% Off," with conditions that if a customer's cart contains at least one item from the "Burgers" category AND at least one item from the "Fries" category, a 15% discount is applied to those specific items.

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmRvY22NWI5ZjAxMzU5NGIwNDllZTk=' \
--header 'Cookie: _cfuvid=5O_PtucI3YnfcKJjaHWDOkNDip3Po-1760116657904-0.0.1.1-604800000' \
--data '{
  "name": "Burger and Fries Combo Discount",
  "orgId": 100737,
  "type": "CUSTOMER",
  "messageLabel": "Get 15% off our Burger and Fries Combo!",
  "active": true,
  "priority": 0,
  "isStackable": false,
  "startDate": 1759363200000,
  "endDate": 1790985600000,
  "campaignId": "286039",
  "condition": {
    "type": "COMBO_PRODUCT",
    "comboProductCondition": {
      "productConditions": [
        {
          "kpi": "QUANTITY",
          "operator": "GREATER_THAN_OR_EQUAL",
          "value": "1",
          "criteriaList": [
            {
              "entity": "CATEGORY",
              "operator": "IN",
              "values": [
                "Burgers"
              ]
            }
          ]
        },
        {
          "kpi": "QUANTITY",
          "operator": "GREATER_THAN_OR_EQUAL",
          "value": "1",
          "criteriaList": [
            {
              "entity": "CATEGORY",
              "operator": "IN",
              "values": [
                "Fries"
              ]
            }
          ]
        }
      ]
    }
  },
  "action": {
    "type": "PRODUCT_BASED",
    "productBasedAction": {
      "type": "PERCENTAGE",
      "value": "15.00",
      "productBasedCondition": {
        "type": "COMBO_PRODUCT",
        "comboProductCondition": {
          "productConditions": [
            {
              "kpi": "QUANTITY",
              "operator": "GREATER_THAN_OR_EQUAL",
              "value": "1",
              "criteriaList": [
                {
                  "entity": "CATEGORY",
                  "operator": "IN",
                  "values": [
                    "Burgers"
                  ]
                }
              ]
            },
            {
              "kpi": "QUANTITY",
              "operator": "GREATER_THAN_OR_EQUAL",
              "value": "1",
              "criteriaList": [
                {
                  "entity": "CATEGORY",
                  "operator": "IN",
                  "values": [
                    "Fries"
                  ]
                }
              ]
            }
          ]
        }
      }
    }
  },
  "customerActivationRequired": true,
  "maxIssuancePerCustomer": 1,
  "promotionRestrictions": {},
  "customFieldValues": {}
}'

Cart promotion with the cart promotion's condition type as PRODUCT

This condition type triggers a cart promotion based on the presence, quantity, or total value of specific products or product groups within the cart.

Field	Type	Required	Description
.productCondition	Object	Yes	Defines rules that apply to specific products in the shopping cart.
..criteriaList	Array	Yes	Defines the specific products that must be present in the cart to satisfy the condition.
...entity	String	Yes	The product attribute to evaluate. Supported values: `SKU:` The unique product code used internally to track a specific item (Stock Keeping Unit). `BRAND`: The name of the manufacturer. `ATTRIBUTE`: A custom property or characteristic of the product not covered by SKU, Brand, or Category, Eg. 'Color: Red' or 'Material: Leather'. `CATEGORY`: The classification or group the product belongs to, Eg. 'Detergents' or 'Outerwear'.
...operator	Enum	Yes	Defines how attribute values are compared. Supported values: `IN`: Specifies that an attribute's value must match one of the values provided in a list `NOT_IN`: Specifies that an attribute's value must not match any of the values provided in a list. For example, buy a Nike or Puma shoes to get 50% off on your purchase.
...values	Array	Yes	List of attribute values to match against the entity. Supports up to 100 values in a single array.
..kpi	Enum	Yes	Specifies the metric used to evaluate the matching products. `NONE`: Used when the condition focuses only on the presence of a specific product type, without requiring a minimum quantity or value check. `QUANTITY`: Used when the condition evaluates the number of units of the qualifying product in the cart. `AMOUNT`: Used when the condition evaluates the total monetary value of the qualifying product in the cart.
..operator	Enum	Conditional	Comparison logic for the metric. Supported values: `EQUALS`: The metric must be the same value as the target set in the rule. `GREATER_THAN`: The metric must be more than the value set in the rule. `GREATER_THAN_OR_EQUAL`: The metric must be the same value or more than the target set in the rule.
..value	String	Conditional	Target value for the comparison. Required if `kpi` is not `NONE`.

Requirement: The brand wants to set up a cart promotion, "Buy 2 'Paint Supplies', Get $15 Off Your Order," with the condition that if the cart contains at least two items from the "Paint Supplies" category, a fixed discount of $15 is applied to the entire cart.

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmRW86Mm5ZjAxMzU5NGIwNDllZTk=' \
--header 'Cookie: _cfuvid=5O_PtucI3YnHbPip3Po-1760116657904-0.0.1.1-604800000' \
--data '{
    "name": "Buy 2 Paint Supplies Get 15 Off",
    "type": "CUSTOMER",
    "messageLabel": "Get $15 off when you buy two paint supplies!",
    "active": true,
    "priority": 0,
    "isStackable": false,
    "startDate": 1759363200000,
    "endDate": 1790985600000,
    "campaignId": "286039",
    "condition": {
        "type": "PRODUCT",
        "productCondition": {
            "criteriaList": [
                {
                    "entity": "CATEGORY",
                    "operator": "IN",
                    "values": [
                        "Paint Supplies"
                    ]
                }
            ],
            "kpi": "QUANTITY",
            "operator": "GREATER_THAN_OR_EQUAL",
            "value": "2"
        }
    },
    "action": {
        "type": "CART_BASED",
        "cartBasedAction": {
            "type": "ABSOLUTE",
            "value": 15
        }
    },
    "customerActivationRequired": false,
    "maxIssuancePerCustomer": 1,
    "promotionRestrictions": {},
    "customFieldValues": {}
}'\'''

Cart promotion with condition type `PAYMENT_MODE_SCOPE`

This condition type combines payment using Points with a product or cart condition that will trigger the promotion benefits. For example, "Pay with 50 points to get 60% off on ChocoBrand biscuit".

Field	Type	Required	Description
.paymentModeScopeConditionRO	Object	Yes	Defines the main container object for a payment condition.
..paymentModeConditionRO	Object	Yes	Defines the specific payment method rules that will trigger the promotion.
...paymentModeSelectionCriteriaRO	Object	Yes	Specifies the specific criteria for selecting the payment mode. Example : "paymentModeSelectionCriteriaRO": `{` "operator": "IN", "values": `[` `{` "type": "CARD", "identifiers": `[`"POINTS`]`
....operator	Enum	Yes	Indicates the logical operator for the values list. Supported values: `IN`: Contains at least one item from the specified values. `NOT_IN`: Does not contain item from the specified values. For example, the cart must contain either "Nike shoes" OR "Adidas shoes".
....values	Array	Yes	Defines an array of payment mode objects that are allowed.
.....type	String	Yes	Specifies the category of the payment method. Supported: `CARD`. `CARD` is always used as a payment type when the payment method is Points.
.....identifiers	Array	Yes	Specifies the payment identifier. Supported: `POINTS`
..condition	Object	Yes	Indicates a standard subcondition /nested condition that must also be met for the promotion to be applied.
...type	Enum	Yes	Defines the type of the nested condition. Supported: `PRODUCT`: Condition is based on a specific product. `CART`: Condition is based on a specific product. For example, pay with points and purchase a "Nike" shoes to get 50% off.
...productCondition	Object	Conditional	Specifies the product condition details. Required if the condition type is `PRODUCT`.
....criteriaList	Array	Yes	Defines the specific products that must be in the cart to satisfy the condition. Example: "criteriaList": `[` `{` "entity": "SKU", "operator": "IN", "values": `[` "'ChocoBrand'"`]`
.....entity	String	Yes	Specifies the product attribute to evaluate. Supported values: `SKU`: The unique product code used internally to track a specific item (Stock Keeping Unit). `BRAND`: The trademarked name of the manufacturer or collection associated with the product. `ATTRIBUTE`: A custom property or characteristic of the product not covered by SKU, Brand, or Category Eg., 'Color: Red' or 'Material: Leather'. `CATEGORY`: The classification or group the product belongs to Eg., 'Detergents' or 'Outerwear'.
.....operator	Enum	Yes	Defines how attribute values are compared. Supported values: `IN`: Contains at least one item from the specified values. `NOT_IN`: Does not contain item from the specified values. For example, the cart must contain either "Nike shoes" OR "Adidas shoes".
.....values	Array	Yes	Defines values to match against the product. Example:`[ "ChocoBrand"]` Supports up to 100 values in a single array.
....kpi	Enum	Yes	Defines the metric used to evaluate the matching products. Supported: `NONE`, `QUANTITY`, `AMOUNT`.
....operator	Enum	Conditional	Defines the comparison logic for the metric. Required if KPI is not NONE. Supported: `EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`.
....value	Number	Conditional	Specifies the target value for the comparison. Required if KPI is not `NONE`.
...cartCondition	Object	Conditional	Defines the cart condition details. Required if ..condition.type is `CART`.
....kpi	Enum	Yes	Defines the metric to evaluate the entire cart. Supported: `SUBTOTAL`: Total sum value of the items in the cart , `ITEMCOUNT`: Total number of items in the cart.
....operator	Enum	Yes	Indicates the comparison operator. Supported: `EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`.
....value	Number	Yes	Specifies the number to compare the cart's KPI against.

Requirement: A convenience store wants to set up a code-based promotion: "Use code SAVE50, Get 50% Off on 'ChocoBrand' cake when paying with Points".

{
    
    "name": "CODE: POINTS Payment + Oreo → 50% Off",
    "orgId": 50672,
    "priority": 5,
    "active": true,
    "messageLabel": "test!!",
    "type": "CODE",
    "condition": {
        "type": "PAYMENT_MODE_SCOPE",
        "paymentModeScopeConditionRO": {
            "paymentModeConditionRO": {
                "paymentModeSelectionCriteriaRO": {
                    "operator": "IN",
                    "values": [
                        {
                            "type": "CARD", //check this
                            "identifiers": [
                                "POINTS"
                            ]
                        }
                    ]
                }
            }
            ,
            "condition": {
                "type": "PRODUCT",
                "productCondition": {
                    "criteriaList": [
                        {
                            "entity": "SKU",
                            "operator": "IN",
                            "values": [
                                "ChocoBrand"
                            ]
                        }
                    ],
                    "kpi": "QUANTITY",
                    "value": 1.000000,
                    "operator": "GREATER_THAN_OR_EQUAL"
                }
            }
        }
    },
    "action": {
        "type": "PRODUCT_BASED",
        "productBasedAction": {
            "type": "PERCENTAGE",
            "value": 50.000000,
            "includeItemsFromConditionSet": false
        }
    },
    "createdBy": 1234,
    "createdOn": 1761670118230,
    "lastUpdatedBy": 1234,
    "lastUpdatedOn": 1761670118230,
    "startDate": 1761497318230,
    "endDate": 1762104742000,
    "campaignId": 2013,
    "promotionRestrictions": {
        "Code": [
            {
                "kpi": "REDEMPTION",
                "limit": 100.000000
            }
        ]
    },
    "earnLimitedToSpecificAudience": false,
    "customFieldValues": {
        "f1": "v1",
        "f2": "v2"
    },
    "mode": "DISCOUNT",
    "maxIssuancePerCustomer": 1,
    "isStackable": false
}

Cart promotion with condition type `PAYMENT_MODE_COMBO_PRODUCT`

Field	Type	Required	Description
.paymentComboProductConditionRO	Object	Yes	Specifies the main container object for a payment based combo condition.
..tenderCondition	Object	Yes	Defines the specific payment method rules required to trigger the promotion.
...paymentModeSelectionCriteriaRO	Object	Yes	Specifies the criteria for selecting the payment mode.
....operator	Enum	Yes	Indicates the logical operator for the values list. Supported values: `IN`: The promotion applies if the customer pays with points. `NOT_IN`: The promotion applies if the customer pays with any method other than points. Eg. Paying with "Cash" instead of "Points".
....values	Array	Yes	Defines an array of payment mode objects to check against.
.....type	String	Yes	Specifies the category of the payment method. Supported values: `CARD`: A non-cash payment type, which is always used to represent the identifier "Points".
.....identifiers	Array	Yes	Defines the specific payment identifiers. Supported value: `POINTS`.
..comboProductCondition	Object	Yes	Defines the combo product condition. All product conditions listed inside must be fulfilled for the promotion to be triggered Example: The customer must buy both a "Burger" AND "Fries".
...productConditions	Array	Yes	Defines the list of product rules that make up the combo. Each object in this list is one part of the combo.
....criteriaList	Array	Yes	Defines the specific products that must be in the cart for this part of the combo. Example: "criteriaList": `[` `{` "entity": "SKU", "operator": "IN", "values": `[` "ChocoBrand"`]`
.....entity	String	Yes	Specifies the product attribute to evaluate. Supported values:
.....operator	Enum	Yes	Defines how attribute values are compared. Supported values: `IN`: The item's entity must be in this list of values `NOT_IN`: The item's entity must not be in this list of values.
.....values	Array	Yes	Defines an array of user-defined strings to match against the entity. Supports up to 100 values in a single array. Example: `[`"SKU-123"`]`, `[`"Large Fries"`]`.
....kpi	Enum	Yes	Specifies the metric used to evaluate the matching products for this combo part. Supported values: `NONE`: Checks only for the presence of the item, not its quantity or value. `QUANTITY`: Checks the number of units of the item. `AMOUNT`: Checks the total value of the items.
....operator	Enum	Conditional	Indicates the comparison logic for the kpi. Required if kpi is not `NONE`. Supported values: `EQUALS`: The KPI must exactly match the value. `GREATER_THAN`: The KPI must be more than the value. `GREATER_THAN_OR_EQUAL`: The KPI must be at least the set value.
....value	Number	Conditional	Specifies the target value for the comparison. Required if kpi is not NONE.

Requirement: A convenience store wants to set up a POS promotion, "Buy Coke & ChocoBrand biscuit with Points payment mode, and get 50% off on Maggi noodles." The condition is that if a customer's cart contains at least $2 worth of Coke and at least $1 worth of ChocoBrand biscuits (the combo), and they pay using points, a 50% discount is applied to the Maggi noodle item(s).

{
    "name": "POINTS Payment Combo: Coke+ChocoBrand → 50% off Maggi",
    "type": "POS",
    "mode": "DISCOUNT",
    "campaignId": "286039",
    "condition": {
        "type": "PAYMENT_MODE_COMBO_PRODUCT",
        "paymentComboProductConditionRO": {
            "tenderCondition": {
                "paymentModeSelectionCriteria": {
                    "operator": "IN",
                    "values": [
                        {
                            "type": "CARD",
                            "identifiers": ["POINTS"]
                        }
                    ]
                }
            },
            "comboProductCondition": {
                "productConditions": [
                    {
                        "criteriaList": [
                            {
                                "entity": "SKU",
                                "operator": "IN",
                                "values": ["COKE"]
                            }
                        ],
                        "kpi": "AMOUNT",
                        "value": 2,
                        "operator": "GREATER_THAN_OR_EQUAL"
                    },
                    {
                        "criteriaList": [
                            {
                                "entity": "SKU",
                                "operator": "IN",
                                "values": ["ChocoBrand"]
                            }
                        ],
                        "kpi": "AMOUNT",
                        "value": 1,
                        "operator": "GREATER_THAN_OR_EQUAL"
                    }
                ]
            }
        }
    },
    "action": {
        "type": "PRODUCT_BASED",
        "productBasedAction": {
            "productBasedCondition": {
                "type": "PRODUCT",
                "productCondition": {
                    "criteriaList": [
                        {
                            "entity": "SKU",
                            "operator": "IN",
                            "values": ["MAGGI"]
                        }
                    ],
                    "kpi": "AMOUNT",
                    "value": 0,
                    "operator": "GREATER_THAN"
                }
            },
            "type": "PERCENTAGE",
            "value": 50,
            "includeItemsFromConditionSet": false
        }
    }
}

**Note **

A PRODUCT condition checks for one set of products that meet a single criteria.
A COMBO_PRODUCT condition checks for multiple, distinct sets of products that must all be present in the cart together.

Action Objects (specifies what happens when the cart promotion is applied)

The action object defines what happens when a cart promotion’s condition is met. In simple terms:

Condition = When does the offer apply?
Action = What benefit does the customer get?

Concept	Purpose	Example
condition	Specifies the trigger criteria for the cart promotion.	When the cart subtotal is ₹1,000 or more.
action	Specifies the reward action or benefit once the condition is satisfied.	Apply a ₹200 discount.

Action Types and Scenarios

1. CART_BASED

Applies a discount to the entire shopping cart when a cart-level condition is met. Example: Give a $200 discount when the cart subtotal is $1,000 or more.

The condition checks the cart’s total value; the action applies the discount to the entire cart.

2. TENDER

Applies a discount based on the customer’s payment method. Example: Give a $100 discount when the customer pays using a VISA credit card.

The condition checks the payment type; the action applies a discount tied to that payment.

3. PRODUCT_BASED

A product-based action is used when the cart promotion applies a discount or reward action to specific products in the cart, not to the entire cart or a payment method. This action type is most commonly used for item-level offers, where the benefit depends on the products purchased or their attributes (such as category, brand, or quantity).

When to use it

Apply a percentage or fixed amount discount on certain products.
Offer discounts only on products that meet specific criteria, such as category, brand, or SKU.
Reward a related product set, for example, “Buy product A, get a discount on product B.”
Run category-level or brand-level cart promotions.

4. FREE_PRODUCT

Makes one or more specific items in the cart free of charge. This is the ideal action for "Buy X, Get Y Free" cart promotions.

Example: Buy a laptop and get a computer mouse for free.

The system identifies the product to be discounted and reduces its price to zero.

5. FIXED_PRICE

Changes the price of specific items to a set amount, regardless of their original price.

Example: Get any large pizza for $10.

The system finds the qualifying item and overrides its original price with the new fixed price.

6. PER_UNIT

Applies a reward action repeatedly for each qualifying group of items or value. Example: Buy 2 Paint Buckets, get 1 Paint Brush free for every 2 buckets.

The condition checks the total quantity or amount, and the action applies a recurring reward action for each multiple of a defined value.

Comparison Table

Action Type	When to Use It	What It Does	Example cart Promotion
CART_BASED	When the discount applies to the entire cart total.	Gives a single discount based on the total value of all items in the cart.	Get $200 off when your cart total is $1,000 or more.
TENDER	When the reward action depends on the payment method used.	Applies a discount if the customer uses a specific payment mode.	Pay with a VISA card and get $100 off your total bill.
PRODUCT_BASED	When you want to discount specific products or categories.	Applies a fixed or percentage discount to particular items that meet set criteria.	Get 10% off all Paint Supplies.
FREE_PRODUCT	For "Buy X, Get Y Free" offers.	Reduces the price of one or more specific items to zero.	Buy a laptop and get a computer mouse for free.
FIXED_PRICE	To sell an item or group of items at a specific special price.	Overrides the original price of an item with a new, set price.	Get any large pizza for $10.
PER_UNIT	When the reward action should repeat per quantity or group.	Applies benefits repeatedly for each qualifying group of items or value.	Buy 2 Paint Buckets, get 1 Paint Brush free for every 2 buckets.

When the cart promotions action type is CART_BASED

Field	Type	Required	Description
.cartBasedAction	Object	Yes	Defines a reward action or discount that applies to the entire shopping cart once the cart promotion’s condition is met. It’s used when the benefit is calculated at the cart level, not per product or payment type. Example: Apply a $200 discount when the cart subtotal is $1,000 or more.
..type	Enum	Yes	Type of action. Supported value: `ABSOLUTE`, `PERCENTAGE`.
..value	Number	Yes	Fixed monetary amount for the discount.

Example request

Requirement: The brand wants to set up a cart promotion, "Spend $100, Get $10 Off," with the condition that if the cart's subtotal is greater than or equal to $100, a fixed discount of $10 is applied to the entire cart.

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Cookie: _cfuv_vSE54e.Ky_kOxQM.ixIiU-1760115687488-0.0.1.1-604800000' \
--header 'Authorization: Basic Z2VvcmdlLmRvY2RlbW81OGE2NWI5ZjAxMzU5NGIwNDllZTk=' \
--data '{
  "name": "Spend 100 Get 10 Off",
  "orgId": 100737,
  "type": "CUSTOMER",
  "messageLabel": "Get $10 off on orders over $100!",
  "active": true,
  "priority": 0,
  "isStackable": false,
  "startDate": 1759363200000,
  "endDate": 1790985600000,
  "campaignId": "286039",
  "condition": {
    "type": "CART",
    "cartCondition": {
      "kpi": "SUBTOTAL",
      "operator": "GREATER_THAN_OR_EQUAL",
      "value": 100
    }
  },
  "action": {
    "type": "CART_BASED",
    "cartBasedAction": {
      "type": "ABSOLUTE",
      "value": 10
    }
  },
  "customerActivationRequired": true,
  "maxIssuancePerCustomer": 1,
  "promotionRestrictions": {},
  "customFieldValues": {}
}'

When the cart promotions action type is TENDER

Field	Type	Required	Description
.tenderBasedAction	Object	Yes	Defines a reward action or discount that applies when the customer uses a specific payment method (tender) during checkout. It’s used for conditions tied to cards or cash payments. Apply a $100 discount when the customer pays using a VISA credit card.
..type	Enum	Yes	Specifies how the discount or reward action amount is calculated. Supported value: `ABSOLUTE`, `PERCENTAGE`.
..value	String	Yes	Specifies the amount of discount to apply in numbers. Example: If the value is $20, the system applies a fixed discount, for example, $20 off.

Example request

Requirement: The brand wants to set up a cart promotion, "Pay with VISA, Get $20 Off on Orders Above $100," with conditions that if a customer's cart subtotal is greater than or equal to $100 AND they pay with a VISA card, an absolute discount of $20 is applied.

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlI5ZjAxMzU5NGIwkNDip3Po-1760116657904-0.0.1.1-604800000' \
--data '{
  "name": "VISA Discount on Cart Total",
  "orgId": 100737,
  "type": "CUSTOMER",
  "messageLabel": "Get $20 off with VISA on orders above $100",
  "active": true,
  "priority": 0,
  "isStackable": false,
  "startDate": 1759363200000,
  "endDate": 1790985600000,
  "campaignId": "286039",
  "condition": {
    "type": "TENDER",
    "tenderCondition": {
      "tenderModes": [
        {
          "type": "CARD",
          "identifiers": [
            "VISA_CARD"
          ]
        }
      ],
      "condition": {
        "type": "CART",
        "cartCondition": {
          "kpi": "SUBTOTAL",
          "operator": "GREATER_THAN_OR_EQUAL",
          "value": 100
        }
      }
    }
  },
  "action": {
    "type": "TENDER",
    "tenderBasedAction": {
      "type": "ABSOLUTE",
      "value": "20"
    }
  },
  "customerActivationRequired": true,
  "maxIssuancePerCustomer": 1,
  "promotionRestrictions": {},
  "customFieldValues": {}
}'

When the cart promotions action type is PRODUCT_BASED

Field	Type	Required	Description
.productBasedAction	Object	Yes	Defines a discount or reward action applied to specific products that meet defined criteria. Example: Apply a 10% discount on Paint Supplies.
..type	Enum	Yes	Defines how the discount is calculated. Supported values: `ABSOLUTE` (fixed amount), `PERCENTAGE(percentage-based). Example: type = PERCENTAGE applies 10% off.
..value	Number	Yes	Specifies the amount or percentage of the discount. Example: value = 10 applies a 10% discount if type is PERCENTAGE, or $10 off if type is ABSOLUTE.
..includeItemsFromConditionSet	Boolean	Yes	Controls whether the action benefit applies to the same items that satisfied the cart promotion trigger (`true`) or to a different target set defined by productBasedCondition (`false`). Example (true): “Buy 10 A, get $100 off those 10 A.” Example (false): “Buy 10 A, get $100 off B.”
..productBasedCondition	Object	Conditional	Defines the set of products to which the action's benefit will be applied. This field is required when includeItemsFromConditionSet is false, unless the action is intended to apply to the items from the nested condition like in condition type "PAYMENT_MODE_SCOPE".
...type	Enum	Yes	Specifies how target products are grouped. Supported values: `PRODUCT`, `COMBO_PRODUCT`. Example: COMBO_PRODUCT targets combinations like Paint + Brush.
...productCondition	Object	Conditional	Defines target products using product-level rules. Required if type = `PRODUCT`. Example: Apply discount to products in the “Paint Supplies” category.
....criteriaList	Array	Yes	List of rules that specify which products are eligible. Example: entity = CATEGORY, values = ["Paint Supplies"].
....kpi	Enum	Yes	Metric used for filtering products. Supported values: `NONE`, `QUANTITY`, `AMOUNT`. Example: QUANTITY = 2 means at least two products are required.
....operator	Enum	Conditional	Defines how the KPI is compared. Supported value: `EQUALS`. Example: EQUALS ensures the quantity exactly matches the target value.
....value	String	Conditional	Specifies the target number or value for the comparison. This should be defined in numbers. Example: value = "2" means exactly two items must be purchased.
...comboProductCondition	Object	Conditional	Defines the set of product combinations that receive the discount or reward action when the cart promotion is applied. It specifies which combo of products — such as a bundle or paired items — will get the benefit, based on the action’s configuration. If `includeItemsFromConditionSet` is true, the discount applies to the same combo that triggered the cart promotion. If `includeItemsFromConditionSet` is false, the discount applies to a different combo defined here.
....productConditions	Array	Yes	List of product condition objects. All listed conditions must be met for the discount to apply. Example: One Paint Brush and one ColorCo product.
.....kpi	Enum	Yes	Metric used for evaluating combo conditions. Supported values: `NONE`, `QUANTITY`, `AMOUNT`. Example: QUANTITY = 1 ensures each product is present at least once.
.....operator	Enum	Conditional	Logical operator. Supported values: `EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUA`L.
.....value	String	Conditional	Numeric target for KPI comparison. This should be defined in numbers. Example: value = "1" means at least one item must be present.
.....criteriaList	Array	Yes	Defines which products or attributes are included in the combo. Example: entity = PRODUCT_NAME, values = ["Paint Brush"].
......entity	String	Yes	Product attribute to evaluate (e.g., SKU).
......operator	Enum	Yes	Defines how the attribute values are compared. Supported values: `IN`, `NOT_IN`. Example: IN checks if the product belongs to “Paint Supplies.”
......values	Array	Yes	List of attribute values to match. Supports up to 100 values in a single array. Example: values = ["Paint Brush", "ColorCo"].

Example request

Requirement 1: The brand wants to set up a cart promotion where a customer buys any laptop, they should receive a 50% discount on an accessory bundle. The bundle is defined as exactly one mouse and one keyboard. If the customer has more than one mouse or keyboard in their cart, the discount should only apply to one of each

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmJ1a2w6NzYzNDkxOGFmNDI3MGQ3YzI4ZjU4ZjY3MmNhZjY1ZmY=' \
--header 'Cookie: _cfuvid=m_cAUxdAS9kIldmFfEaOkagijzS7nWq3g15w1dpuKfA-1760347164530-0.0.1.1-604800000' \
--data 'curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmJ1a2w6NzYzNDkxOGFmNDI3MGQ3YzI4ZjU4ZjY3MmNhZjY1ZmY=' \
--header 'Cookie: _cfuvid=m_cAUxdAS9kIldmFfEaOkagijzS7nWq3g15w1dpuKfA-1760347164530-0.0.1.1-604800000' \
--data '{
    "name": "Laptop + Accessory Bundle Deal",
    "type": "POS",
    "messageLabel": "Buy a Laptop, Get 50% Off a Mouse & Keyboard!",
    "active": true,
    "priority": 5,
    "isStackable": false,
    "startDate": 1760332800000,
    "endDate": 1792031999000,
    "campaignId": "286039",
    "condition": {
        "type": "PRODUCT",                             
        "productCondition": {
            "criteriaList": [
                {
                    "entity": "CATEGORY",
                    "operator": "IN",
                    "values": ["Laptops"]             
                }
            ],
            "kpi": "QUANTITY",
            "operator": "GREATER_THAN_OR_EQUAL",
            "value": "1"                              
        }
    },
    "action": {
        "type": "PRODUCT_BASED",                      
        "productBasedAction": {
            "type": "PERCENTAGE",                     
            "value": "50",                            
            "includeItemsFromConditionSet": false,    
            "productBasedCondition": {
                "type": "COMBO_PRODUCT",              
                "comboProductCondition": {
                    "productConditions": [            
                        {
                            "criteriaList": [
                                {
                                    "entity": "CATEGORY",
                                    "operator": "IN",
                                    "values": ["Mouse"] 
                                }
                            ],
                            "kpi": "QUANTITY",        
                            "operator": "EQUALS",     
                            "value": "1"              
                        },
                        {
                            "criteriaList": [
                                {
                                    "entity": "CATEGORY",
                                    "operator": "IN",
                                    "values": ["Keyboards"] 
                                }
                            ],
                            "kpi": "QUANTITY",        
                            "operator": "EQUALS",     
                            "value": "1"              
                        }
                    ]
                }
            }
        }
    }
}'\''''\'''

Requirement 2: A brand wants to offer a "25% Off Snacks" cart promotion, but to manage costs, they want the discount to apply only to the first two snack items a customer buys. If a customer buys five snack items, only two of them will receive the 25% discount.

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmJ1a2w6NzYzNDkxOGFmNDI3MGQ3YzI4ZjU4ZjY3MmNhZjY1ZmY=' \
--header 'Cookie: _cfuvid=m_cAUxdAS9kIldmFfEaOkagijzS7nWq3g15w1dpuKfA-1760347164530-0.0.1.1-604800000' \
--data '{
    "name": "25 Percent Off First Two Snacks",
    "type": "POS",
    "messageLabel": "25% Off the first two snacks you buy!",
    "active": true,
    "priority": 1,
    "isStackable": false,
    "startDate": 1759363200000,
    "endDate": 1790985600000,
    "campaignId": "286039",
    "condition": {
        "type": "PRODUCT",                             // Trigger: If the cart contains at least one snack.
        "productCondition": {
            "criteriaList": [
                {
                    "entity": "CATEGORY",
                    "operator": "IN",
                    "values": ["Snacks"]
                }
            ],
            "kpi": "QUANTITY",
            "operator": "GREATER_THAN_OR_EQUAL",
            "value": "1"
        }
    },
    "action": {
        "type": "PRODUCT_BASED",                      // Action: Apply a discount to specific products.
        "productBasedAction": {
            "type": "PERCENTAGE",                     // The discount is 25%.
            "value": "25.00",
            "productBasedCondition": {
                "type": "PRODUCT",
                "productCondition": {
                    "criteriaList": [                 // Rule: Find items in the "Snacks" category.
                        {
                            "entity": "CATEGORY",
                            "operator": "IN",
                            "values": [
                                "Snacks"
                            ]
                        }
                    ],
                    "kpi": "QUANTITY",                // KPI: Apply the discount based on the quantity of snacks.
                    "operator": "EQUALS",             // Logic: The quantity must be an exact match.
                    "value": "2"                      // Value: The discount applies to exactly TWO snack items.
                }
            }
        }
    },
    "customerActivationRequired": false,
    "maxIssuancePerCustomer": 10,
    "promotionRestrictions": {},
    "customFieldValues": {}
}'\'''

When the cart promotions action type is PER_UNIT

Field	Type	Required	Description
.perUnitAction	Object	Yes	Defines a reward action that can be applied repeatedly.
..perUnitKPI	Enum	Yes	Metric used to group items. Supported: `QUANTITY`.
..perUnitDivider	String	Yes	Specifies a numerical value that specifies the minimum quantity of items that must be purchased before a specified action (such as a discount or free item)is repeated. Example : Customer buys any two items from the 'Shirts' category, they are eligible to receive one item from the 'Ties' category for free Here the perUnitDivider will be 2, since every two item purchased is eligible for a free item repeatedly.
..rewardAction	Object	Yes	Defines the specific benefit for each group.
...type	Enum	Yes	Type of per-unit reward action. Supported values : `PRODUCT_BASED`: This action applies a direct discount (either a fixed amount or a percentage) to specific items., Example :A "25% Off All Snacks" cart promotion . When a customer adds any item from the "Snacks" category to their cart, the system applies a 25% discount to the price of just those snack items. `FREE_PRODUCT`:This action makes a specific item free, often as part of a "Buy X, Get Y" offer. Example : A "Buy 2 Shirts, Get 1 Free" cart promotion . When the system detects three items from the "Shirts" category in the cart, it identifies the cheapest one among them and reduces its price to zero, making it free. `FIXED_PRICE`:This action changes the price of a specific item to a set amount, regardless of its original price. Example: An "Any Large Pizza for $10" deal . When a customer adds any pizza from the "Large Pizzas" category to their cart, the system ignores its original price (e.g., $18) and changes it to the special fixed price of $10.
...productBasedAction	Object	Conditional	Required when `rewardAction.type` is `PRODUCT_BASED`.
....type	Enum	Yes	Calculation method. Supported: `ABSOLUTE`, `PERCENTAGE`.
....value	Number	Yes	The amount or percentage of the discount.
....includeItemsFromConditionSet	Boolean	Yes	Controls whether the action benefit applies to the same items that satisfied the cart promotion trigger (`true`) or to a different target set defined by productBasedCondition (`false`). Example (true): “Buy 10 A, get $100 off those 10 A.” Example (false): “Buy 10 A, get $100 off B.” Example : "If a customer buys a Laptop, a Mouse, and a Keyboard all in the same transaction, they get 50% off all three items." By setting `includeItemsFromConditionSet` to true, the discount is applied directly to the same three items that triggered the cart promotion in the above example.
....productBasedCondition	Object	Conditional	Defines the set of products to which the action's benefit will be applied. This field is required when includeItemsFromConditionSet is false, unless the action is intended to apply to the items from the nested condition like in condition type "PAYMENT_MODE_SCOPE".
.....type	Enum	Yes	Targeting method. Supported: `PRODUCT`, `COMBO_PRODUCT`.
.....productCondition	Object	Conditional	Defines target products. Required if type is PRODUCT.
......criteriaList	Array	Yes	Defines an array of rule objects that specify which products are targeted.
.......entity	String	Yes	Specifies the product attribute to evaluate. Supported values: `SKU`: The unique product code used internally to track a specific item (Stock Keeping Unit). `BRAND`: The trademarked name of the manufacturer or collection associated with the product. `ATTRIBUTE`: A custom property or characteristic of the product not covered by SKU, Brand, or Category Eg., 'Color: Red' or 'Material: Leather'. `CATEGORY`: The classification or group the product belongs to Eg., 'Detergents' or 'Outerwear'.
.......values	Array	Yes	Specifies an array of strings to match against the `entity` attribute. Supports up to 100 values in a single array.
.......operator	Enum	Yes	Specifies the operator for the list comparison. Supported values: `IN`, `NOT_IN`.
......kpi	Enum	Yes	Specifies an optional metric for filtering products. Supported values: `NONE`, `QUANTITY`, `AMOUNT`.
......operator	Enum	Conditional	Specifies the logical operator for product comparison. Supported values: `EQUALS`.
......value	String	Conditional	Specifies the target value for the product KPI comparison.
.....comboProductCondition	Object	Conditional	Defines target combos. Required if type is COMBO_PRODUCT.
......productConditions	Array	Yes	Array of product condition objects.
...freeProductAction	Object	Conditional	Required when rewardAction.type is FREE_PRODUCT.
....includeItemsFromConditionSet	Boolean	Yes	Controls whether the action benefit applies to the same items that satisfied the cart promotion trigger (`true`) or to a different target set defined by productBasedCondition (`false`). Example (true): “Buy 10 A, get $100 off those 10 A.” Example (false): “Buy 10 A, get $100 off B.” Example : "If a customer buys a Laptop, a Mouse, and a Keyboard all in the same transaction, they get 50% off all three items."
....productBasedCondition	Object	Yes	Defines exactly which products are to be marked as free.
.....type	Enum	Yes	Targeting method. Supported: `PRODUCT`, `COMBO_PRODUCT`.
.....productCondition	Object	Conditional	Defines target products. Required if type is `PRODUCT`.
......criteriaList	Array	Yes	Defines an array of rule objects that specify which products are targeted.
.......entity	String	Yes	Specifies the product attribute to evaluate, such as `SKU`, `BRAND`, or `CATEGORY`.
.......values	Array	Yes	Specifies an array of strings to match against the `entity` attribute. Supports up to 100 values in a single array.
.......operator	Enum	Yes	Specifies the operator for the list comparison. Supported values: `IN`, `NOT_IN`.
......kpi	Enum	Yes	Specifies an optional metric for filtering products. Supported values: `NONE`, `QUANTITY`, `AMOUNT`.
......operator	Enum	Conditional	Specifies the logical operator for product comparison. Supported values: `EQUALS`.
......value	String	Conditional	Specifies the target value for the product KPI comparison.
.....comboProductCondition	Object	Conditional	Defines target combos. Required if type is `COMBO_PRODUCT`.
...fixedPriceAction	Object	Conditional	Defines a reward action where products are sold at a fixed price. Required when `rewardAction.type` is `FIXED_PRICE`.
....value	Number	Yes	Specifies the new, fixed price for the qualifying items.
....includeItemsFromConditionSet	Boolean	Yes	Controls whether the action benefit applies to the same items that satisfied the cart promotion trigger (`true`) or to a different target set defined by productBasedCondition (`false`). Example (true): “Buy 10 A, get $100 off those 10 A.” Example (false): “Buy 10 A, get $100 off B.” Example : "If a customer buys a Laptop, a Mouse, and a Keyboard all in the same transaction, they get 50% off all three items."
....productBasedCondition	Object	Yes	Defines exactly which products are to be sold at the fixed price.
.....type	Enum	Yes	Specifies the product targeting method for the action. Supported values: `PRODUCT`, `COMBO_PRODUCT`.
.....productCondition	Object	Conditional	Defines target products using a list of criteria. Required when `type` is `PRODUCT`.
......criteriaList	Array	Yes	Defines an array of rule objects that specify which products are targeted.
.......entity	String	Yes	Specifies the product attribute to evaluate, such as `SKU`, `BRAND`, or `CATEGORY`.
.......values	Array	Yes	Specifies an array of strings to match against the `entity` attribute. Supports up to 100 values in a single array.
.......operator	Enum	Yes	Specifies the operator for the list comparison. Supported values: `IN`, `NOT_IN`.
......kpi	Enum	Yes	Specifies an optional metric for filtering products. Supported values: `NONE`, `QUANTITY`, `AMOUNT`.
......operator	Enum	Conditional	Specifies the logical operator for product comparison. Supported values: `EQUALS`.
......value	String	Conditional	Specifies the target value for the product KPI comparison.
.....comboProductCondition	Object	Conditional	Defines the target combo products for the action. Required when `type` is `COMBO_PRODUCT`.
......productConditions	Array	Yes	Defines an array of product condition objects that must all be satisfied for the action to apply.
.......kpi	Enum	Yes	Specifies an optional metric for filtering products. Supported values: `NONE`, `QUANTITY`.
.......operator	Enum	Conditional	Specifies the logical operator for the product `kpi` comparison.
.......value	String	Conditional	Specifies the target value for the product `kpi` comparison. Supports up to 100 values in a single array.
.......criteriaList	Array	Yes	Defines an array of rule objects that specify the products in this part of the combo.
........entity	String	Yes	Specifies the product attribute to evaluate, such as `SKU`, `BRAND`, or `CATEGORY`.
........values	Array	Yes	Specifies an array of strings to match against the `entity` attribute. Supports up to 100 values in a single array.
........operator	Enum	Yes	Specifies the operator for the list comparison. Supported values: `IN`, `NOT_IN`.

Example request

Requirement 1 : The brand wants to set up a product-specific discount cart promotion, "Get 25% Off All Snacks," with conditions that if a customer adds any item from the "Snacks" category to their cart, a 25% discount is applied to those specific items. This uses a PRODUCT_BASED reward action.

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmJ1a2w6NzYzNDkxOGFmNDjU4ZjY3MmNhZjY1ZmY=' \
--header 'Cookie: _cfuvid=m_cAUxdASkagijzS7nWq3g15w1dpuKfA-1760347164530-0.0.1.1-604800000' \
--data '{
    "name": "Buy a Drink, Get 25% Off Two Snacks",
    "type": "POS",
    "messageLabel": "Buy a Drink, Get 25% Off Up to Two Snacks!",
    "active": true,
    "priority": 1,
    "isStackable": false,
    "startDate": 1759363200000,
    "endDate": 1790985600000,
    "campaignId": "286039",
    "condition": {
        "type": "PRODUCT",                             // The trigger condition is buying a specific product.
        "productCondition": {
            "criteriaList": [
                {
                    "entity": "CATEGORY",
                    "operator": "IN",
                    "values": ["Drinks"]              // Triggers if the cart contains at least one item from the "Drinks" category.
                }
            ],
            "kpi": "QUANTITY",
            "operator": "GREATER_THAN_OR_EQUAL",
            "value": "1"
        }
    },
    "action": {
        "type": "PER_UNIT",                           // Using PER_UNIT to precisely control the reward.
        "perUnitAction": {
            "perUnitKPI": "QUANTITY",                 // The logic is based on the quantity of items.
            "perUnitDivider": "1",                    // This action logic will run once per triggering item.
            "rewardAction": {
                "type": "PRODUCT_BASED",              // The reward is a discount on specific products.
                "productBasedAction": {
                    "type": "PERCENTAGE",             // The discount is 25%.
                    "value": 25,
                    "includeItemsFromConditionSet": false, // The discount applies to snacks, NOT the drink that triggered the promo.
                    "productBasedCondition": {
                        "type": "PRODUCT",
                        "productCondition": {
                            "criteriaList": [         // Identifies the items eligible for the discount.
                                {
                                    "entity": "CATEGORY",
                                    "operator": "IN",
                                    "values": ["Snacks"] // The discount applies only to items in the "Snacks" category.
                                }
                            ],
                            "kpi": "QUANTITY",        // Use a KPI to limit how many snacks get the discount.
                            "operator": "EQUALS",     // The quantity must be an exact match.
                            "value": "2"              // The 25% discount applies to exactly TWO snack items.
                        }
                    }
                }
            }
        }
    },
    "customerActivationRequired": false,
    "maxIssuancePerCustomer": 10,
    "promotionRestrictions": {},
    "customFieldValues": {}
}'\'''

Requirement 2: The brand wants to set up a cart promotion, where a customer buys any two items from the 'Shirts' category, they are eligible to receive one item from the 'Ties' category for free.

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmJ1a2w6NzYzNDkxOjU4ZjY3MmNhZjY1ZmY=' \
--header 'Cookie: _cfuvid=m_cAUxdAS9kIldnWq3g15w1dpuKfA-1760347164530-0.0.1.1-604800000' \
--data '{
    "name": "Buy 2 Shirts, Get a Tie Free",
    "type": "POS",
    "messageLabel": "Free tie when you buy any two shirts!",
    "active": true,
    "priority": 1,
    "isStackable": false,
    "startDate": 1759363200000,
    "endDate": 1790985600000,
    "campaignId": "286039",
    "condition": {
        "type": "PRODUCT",                             // The trigger is based on specific products.
        "productCondition": {
            "criteriaList": [
                {
                    "entity": "CATEGORY",
                    "operator": "IN",
                    "values": ["Shirts"]              // Checks for items in the "Shirts" category.
                }
            ],
            "kpi": "QUANTITY",
            "operator": "GREATER_THAN_OR_EQUAL",
            "value": "2"                              // Triggers when the cart has at least two shirts.
        }
    },
    "action": {
        "type": "PER_UNIT",
        "perUnitAction": {
            "perUnitKPI": "QUANTITY",                 // Logic is based on the quantity of triggering items.
            "perUnitDivider": "2",                    // The reward action will trigger for every 2 shirts.
            "rewardAction": {
                "type": "FREE_PRODUCT",               // The reward is a free product.
                "freeProductAction": {
                    "includeItemsFromConditionSet": false, // The free item is NOT a shirt.
                    "productBasedCondition": {
                        "type": "PRODUCT",
                        "productCondition": {
                            "criteriaList": [         // Identifies the item that will be made free.
                                {
                                    "entity": "CATEGORY",
                                    "operator": "IN",
                                    "values": ["Ties"]// The free item must be from the "Ties" category.
                                }
                            ],
                            "kpi": "QUANTITY",        // Use a KPI to specify how many ties are made free.
                            "operator": "EQUALS",     // The quantity must be an exact match.
                            "value": "1"              // Exactly ONE tie will be made free.
                        }
                    }
                }
            }
        }
    },
    "customerActivationRequired": false,
    "maxIssuancePerCustomer": 10,
    "promotionRestrictions": {},
    "customFieldValues": {}
}''\'''

Requirement 3: The brand wants to set up a cart promotion, "Any Large Pizza for $10," with conditions that if a customer buys any item from the "Large Pizzas" category, its price is set to $10. This uses a FIXED_PRICE reward action.

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmRvY2RlbW86MmQ1OTNhMjI2MTk1OGE2NWI5ZjAxMzU5NGIwNDllZTk=' \
--header 'Cookie: _cfuvid=5O_PtucI3YnfDUgjgMPnHbPeEKcKJjaHWDOkNDip3Po-1760116657904-0.0.1.1-604800000' \
--data '{
  "name": "Any Large Pizza for 10 Dollars",
  "orgId": 100737,
  "type": "POS",
  "messageLabel": "Hot Deal: Any Large Pizza for just $10!",
  "active": true,
  "priority": 2,
  "isStackable": true,
  "startDate": 1759363200000,
  "endDate": 1790985600000,
  "campaignId": "286039",
  "condition": {
    "type": "CART",
    "cartCondition": {
      "kpi": "ITEMCOUNT",
      "operator": "GREATER_THAN_OR_EQUAL",
      "value": 1
    }
  },
  "action": {
    "type": "PER_UNIT",
    "perUnitAction": {
      "perUnitKPI": "QUANTITY",
      "perUnitDivider": "1",
      "rewardAction": {
        "type": "FIXED_PRICE",
        "fixedPriceAction": {
          "value": 10,
          "includeItemsFromConditionSet": false,
          "productBasedCondition": {
            "type": "PRODUCT",
            "productCondition": {
              "criteriaList": [
                {
                  "entity": "CATEGORY",
                  "values": [
                    "Large Pizzas"
                  ],
                  "operator": "IN"
                }
              ],
              "kpi": "NONE"
            }
          }
        }
      }
    }
  },
  "customerActivationRequired": false,
  "maxIssuancePerCustomer": 10,
  "promotionRestrictions": {},
  "customFieldValues": {}
}'

Requirement 4: The brand wants to set up a cart promotion in which "If a customer buys a Laptop, a Mouse, and a Keyboard all in the same transaction, they get 50% off all three items."

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmJ1a2w6NzYzNDkxOGFmN4ZjY3MmNhZjY1ZmY=' \
--header 'Cookie: _cfuvid=8M02INsasy1bHCM-1760357020184-0.0.1.1-604800000' \
--data '{
    "name": "Work From Home Bundle - 50% Off",
    "type": "POS",
    "messageLabel": "Get 50% off when you buy a Laptop, Mouse, and Keyboard together!",
    "active": true,
    "priority": 0,
    "isStackable": false,
    "startDate": 1759363200000,
    "endDate": 1790985600000,
    "campaignId": "286039",
    "condition": {
        "type": "COMBO_PRODUCT",                   // The trigger requires a combination of products.
        "comboProductCondition": {
            "productConditions": [                 // All three of these conditions must be met.
                {
                    "kpi": "QUANTITY",
                    "operator": "GREATER_THAN_OR_EQUAL",
                    "value": "1",
                    "criteriaList": [
                        { "entity": "CATEGORY", "operator": "IN", "values": ["Laptops"] }
                    ]
                },
                {
                    "kpi": "QUANTITY",
                    "operator": "GREATER_THAN_OR_EQUAL",
                    "value": "1",
                    "criteriaList": [
                        { "entity": "CATEGORY", "operator": "IN", "values": ["Mice"] }
                    ]
                },
                {
                    "kpi": "QUANTITY",
                    "operator": "GREATER_THAN_OR_EQUAL",
                    "value": "1",
                    "criteriaList": [
                        { "entity": "CATEGORY", "operator": "IN", "values": ["Keyboards"] }
                    ]
                }
            ]
        }
    },
    "action": {
        "type": "PRODUCT_BASED",                     // The action is a discount on specific products.
        "productBasedAction": {
            "type": "PERCENTAGE",                     // The discount is 50%.
            "value": 50,
            "includeItemsFromConditionSet": true      // CRITICAL: This tells the action to discount the items from the main condition (the bundle).
        }
    },
    "customerActivationRequired": false,
    "maxIssuancePerCustomer": 10,
    "promotionRestrictions": {},
    "customFieldValues": {}
}''\'''

When the cart promotion's action type is `FREE_PRODUCT`

Field	Type	Required	Description
.freeProductAction	Object	Yes	Defines a reward action where specific products are made free.
..includeItemsFromConditionSet	Boolean	Yes	Controls whether the action benefit applies to the same items that satisfied the cart promotion trigger (`true`) or to a different target set defined by productBasedCondition (`false`). Example (true): “Buy 10 A, get $100 off those 10 A.” Example (false): “Buy 10 A, get $100 off B.” Example: "If a customer buys a premium laptop (over $1000), a 'Pro Gaming Mouse', AND a 'Mechanical Keyboard' all in the same transaction, they get all three items for a combined, fixed price of $1200."
..productBasedCondition	Object	Yes	Defines the set of products that are eligible to be made free. If multiple items in the cart match, the system typically makes the cheapest one free.
...type	Enum	Yes	Specifies how target products are grouped. Supported: `PRODUCT`, `COMBO_PRODUCT`.
...productCondition	Object	Conditional	Defines target products using product-level rules. Required when `type` is `PRODUCT`.
....criteriaList	Array	Yes	A list of rule objects that specify which products are targeted.
.....entity	String	Yes	Specifies the product attribute to evaluate, such as `SKU`, `BRAND`, or `CATEGORY`.
.....operator	Enum	Yes	Specifies the operator for the list comparison. Supported: `IN`, `NOT_IN`.
.....values	Array	Yes	Specifies an array of strings to match against the `entity` attribute.
....kpi	Enum	Yes	An optional metric for filtering products. Supported: `NONE`, `QUANTITY`, `AMOUNT`.
....operator	Enum	Conditional	The logical operator for the KPI comparison. Required if `kpi` is not `NONE`. Supported: `EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL`.
....value	String	Conditional	The target value for the KPI comparison. Required if `kpi` is not `NONE`.
...comboProductCondition	Object	Conditional	Defines the set of product combinations that can be made free. Required when `type` is `COMBO_PRODUCT`.
....productConditions	Array	Yes	An array of product condition objects. All conditions in this list must be satisfied for the combo to qualify.
.....criteriaList	Array	Yes	Defines the specific products to check in this part of the combo.
......entity	String	Yes	Specifies the product attribute to evaluate, such as `SKU`, `BRAND`, or `CATEGORY`.
......operator	Enum	Yes	The operator for the list comparison. Supported values:`IN`, `NOT_IN`.
......values	Array	Yes	The list of attribute values to match against. Supports up to 100 values in a single array.
.....kpi	Enum	Yes	The metric to evaluate for this part of the combo. Supported values:`NONE`, `QUANTITY`, `AMOUNT`.
.....operator	Enum	Conditional	The comparison logic for the KPI Supported values: `EQUALS`, `GREATER_THAN`, `GREATER_THAN_OR_EQUA`L.
.....value	String	Conditional	The target value for the KPI comparison.

Example request

Requirement: A tech store wants to create an "all-in-one" bundle deal. The requirement is: "If a customer buys a premium laptop (over $1000), a 'Pro Gaming Mouse', AND a 'Mechanical Keyboard' all in the same transaction, they get all three items for a combined, fixed price of $1200."

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmJ1a2w6NzYzNDkxOGFmNDI3MGQ3YzI4ZjU4ZjY3MmNhZjY1ZmY=' \
--header 'Cookie: _cfuvid=8M02INwaH44vLLEiiCcBIHKDdvTjqsnNjksasy1bHCM-1760357020184-0.0.1.1-604800000' \
--data '{
    "name": "Ultimate Workstation Bundle - $1200",
    "type": "POS",
    "messageLabel": "Get a Premium Laptop, Pro Mouse, and Mechanical Keyboard for just $1200!",
    "active": true,
    "priority": 1,
    "isStackable": false,
    "startDate": 1759363200000,
    "endDate": 1790985600000,
    "campaignId": "286039",
    "condition": {
        "type": "COMBO_PRODUCT",                   // The trigger requires a 3-part combo.
        "comboProductCondition": {
            "productConditions": [
                {
                    "criteriaList": [ { "entity": "CATEGORY", "operator": "IN", "values": ["Laptops"] } ],
                    "kpi": "AMOUNT",
                    "operator": "GREATER_THAN_OR_EQUAL",
                    "value": "1000"               // Part 1: A laptop valued at $1000 or more.
                },
                {
                    "criteriaList": [ { "entity": "SKU", "operator": "IN", "values": ["GM-PRO-001"] } ],
                    "kpi": "QUANTITY",
                    "operator": "GREATER_THAN_OR_EQUAL",
                    "value": "1"                  // Part 2: The specific 'Pro Gaming Mouse'.
                },
                {
                    "criteriaList": [ { "entity": "CATEGORY", "operator": "IN", "values": ["Mechanical Keyboards"] } ],
                    "kpi": "QUANTITY",
                    "operator": "GREATER_THAN_OR_EQUAL",
                    "value": "1"                  // Part 3: Any mechanical keyboard.
                }
            ]
        }
    },
    "action": {
        "type": "FIXED_PRICE",                    // The reward sets a fixed price for the items.
        "fixedPriceAction": {
            "value": 1200,                        // The fixed price for the entire bundle is $1200.
            "includeItemsFromConditionSet": true, // The price applies to the items from the main condition.
            "productBasedCondition": {
                "type": "COMBO_PRODUCT",          // This re-defines the items to satisfy the validator.
                "comboProductCondition": {
                    "productConditions": [        // Each part MUST use kpi: QUANTITY and operator: EQUALS.
                        {
                            "criteriaList": [ { "entity": "CATEGORY", "operator": "IN", "values": ["Laptops"] } ],
                            "kpi": "QUANTITY",
                            "operator": "EQUALS",
                            "value": "1"
                        },
                        {
                            "criteriaList": [ { "entity": "SKU", "operator": "IN", "values": ["GM-PRO-001"] } ],
                            "kpi": "QUANTITY",
                            "operator": "EQUALS",
                            "value": "1"
                        },
                        {
                            "criteriaList": [ { "entity": "CATEGORY", "operator": "IN", "values": ["Mechanical Keyboards"] } ],
                            "kpi": "QUANTITY",
                            "operator": "EQUALS",
                            "value": "1"
                        }
                    ]
                }
            }
        }
    },
    "customerActivationRequired": false,
    "maxIssuancePerCustomer": 10,
    "promotionRestrictions": {},
    "customFieldValues": {}
}'\'''

When the cart promotion's action type is `FIXED_PRICE`

Important Constraint: For a FIXED_PRICE action to be valid, the productCondition or comboProductCondition that defines which items get the special price must use a kpi of QUANTITY and an operator of EQUALS.

Field	Type	Required	Description
.fixedPriceAction	Object	Yes	Defines a reward action where the price of a product is changed to a specific value.
..value	Number	Yes	The new, fixed price for the qualifying items.
..includeItemsFromConditionSet	Boolean	Yes	Controls whether the action benefit applies to the same items that satisfied the cart promotion trigger (`true`) or to a different target set defined by productBasedCondition (`false`). Example (true): “Buy 10 A, get $100 off those 10 A.” Example (false): “Buy 10 A, get $100 off B.” Example : "Any Large Pizza for $10." The condition is that if a customer buys any item from the "Large Pizzas" category, its price is set to a fixed $10.
..productBasedCondition	Object	Yes	Defines the specific set of products that will be sold at the fixed price.
...type	Enum	Yes	Specifies how the target products are grouped. Supported: `PRODUCT`, `COMBO_PRODUCT`.
...productCondition	Object	Conditional	Defines target products using product-level rules. Required when `type` is `PRODUCT`.
....criteriaList	Array	Yes	A list of rule objects that specify which products are targeted.
.....entity	String	Yes	Specifies the product attribute to evaluate, such as `SKU`, `BRAND`, or `CATEGORY`.
.....operator	Enum	Yes	Specifies the operator for the list comparison. Supported: `IN`, `NOT_IN`.
.....values	Array	Yes	Specifies an array of strings to match against the `entity` attribute.
....kpi	Enum	Yes	The metric for filtering products. Constraint: Must be `QUANTITY` for this action type.
....operator	Enum	Conditional	The logical operator for the KPI comparison. Constraint: Must be `EQUALS` for this action type.
....value	String	Conditional	The target quantity for the KPI comparison. Required if `kpi` is not `NONE`.
...comboProductCondition	Object	Conditional	Defines the set of product combinations that will be sold at the fixed price. Required when `type` is `COMBO_PRODUCT`.
....productConditions	Array	Yes	An array of `productCondition` objects. All conditions in this list must be satisfied for the combo to qualify.
.....criteriaList	Array	Yes	Defines the specific products to check in this part of the combo.
......entity	String	Yes	The product attribute to evaluate Supported values: `CATEGORY`, `BRAND`,`SKU`.
......operator	Enum	Yes	The operator for the list comparison Supported values:`IN`, `NOT_IN`.
......values	Array	Yes	The list of attribute values to match against. Supports up to 100 values in a single array.
.....kpi	Enum	Yes	The metric for this part of the combo. Constraint: Must be `QUANTITY`.
.....operator	Enum	Conditional	The comparison logic for the KPI. Constraint: Must be `EQUALS`.
.....value	String	Conditional	The target quantity for the KPI comparison.

Example Request

Requirement: The brand wants to set up a cart promotion, "Any Large Pizza for $10." The condition is that if a customer buys any item from the "Large Pizzas" category, its price is set to a fixed $10.

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--data '{
    "name": "Any Large Pizza for 10 Dollar",
    "type": "POS",
    "messageLabel": "Hot Deal: Any Large Pizza for just $10!",
    "active": true,
    "priority": 2,
    "isStackable": true,
    "startDate": 1759363200000,
    "endDate": 1790985600000,
    "campaignId": "286039",
    "condition": {
        "type": "PRODUCT",
        "productCondition": {
            "criteriaList": [
                {
                    "entity": "CATEGORY",
                    "operator": "IN",
                    "values": [
                        "Large Pizzas"
                    ]
                }
            ],
            "kpi": "QUANTITY",
            "operator": "GREATER_THAN_OR_EQUAL",
            "value": "1"
        }
    },
    "action": {
        "type": "FIXED_PRICE",
        "fixedPriceAction": {
            "value": 10,
            "includeItemsFromConditionSet": true,
            "productBasedCondition": {
                "type": "PRODUCT",
                "productCondition": {
                    "criteriaList": [
                        {
                            "entity": "CATEGORY",
                            "operator": "IN",
                            "values": [
                                "Large Pizzas"
                            ]
                        }
                    ],
                    "kpi": "QUANTITY",
                    "operator": "EQUALS",
                    "value": "1"
                }
            }
        }
    },
    "customerActivationRequired": false,
    "promotionRestrictions": {},
    "customFieldValues": {}
}'\'''

Promotion restrictions Object

Field	Type	Required	Description
.Customer	Array	Conditional	Specifies restrictions that apply per customer.
.Cart	Array	Conditional	Specifies restrictions that apply per cart.
.Promotion	Array	Conditional	Specifies restrictions that apply to the overall cart promotion.
.Code	Array	Conditional	Specifies restrictions that apply to cart promotion codes. Required when the main promotion type is `CODE`.
.Earn	Array	Conditional	Specifies restrictions that apply to the earning action. This is only valid when the main promotion type is `EARNING`.
..kpi	Enum	Yes	The metric to be limited. Supported: • `REDEMPTION`: Limits redemption count. • `TRANSACTION`: Limits transaction count. • `DISCOUNT`: Caps total discount value.
..frequency	Enum	Optional	How often the restriction resets. Supported: <br>* `DAYS`: The limit resets every N days. Example: A limit of 100 redemptions resets every 10 days. <br>* `WEEKS`: The limit resets weekly. Example: A limit of 500 redemptions resets each week, starting on Monday. DOES_NOT_REPEAT : The restriction is applied only once and does not reset. It acts as a single, lifetime limit for the duration of the promotion.. If omitted, the restriction does not repeat.
..minTimeBetweenRepeat	Long	Conditional	Defines the interval at which the limit resets Weekly Limit Reset: The limit resets based on a fixed, recurring window measured in weeks.Example: If the value is 2, the limit resets every two weeks. Reset Day: The reset consistently occurs based on the first day of the week which is set as Sunday, regardless of the purchase date. Daily Limit Reset (Rolling Window): The spending limit resets based on a rolling window starting from the time of each purchase. Example: If a redemption `minTimeBetweenRepeat` is set as 5 and a redemption is made on November 1st, the next redemption will be possible starting November 6th (after the 5-day window has passed).
..limit	BigDecimal	Yes	Maximum allowed value for the restriction. Example: A REDEMPTION limit of "1".

Example Request

Customer level restriction requirement: A coffee shop wants to offer a "Happy Hour" cart promotion for "$2 off any drink" but wants to limit each customer to using this offer only once per day to ensure fair usage.

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmRvY2RlbW86MmQ1OTNhMjI2MTk1OllZTk=' \
--header 'Cookie: _cfuvid=m_cAUxdzS7nWq3g15w1dpuKfA-1760347164530-0.0.1.1-604800000' \
--data '{
    "name": "Happy Hour Daily Discount",          
    "type": "CUSTOMER",                          
    "messageLabel": "$2 off any drink, once per day!",
    "active": true,
    "priority": 10,
    "isStackable": false,
    "startDate": 1759363200000,
    "endDate": 1790985600000,
    "campaignId": "286039",
    "condition": {
        "type": "PRODUCT",                        
        "productCondition": {
            "criteriaList": [
                {
                    "entity": "CATEGORY",         
                    "operator": "IN",
                    "values": ["Coffee", "Tea", "Juice"] 
                }
            ],
            "kpi": "QUANTITY",
            "operator": "GREATER_THAN_OR_EQUAL",
            "value": "1"                          
        }
    },
    "action": {
        "type": "CART_BASED",
        "cartBasedAction": {
            "type": "ABSOLUTE",
            "value": 2                            
        }
    },
    "promotionRestrictions": {
        "Customer": [                             
            {
                "kpi": "REDEMPTION",              
                "frequency": "DAYS",              
                "minTimeBetweenRepeat": 86400000, 
                "limit": "1"                      
            }
        ]
    }
}'\'''

Cart level restriction requirement: A fashion retailer offers a "25% Off Everything" cart promotion but wants to cap the maximum discount at $100 per transaction.

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmRvY2RlbW86MmQ1OOGE2NWI5ZjAxMzU5NGIwNDllZTk=' \
--header 'Cookie: _cfuvid=m_cAUxdAzS7nWq3g15w1dpuKfA-1760347164530-0.0.1.1-604800000' \
--data '{
    "name": "25% Off Sitewide (Capped at $100)",    
    "type": "POS",                                
    "messageLabel": "Get 25% off your order! Max discount $100.",
    "active": true,
    "priority": 5,
    "isStackable": false,
    "startDate": 1759363200000,
    "endDate": 1790985600000,
    "campaignId": "286039",
    "condition": {
        "type": "CART",
        "cartCondition": {
            "kpi": "SUBTOTAL",
            "operator": "GREATER_THAN",
            "value": 0                            
        }
    },
    "action": {
        "type": "CART_BASED",
        "cartBasedAction": {
            "type": "PERCENTAGE",                 
            "value": 25                           
        }
    },
    "promotionRestrictions": {
        "Cart": [                                 
            {
                "kpi": "DISCOUNT",                
                "limit": "100"                    
            }
        ]
    }
}'\''
'

Promotion Level Restriction requirement: A new store is launching with a "Grand Opening" offer where the first 1,000 customers get $10 off.

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmRvY2RlbW86MmQ1OTN5ZjAxMzU5NGIwNDllZTk=' \
--header 'Cookie: _cfuvid=m_cAUxdAS9kIldmF3g15w1dpuKfA-1760347164530-0.0.1.1-604800000' \
--data '{
    "name": "Grand Opening - First 1000 Customers", 
    "type": "POS",
    "messageLabel": "$10 off for our first 1000 customers!",
    "active": true,
    "priority": 1,                                
    "isStackable": false,
    "startDate": 1759363200000,
    "endDate": 1790985600000,
    "campaignId": "286039",
    "condition": {
        "type": "CART",
        "cartCondition": {
            "kpi": "SUBTOTAL",
            "operator": "GREATER_THAN_OR_EQUAL",
            "value": 10                           
        }
    },
    "action": {
        "type": "CART_BASED",
        "cartBasedAction": {
            "type": "ABSOLUTE",
            "value": 10                           
        }
    },
    "promotionRestrictions": {
        "Promotion": [                            
            {
                "kpi": "REDEMPTION",              
                "limit": "1000"                   
            }
        ]
    }
}'\'''

Code level restriction requirement: A company provides new subscribers with a unique, single-use code for "15% off their first order."

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmRvY2RlbWjI2MTk1OGE2NWI5ZjAxMzU5NGIwNDllZTk=' \
--header 'Cookie: _cfuvid=m_cAUxdAagijzS7nWq3g15w1dpuKfA-1760347164530-0.0.1.1-604800000' \
--data '{
    "name": "15% Off First Order - Single-Use Codes", 
    "type": "CODE",                              
    "messageLabel": "Welcome! Here is 15% off your first order.",
    "active": true,
    "priority": 0,
    "isStackable": false,
    "startDate": 1759363200000,
    "endDate": 1790985600000,
    "campaignId": "286039",
    "condition": {
        "type": "CART",
        "cartCondition": {
            "kpi": "SUBTOTAL",
            "operator": "GREATER_THAN",
            "value": 0                            
        }
    },
    "action": {
        "type": "CART_BASED",
        "cartBasedAction": {
            "type": "PERCENTAGE",
            "value": 15                           
        }
    },
    "promotionRestrictions": {
        "Code": [                                 
            {
                "kpi": "REDEMPTION",              
                "limit": "1"                      
            }
        ]
    }
}'\'''

Earning Criteria Object

Field	Type	Required	Description
.active	Boolean	Yes	Flag to enable or disable this specific earning rule.
.criteriaDsl	String	Yes	The earning rule in simple language Example: "true": Always True (No Condition)
.criteriaDslJson	String	Yes	Escaped JSON string of the rule's values. Example: `"{ \"arity\":\"literal\", \"value\":\"true\", \"type\":\"boolean:primitive\" }"`
.criteriaName	String	Yes	A name for the earning criteria rule.
.earnedFromType	Enum	Yes	Type of event that triggers the rule. Supported: `ACTIVITY`: This type is used when a cart promotion is earned based on a customer's real-time actions, such as making a purchase (TransactionAdd). `MILESTONE`: This type is used when a cart promotion is earned because a customer has achieved a predefined goal or status within a program.
.eventType	Enum	Yes	Specific activity that triggers the rule. Supported: `TransactionAdd` , `Customer Update` , `Registration`.
.groupId	Integer	Yes	Identifier for grouping related earning criteria.
.milestoneId	Integer	Yes	Identifier for a specific milestone within an earning program.

Example Request

Requirement: brand wants to setup a cart promotion where a customer reaches milestone 12345, they get a $50 voucher that they can use on their next purchase of $50 or more.

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmJNzYzNDkxOGFU4ZjY3MmNhZjY1ZmY=' \
--header 'Cookie: _cfuvid=m_cAUxdASmg15w1dpuKfA-1760347164530-0.0.1.1-604800000' \
--data '{
    "name": "Milestone Reward - $50 Voucher",
    "type": "EARNING",
    "messageLabel": "Congratulations! You'\''ve earned a $50 voucher.",
    "active": true,
    "priority": 1,
    "isStackable": false,
    "startDate": 1760332800000,
    "endDate": 1792031999000,
    "campaignId": "286039",
    "condition": {
        "type": "CART",
        "cartCondition": {
            "kpi": "SUBTOTAL",
            "operator": "GREATER_THAN_OR_EQUAL",
            "value": "50.000000"
        }
    },
    "action": {
        "type": "CART_BASED",
        "cartBasedAction": {
            "type": "ABSOLUTE",
            "value": "50.000000"
        }
    },
    "earningCriteria": {
        "active": true,
        "earnedFromType": "MILESTONE",
        "eventType": "TransactionAdd",
        "criteriaName": "Milestone_Achievement_12345",
        "criteriaDsl": "true",
        "criteriaDslJson": "{ \"arity\":\"literal\", \"value\":\"true\", \"type\":\"boolean:primitive\" }",
        "groupId": 1,
        "milestoneId": 12345
    }
}'

Store Criteria Object

This object limits the promotion to specific physical or logical locations, such as a set of stores or a geographical zone.

Field	Type	Required	Description
.type	Enum	Yes	The type of location entity. Supported values: • `STORE`: A specific store. • `ZONE`: A defined group of stores. • `CONCEPT`: A brand or store concept.
.values	Array of Integers	Yes	An array of IDs corresponding to the `type` (e.g., `[101, 204]` for store IDs).
.operator	Enum	Yes	The logical operator. Supported values: • `IN`: The promotion is valid only in the listed locations. • `NOT_IN`: The promotion is valid everywhere except the listed locations.

Example Request

Requirement: The brand wants to offer a "15% Off Store Opening Special" that is only valid at their two new store locations (IDs: 101 and 102).

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmJ1a2w6NzYzNDkxOGFmN4ZjU4ZjY3MmNhZjY1ZmY=' \
--header 'Cookie: _cfuvid=Fl.R3pP_RtM6ZaoUweo7cHOk4zcxuRg-1761063598566-0.0.1.1-604800000' \
--data '{
    "name": "New Store Opening Special",
    "type": "POS",
    "startDate": 1761019200000,
    "endDate": 1764565199999,
    "campaignId": 286039,
    "storeCriteria": {
        "type": "STORE",
        "values": [101, 102],
        "operator": "IN"
    },
    "condition": {
        "type": "CART",
        "cartCondition": {
            "kpi": "SUBTOTAL",
            "operator": "GREATER_THAN",
            "value": 0
        }
    },
    "action": {
        "type": "CART_BASED",
        "cartBasedAction": {
            "type": "PERCENTAGE",
            "value": 15
        }
    }
}'

Time Criteria Object

This object restricts the promotion to specific times of the day or days of the week, enabling use cases like "Happy Hour" or "Weekend Specials."

Field	Type	Required	Description
.startTime	String	Yes	An object specifying the start time. Must contain `hour` (0-23) and `minute` (0-59).
.durationInHours	Integer	Yes	The duration of the promotion window in hours from the `startTime`.
.repeatFrequency	Enum	Yes	How often the time window repeats. Supported: `WEEKS`, `DAYS`, `DOES_NOT_REPEAT`.
.weeklyValues	Array of Strings	Conditional	Required if `repeatFrequency` is `WEEKS`. A list of days, e.g., `["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY", "SUNDAY"]`.

Example Request

Requirement: The brand wants a "Weekday Happy Hour" offering 20% off from 4:00 PM to 5:59 PM (a 2-hour duration) every Monday through Friday.

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmJ1a2w6NzYzNDkxOGFmNDIZjU4ZjY3MmNhZjY1ZmY=' \
--header 'Cookie: _cfuvid=Fl.R3pP_RilU3aoUweo7cHOk4zcxuRg-1761063598566-0.0.1.1-604800000' \
--data '{
    "name": "Weekday Happy Hour",
    "type": "POS",
    "startDate": 1761019200000,
    "endDate": 1764565199999,
    "campaignId": "286039",
    "timeCriteria": {
        "startTime": "16:00",                 
        "durationInHours": "2",               
        "repeatFrequency": "WEEKS",
        "weeklyValues": [
            "MONDAY",
            "TUESDAY",
            "WEDNESDAY",
            "THURSDAY",
            "FRIDAY"
        ]
    },
    "condition": {
        "type": "PRODUCT",
        "productCondition": {
            "criteriaList": [ { "entity": "CATEGORY", "operator": "IN", "values": ["Beverages"] } ],
            "kpi": "QUANTITY",
            "operator": "GREATER_THAN_OR_EQUAL",
            "value": "1"
        }
    },
    "action": {
        "type": "PRODUCT_BASED",
        "productBasedAction": {
            "type": "PERCENTAGE",
            "value": "20",
            "includeItemsFromConditionSet": true
        }
    }
}'

Supplementary Criteria Object

This object targets customers based on their status in a loyalty program, such as their membership tier or subscription status.

Field	Type	Required	Description
.loyaltyProgramId	Integer	Yes	The ID of the loyalty program to check against.
.programType	Enum	Yes	The type of program. Supported values: • `TIER`: Targets customers in a specific loyalty tier. • `SUBSCRIPTION`: Targets customers with a specific subscription.
.partnerProgramId	Integer	Yes	The ID of the specific tier or subscription within the program that is being targeted.

Example Request

Requirement: Offer an exclusive "10% off for Gold Tier members" (Tier ID 99) who are part of the main loyalty program (ID 123).

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/promotions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic Z2VvcmdlLmJ1a2w6NzYzNDkxOGFmND3YzI4ZjU4ZjY3MmNhZjY1ZmY=' \
--header 'Cookie: _cfuvid=Fl.R3pP_RilU3UFbHOk4zcxuRg-1761063598566-0.0.1.1-604800000' \
--data '{
    "name": "Gold Tier Exclusive",
    "type": "CUSTOMER",
    
    "startDate": 1761019200000,
    "endDate": 1764565199999,
    "campaignId": "286039",
    "supplementaryCriteria": {
        "loyaltyProgramId": 123,
        "programType": "TIER",
        "partnerProgramId": 99
    },
    "condition": {
        "type": "CART",
        "cartCondition": { "kpi": "SUBTOTAL", "operator": "GREATER_THAN", "value": 0 }
    },
    "action": {
        "type": "CART_BASED",
        "cartBasedAction": { "type": "PERCENTAGE", "value": 10 }
    }
}'

Example response

{
    "data": {
        "id": "68e4b3d8dd46cd232fb723d3",
        "name": "Combo Product promotion ",
        "orgId": 100737,
        "priority": 0,
        "active": true,
        "messageLabel": "Get 15% off combo products",
        "type": "CUSTOMER",
        "condition": {
            "type": "COMBO_PRODUCT",
            "comboProductCondition": {
                "productConditions": [
                    {
                        "criteriaList": [
                            {
                                "entity": "SKU",
                                "operator": "IN",
                                "values": [
                                    "SKU001",
                                    "SKU002"
                                ]
                            }
                        ],
                        "kpi": "QUANTITY",
                        "value": "1.000000",
                        "operator": "GREATER_THAN_OR_EQUAL"
                    },
                    {
                        "criteriaList": [
                            {
                                "entity": "BRAND",
                                "operator": "IN",
                                "values": [
                                    "BRAND_A"
                                ]
                            }
                        ],
                        "kpi": "QUANTITY",
                        "value": "1.000000",
                        "operator": "GREATER_THAN_OR_EQUAL"
                    }
                ]
            }
        },
        "action": {
            "type": "PRODUCT_BASED",
            "productBasedAction": {
                "productBasedCondition": {
                    "type": "COMBO_PRODUCT",
                    "comboProductCondition": {
                        "productConditions": [
                            {
                                "criteriaList": [
                                    {
                                        "entity": "SKU",
                                        "operator": "IN",
                                        "values": [
                                            "SKU001",
                                            "SKU002"
                                        ]
                                    }
                                ],
                                "kpi": "QUANTITY",
                                "value": "1.000000",
                                "operator": "GREATER_THAN_OR_EQUAL"
                            },
                            {
                                "criteriaList": [
                                    {
                                        "entity": "BRAND",
                                        "operator": "IN",
                                        "values": [
                                            "BRAND_A"
                                        ]
                                    }
                                ],
                                "kpi": "QUANTITY",
                                "value": "1.000000",
                                "operator": "GREATER_THAN_OR_EQUAL"
                            }
                        ]
                    }
                },
                "type": "PERCENTAGE",
                "value": "15.000000",
                "includeItemsFromConditionSet": false
            }
        },
        "createdBy": 75197941,
        "createdOn": 1759818712969,
        "createdOnISO": "2025-10-07T06:31:52Z",
        "lastUpdatedBy": 75197941,
        "lastUpdatedOn": 1759818712969,
        "lastUpdatedOnISO": "2025-10-07T06:31:52Z",
        "startDate": 1759363200000,
        "startDateISO": "2025-10-02T00:00:00Z",
        "endDate": 1790985600000,
        "endDateISO": "2026-10-03T00:00:00Z",
        "campaignId": 286038,
        "promotionRestrictions": {
            "Promotion": [
                {
                    "kpi": "REDEMPTION",
                    "limit": "5000.000000"
                }
            ],
            "Cart": [
                {
                    "kpi": "DISCOUNT",
                    "limit": "50.000000"
                }
            ],
            "Customer": [
                {
                    "kpi": "TRANSACTION",
                    "frequency": "WEEKS",
                    "minTimeBetweenRepeat": 604800000,
                    "limit": "2.000000"
                },
                {
                    "kpi": "DISCOUNT",
                    "limit": "200.000000"
                },
                {
                    "kpi": "REDEMPTION",
                    "frequency": "DAYS",
                    "minTimeBetweenRepeat": 86400000,
                    "limit": "3.000000"
                }
            ]
        },
        "earnLimitedToSpecificAudience": true,
        "customFieldValues": {
            "Age": "25"
        },
        "customerActivationRequired": true,
        "mode": "DISCOUNT",
        "maxIssuancePerCustomer": 1,
        "isStackable": false
    }
}

Response parameters

Field	Type	Description
data	Object	Indicates the main container for the cart promotion object.
..id	String	Specifies the unique, system-generated identifier for the cart promotion.
..name	String	Specifies the unique name of the cart promotion.
..orgId	Integer	Specifies the unique identifier for the organization to which this cart promotion belongs.
..type	String	Specifies the type of cart promotion. Possible values: POS, CODE, CUSTOMER, EARNING, REWARD.
..messageLabel	String	Specifies a customer-facing label for the cart promotion message.
..active	Boolean	Specifies if the cart promotion is active. Possible values: true, false.
..priority	Integer	Specifies the order of application, where lower numbers have higher priority (0 is the highest). Defaults to 0 if not explicitly set during creation.
..isStackable	Boolean	Specifies if this cart promotion can be combined with other cart promotions. Defaults to false if not provided. Possible values: true, false.
..startDate	Long	Specifies the start time of the cart promotion in Unix epoch milliseconds (UTC).
..startDateISO	String	Specifies the start time in ISO 8601 format (UTC).
..endDate	Long	Specifies the end time of the cart promotion in Unix epoch milliseconds (UTC).
..endDateISO	String	Specifies the end time in ISO 8601 format (UTC).
..campaignId	String	Specifies the identifier of the campaign that the cart promotion is linked to.
..createdBy	Long	Specifies the unique identifier of the user who created the cart promotion.
..createdOn	Long	Specifies the creation time of the cart promotion in Unix epoch milliseconds (UTC).
..createdOnISO	String	Specifies the creation time in ISO 8601 format (UTC).
..lastUpdatedBy	Long	Specifies the unique identifier of the user who has last updated the cart promotion.
..lastUpdatedOn	Long	Specifies the last updated time of the cart promotion in Unix epoch milliseconds (UTC).
..lastUpdatedOnISO	String	Specifies the last updated time of the cart promotion in ISO 8601 format (UTC).
..condition	Object	Specifies the rules that determine how the cart promotion applies, based on factors like cart subtotal or item types.
....type	String	Specifies the type of condition to evaluate. Possible values: CART, TENDER, COMBO_PRODUCT.
....cartCondition	Object	Contains rules for the entire shopping cart, present if condition.type is CART.
......kpi	String	Specifies the metric used to evaluate the cart. Possible values: SUBTOTAL, ITEMCOUNT.
......operator	String	Specifies the comparison operator. Possible values: EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL.
......value	String	Specifies the numerical value to compare the kpi against, returned as a string.
....tenderCondition	Object	Contains rules based on the customer's payment method, present if condition.type is TENDER.
......tenderModes	Array	Contains an array of specific payment methods that will trigger the condition.
........type	String	Specifies the category of the payment method. Possible value: CARD.
........identifiers	Array	Contains an array of strings for the exact payment methods, such as ["VISA_CARD", "MASTERCARD"].
......condition	Object	Contains a nested condition (typically CART type) that must also be satisfied.
....comboProductCondition	Object	Contains a condition where multiple product sets must be in the cart, present if condition.type is COMBO_PRODUCT.
......productConditions	Array	Contains an array of product conditions that must all be satisfied.
..action	Object	Defines the action taken when the cart promotion applies.
....type	String	Specifies the scope of the action. Possible values: CART_BASED, PRODUCT_BASED, TENDER, PER_UNIT.
....cartBasedAction	Object	Contains an action for the entire cart, present if action.type is CART_BASED.
......type	String	Specifies the type of cart-based action. Possible value: ABSOLUTE.
......value	String	Specifies the fixed monetary amount for the discount, returned as a string.
....tenderBasedAction	Object	Contains the reward action for a tender-based cart promotion, present if action.type is TENDER.
......type	String	Specifies the calculation method. Possible value: ABSOLUTE.
......value	String	Specifies the fixed monetary amount to be discounted, sent as a string.
....perUnitAction	Object	Contains a repeating reward action, present if action.type is PER_UNIT.
......perUnitKPI	String	Specifies the metric used to group items. Possible value: QUANTITY.
......perUnitDivider	String	Specifies the number of units required to trigger one instance of the rewardAction.
......includeItemsFromConditionSet	Boolean	Controls whether the action benefit applies to the same items that satisfied the cart promotion trigger (`true`) or to a different target set defined by productBasedCondition (`false`). Example (true): “Buy 10 A, get $100 off those 10 A.” Example (false): “Buy 10 A, get $100 off B.”
......rewardAction	Object	Contains the specific benefit granted for each qualifying unit group.
........type	String	Specifies the type of per-unit reward action. Possible values: PRODUCT_BASED, FREE_PRODUCT, FIXED_PRICE.
........productBasedAction	Object	Contains a discount on specific products, present if rewardAction.type is PRODUCT_BASED.
..........type	String	Specifies the discount calculation method. Possible values: ABSOLUTE, PERCENTAGE.
..........value	String	Specifies the discount amount or percentage, returned as a string.
..........includeItemsFromConditionSet	Boolean	Controls whether the action benefit applies to the same items that satisfied the cart promotion trigger (`true`) or to a different target set defined by productBasedCondition (`false`). Example (true): “Buy 10 A, get $100 off those 10 A.” Example (false): “Buy 10 A, get $100 off B.”
..........productBasedCondition	Object	Contains the set of products to which the action's benefit will be applied.
............type	String	Specifies the product targeting mode. Possible values: PRODUCT, COMBO_PRODUCT.
............productCondition	Object	Contains target products using a list of criteria.
..............criteriaList	Array	Contains an array of rule objects specifying the products.
................entity	String	Specifies the product attribute to evaluate (e.g., CATEGORY, SKU, BRAND).
................operator	String	Specifies the operator for the list comparison. Possible values: IN, NOT_IN.
................values	Array	Contains an array of strings to match against the entity. Supports up to 100 values in a single array.
..............kpi	String	Specifies an optional metric for filtering products. Possible values: NONE, QUANTITY.
........freeProductAction	Object	Contains a reward action where products are given for free, present if rewardAction.type is FREE_PRODUCT.
..........includeItemsFromConditionSet	Boolean	Controls whether the action benefit applies to the same items that satisfied the cart promotion trigger (`true`) or to a different target set defined by productBasedCondition (`false`). Example (true): “Buy 10 A, get $100 off those 10 A.” Example (false): “Buy 10 A, get $100 off B.”
..........productBasedCondition	Object	Contains exactly which products are to be marked as free.
........fixedPriceAction	Object	Contains a reward action where products are sold at a fixed price, present if rewardAction.type is FIXED_PRICE.
..........value	String	Specifies the new, fixed price for the qualifying items, returned as a string.
..........includeItemsFromConditionSet	Boolean	Controls whether the action benefit applies to the same items that satisfied the cart promotion trigger (`true`) or to a different target set defined by productBasedCondition (`false`). Example (true): “Buy 10 A, get $100 off those 10 A.” Example (false): “Buy 10 A, get $100 off B.”
..........productBasedCondition	Object	Contains exactly which products are to be sold at the fixed price.
..customerActivationRequired	Boolean	Specifies if a customer must opt-in for a cart promotion before it can be redeemed.
..maxIssuancePerCustomer	Integer	Specifies the total number of times this cart promotion can be issued to a single customer.
..earningCriteria	Object	Contains conditions for EARNING type cart promotions, present if the main cart promotion type is EARNING.
....active	Boolean	Specifies if this specific earning rule is active.
....criteriaDsl	String	Specifies a domain-specific language string representing the earning rule.
....criteriaDslJson	String	Specifies an escaped JSON string representation of the criteriaDsl rule.
....criteriaName	String	Specifies a human-readable name for the earning criteria rule.
....duration	Object	Contains a placeholder object for future duration-based earning rules.
....earnedFromType	String	Specifies the type of event that can trigger the rule. Possible value: ACTIVITY.
....eventType	String	Specifies the specific activity that triggers the rule. Possible value: TransactionAdd.
....groupId	Integer	Specifies an identifier for grouping related earning criteria.
....milestoneId	Integer	Specifies an identifier for a specific milestone within an earning program.
..maxEarningPerCustomer	Integer or null	Specifies the maximum number of times a customer can earn the reward action from an EARNING cart promotion.
..promotionRestrictions	Object	Contains usage limits and constraints on the cart promotion.
....Promotion	Array	Indicates the restrictions that apply to the overall cart promotion.
....Customer	Array	Indicates the restrictions that apply per customer.
....Cart	Array	Indicates the restrictions that apply per cart.
....Code	Array	Contains restrictions for CODE type cart promotions.
......kpi	String	Specifies the metric to be limited. Possible values: REDEMPTION, TRANSACTION, DISCOUNT.
......frequency	String	Specifies how often the restriction resets. Possible values: DAYS, WEEKS.
......minTimeBetweenRepeat	Long	Specifies the minimum time between uses in milliseconds.
......limit	String	Specifies the maximum allowed value for the restriction, returned as a string.
..customFieldValues	Object	Indicates a key-value map for storing custom metadata.
..mode	String	Specifies the application mode of the cart promotion. Possible value: DISCOUNT.
..earnLimitedToSpecificAudience	Boolean	Specifies if earning is limited to a specific audience.
..expiryDateChangeJobList	Array	A list of jobs created to change expiry dates for entities related to the cart promotion. This object only appears in the response to an Update cart Promotion call.
....jobType	String	The type of entity whose expiry date is being changed. Possible values: • `ISSUED`: for issued cart promotion. • `EARNED`: for earned rewards. • `CODE`: for promotion codes.
....status	String	The current status of the expiry date change. Possible values: `OPEN`, `IN_PROGRESS`, COMPLETED, FAILED, `CANCELLED`.
....createdOn	Long	Indicates the date and time when this expiry date change job was created.
....createdBy	Long	The system generated ID of the user or system process that created this expiry date change job.
....lastUpdatedOn	Long	Indicates the date and time when this expiry date change job was last updated.
....lastUpdatedBy	Long	The system generated the ID of the user that last updated this expiry date change job.
....message	String	A descriptive message providing details about the expiry date change, including the old and new expiry dates.

{
    "data": {
        "id": "68c3e98baa0d7a770cbb0952",
        "name": "FreeShipping500",
        "orgId": 100737,
        "priority": 1,
        "active": true,
        "messageLabel": "Free Shipping on $500+",
        "type": "CODE",
        "condition": {
            "type": "CART",
            "cartCondition": {
                "kpi": "SUBTOTAL",
                "operator": "GREATER_THAN",
                "value": "500.000000"
            }
        },
        "action": {
            "type": "CART_BASED",
            "cartBasedAction": {
                "type": "ABSOLUTE",
                "value": "20.000000"
            }
        },
        "createdBy": 75152721,
        "createdOn": 1757669771918,
        "lastUpdatedBy": 75152721,
        "lastUpdatedOn": 1757669771918,
        "startDate": 1757388651000,
        "endDate": 1757475051000,
        "campaignId": 39077,
        "promotionRestrictions": {
            "Code": [
                {
                    "kpi": "REDEMPTION",
                    "limit": "1.000000"
                }
            ]
        },
        "earnLimitedToSpecificAudience": false,
        "mode": "DISCOUNT",
        "maxIssuancePerCustomer": 1,
        "isStackable": false
    }
}

Error codes

Code	Description
400	Invalid request. Check required parameters. Ensure all required parameters are provided and valid.
400	SKU values exceed 100. Ensure the SKU values added are under 100 values.
400	Enum value is invalid. The scope must be "REWARD". Pass `scope` as `"REWARD"` only.
400	defaultValue is required when isMandatory is true. Add a `defaultValue` if `isMandatory` is set to `true`.
701	Error while calling the segmentation engine. Check segmentation engine service connectivity and logs.
703	Org timezone fetch failed. Verify org timezone configuration and service availability.
704	Invalid reward type passed. Provide a valid reward type as per API specification.
705	Exceeded maximum active promotions for an org. Deactivate some active promotions before creating a new one.
706	Promotion has expired. Use a valid, non-expired promotion for the operation.
707	The passed promotion type is not supported. Change the promotion type to one supported by the system.
708	Exceeded the max earn per customer limit. Adjust the earn amount or check the customer limits setup.
709	Promotion not in running state. Ensure the promotion is currently running before proceeding.
710	Error while saving earned promotion. Retry after checking backend/infrastructure logs.
711	Error while saving promotion or Could not get product details. Check input data and ensure product service is available.
712	Error while creating/updating emf rules. Check rule configuration and retry or contact support.
713	Earned from type cannot be changed. Do not change `earnedFromType` on existing earned promotions.
714	Earn is not supported for this promotion type. Switch to a supported promotion type for earn operations.
715	Promotion was not issued to current customer. Ensure the promotion was issued to the specified customer.
716	Promotion name must be unique. Use an unused, unique promotion name.
500	Internal server error. Retry the request after a short delay. If the error persists, contact support with details and logs.