Update Cart Promotion

This endpoint allows you to update cart promotion details.

Example request

curl --location --request PUT 'https://eu.api.capillarytech.com/api_gateway/v1/promotions/68de8ef2f398ae3dc8802e20' \
--header 'Content-Type: application/json' \
--header 'X-CAP-API-AUTH-ORG-ID: 100232' \
--header 'user-agent: pyapps_auto_Promotion_Engine_Eucrm_Smoke' \
--header 'Authorization: Basic bmFtYW5fZG9jOxxxxxxxxjZlY2I2MmEy' \
--data '{
    "name": "CODE_Promotion_Test_17573886",
    "priority": 0,
    "active": true,
    "messageLabel": "test!!",
    "type": "CODE",
    "condition": {
      "type": "CART",
      "cartCondition": {
        "kpi": "SUBTOTAL",
        "operator": "EQUALS",
        "value": 250.0
      }
    },
    "action": {
      "type": "CART_BASED",
      "cartBasedAction": {
        "type": "ABSOLUTE",
        "value": 25.0
      }
    },
    "createdBy": 70707,
    "createdOn": 0,
    "lastUpdatedBy": 70707,
    "startDate": "1857388651000",
    "endDate": "1857475051000",
    "campaignId": 39077,
    "mode": "DISCOUNT",
    "promotionRestrictions": {
      "Code": [
        {
          "kpi": "REDEMPTION",
          "limit": 1
        }
      ]
    },
    "isStackable": false
  }'

Prerequisites

  • Authentication: Basic or OAuth authentication.
  • Default access group

Rate limit

  • Demo and Testing Clusters: 1,000 requests per minute per API key
  • Other Organizations: The rate limit is brand-specific.

To modify the limit, create a ticket with the Capillary Product support team.

Path parameters

FieldTypeRequiredDescription
Promotion idStringYesIndicates the unique identifier of the promotion. This is returned in the data.id field of the promotion payload during promotion creation.

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.

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.

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.

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.”

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.

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"}).

earningCriteria

Object

Conditional

Defines the conditions for earning a reward. Required when 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.

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

FieldTypeRequiredDescription
.cartConditionObjectYesDefines rules that apply to the entire shopping cart.
..kpiEnumYesMetric to evaluate. Supported: SUBTOTAL, ITEMCOUNT.
..operatorEnumYesComparison operator. Supported: EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL.
..valueNumberYesThe 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.

..tenderModes

Array

Yes

Lists specific payment modes that trigger this condition.

...type

String

Yes

Specifies the general payment category. Supported values: CARD, CASH.

...identifiers

Array

Conditional

Lists exact payment identifiers. For example, ["VISA_CARD"]. Required only when the type is CARD.

..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.

....operator

Enum

Conditional

Defines how to compare the product metric. Supported value: EQUALS.

....value

String

Conditional

Specifies the target value for the comparison.

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": {}
}'

Cart promotion with the cart promotions condition type as COMBO_PRODUCT

FieldTypeRequiredDescription
.comboProductConditionObjectYesDefines 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.
..productConditionsArrayYesList 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.
...kpiEnumYesMetric used to evaluate each condition. Supported values: NONE, QUANTITY. QUANTITY checks how many qualifying products are in the cart.
...operatorEnumConditionalComparison logic for evaluating the metric. Supported values: EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL.
...valueStringConditionalTarget value for the comparison. The value should 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.
...criteriaListArrayYesDefines which products or attributes are part of the condition. Example: Products where entity = PRODUCT_NAME and values = ["Paint Brush"].
....entityStringYesProduct attribute to evaluate. Example: PRODUCT_NAME, BRAND, or CATEGORY. This should match with the line item names in the Add Transaction API payload.
....operatorEnumYesDefines how attribute values are compared. Supported values: IN, NOT_IN. Example: IN checks if the product belongs to the specified brand or category.
....valuesArrayYesList 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.

FieldTypeRequiredDescription
.productConditionObjectYesDefines rules that apply to specific products in the shopping cart.
..criteriaListArrayYesDefines the specific products that must be present in the cart to satisfy the condition.
...entityStringYesThe product attribute to evaluate. Example: SKU, BRAND, or CATEGORY.
...operatorEnumYesDefines how attribute values are compared. Supported: IN, NOT_IN.
...valuesArrayYesList of attribute values to match against the entity.
..kpiEnumYesMetric used to evaluate the matching products. Supported: NONE, QUANTITY, AMOUNT.
..operatorEnumConditionalComparison logic for the metric. Supported: EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL. Required if kpi is not NONE.
..valueStringConditionalTarget 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": {}
}'\'''

**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?
ConceptPurposeExample
conditionSpecifies the trigger criteria for the cart promotion.When the cart subtotal is ₹1,000 or more.
actionSpecifies 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 TypeWhen to Use ItWhat It DoesExample cart Promotion
CART_BASEDWhen 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.
TENDERWhen 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_BASEDWhen 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_PRODUCTFor "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_PRICETo 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_UNITWhen 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 (fixed monetary discount).

..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

FieldTypeRequiredDescription
.tenderBasedActionObjectYesDefines 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.
..typeEnumYesSpecifies how the discount or reward action amount is calculated. Supported value: ABSOLUTE, PERCENTAGE.
..valueStringYesSpecifies the amount 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

Yes

Defines the set of products to which the action's benefit will be applied. The main condition decides when the cart promotion should trigger and the action-level condition here decides which products and the benefit applies to once it triggers.

...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. 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. Example: QUANTITY = 1 ensures each product is present at least once.

.....operator

Enum

Conditional

Logical operator. Supported values: EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL.

.....value

String

Conditional

Numeric target for KPI comparison. This should be defiend 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 for inclusion. 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

Yes

Defines the set of products to which the benefit will be applied.

.....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.

.......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.

......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.

.......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.

......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.

.......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.

......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.

.......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.

........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.

.....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_EQUAL.

.....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.

.....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.

..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

Optional

Minimum time between uses in milliseconds. Example: 86400000 (1 day).

..limit

String

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 Z2VvcmdlLmJ1a2w6NzYzNDkxOGFU4ZjY3MmNhZjY1ZmY=' \
--header 'Cookie: _cfuvid=m_cAUxdAS9kIldmg15w1dpuKfA-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
    }
}'

Example response

{
    "data": {
        "id": "68de8ef2f398ae3dc8802e20",
        "name": "CODE_Promotion_Test_17573886",
        "orgId": 100737,
        "priority": 0,
        "active": true,
        "messageLabel": "test!!",
        "type": "CODE",
        "condition": {
            "type": "CART",
            "cartCondition": {
                "kpi": "SUBTOTAL",
                "operator": "EQUALS",
                "value": "250.000000"
            }
        },
        "action": {
            "type": "CART_BASED",
            "cartBasedAction": {
                "type": "ABSOLUTE",
                "value": "25.000000"
            }
        },
        "createdBy": 75197941,
        "createdOn": 1759416050903,
        "createdOnISO": "2025-10-02T14:40:50Z",
        "lastUpdatedBy": 75152721,
        "lastUpdatedOn": 1759416683389,
        "lastUpdatedOnISO": "2025-10-02T14:51:23Z",
        "startDate": 1857388651000,
        "startDateISO": "2028-11-09T13:17:31Z",
        "endDate": 1857475051000,
        "endDateISO": "2028-11-10T13:17:31Z",
        "campaignId": 39077,
        "promotionRestrictions": {
            "Code": [
                {
                    "kpi": "REDEMPTION",
                    "limit": "1.000000"
                }
            ]
        },
        "earnLimitedToSpecificAudience": false,
        "mode": "DISCOUNT",
        "maxIssuancePerCustomer": 1,
        "isStackable": false,
        "expiryDateChangeJobList": [
            {
                "jobType": "CODE",
                "status": "OPEN",
                "createdOn": 1759416683395,
                "createdOnISO": "2025-10-02T14:51:23Z",
                "lastUpdatedOn": 1759416683395,
                "lastUpdatedOnISO": "2025-10-02T14:51:23Z",
                "lastUpdatedBy": 75152721,
                "createdBy": 75152721,
                "message": "Changed to 'Expire on 2028-11-10T13:17:31Z' from 'Expire on 2025-09-23T18:29:59.999Z'",
                "requestId": "1778756bcb13f7d6b3d65587ae38f6da"
            }
        ]
    }
}

Response parameters

FieldTypeDescription
dataObjectContains the main container for the promotion object.
..idStringSpecifies the unique, system-generated identifier for the promotion.
..nameStringSpecifies the unique name of the promotion.
..orgIdIntegerSpecifies the unique identifier for the organization to which this promotion belongs.
..typeStringSpecifies the type of promotion. Possible values: POS, CODE, CUSTOMER, EARNING, REWARD.
..messageLabelStringSpecifies a customer-facing label for the promotion message.
..activeBooleanSpecifies if the promotion is active. Possible values: true, false.
..priorityIntegerSpecifies the order of application, where lower numbers have higher priority (0 is the highest). Defaults to 0 if not explicitly set.
..isStackableBooleanSpecifies if this promotion can be combined with other promotions. Defaults to false if not provided. Possible values: true, false.
..startDateLongSpecifies the start time of the promotion in Unix epoch milliseconds (UTC).
..startDateISOStringSpecifies the start time in ISO 8601 format (UTC).
..endDateLongSpecifies the end time of the promotion in Unix epoch milliseconds (UTC).
..endDateISOStringSpecifies the end time in ISO 8601 format (UTC).
..campaignIdStringSpecifies the identifier of the campaign that the promotion is linked to.
..createdByLongSpecifies the unique identifier of the user who created the promotion.
..createdOnLongSpecifies the creation time in Unix epoch milliseconds (UTC).
..createdOnISOStringSpecifies the creation time in ISO 8601 format (UTC).
..lastUpdatedByLongSpecifies the unique identifier of the user who last updated the promotion.
..lastUpdatedOnLongSpecifies the last update time in Unix epoch milliseconds (UTC).
..lastUpdatedOnISOStringSpecifies the last update time in ISO 8601 format (UTC).
..conditionObjectDefines the conditions under which the promotion applies.
....typeStringSpecifies the type of condition to evaluate. Possible values: CART, TENDER, COMBO_PRODUCT.
....cartConditionObjectContains rules for the entire shopping cart, present if condition.type is CART.
......kpiStringSpecifies the metric used to evaluate the cart. Possible values: SUBTOTAL, ITEMCOUNT.
......operatorStringSpecifies the comparison operator. Possible values: EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL.
......valueStringSpecifies the numerical value to compare the kpi against, returned as a string.
....tenderConditionObjectContains rules based on the customer's payment method, present if condition.type is TENDER.
......tenderModesArrayContains an array of specific payment methods that will trigger the condition.
........typeStringSpecifies the category of the payment method. Possible value: CARD, CASH.
........identifiersArrayContains an array of strings for the exact payment methods, such as ["VISA_CARD", "MASTERCARD"].
......conditionObjectContains a nested condition (typically CART type) that must also be satisfied.
....comboProductConditionObjectContains a condition where multiple product sets must be in the cart, present if condition.type is COMBO_PRODUCT.
......productConditionsArrayContains an array of product conditions that must all be satisfied.
..actionObjectDefines the action taken when the promotion applies.
....typeStringSpecifies the scope of the action. Possible values: CART_BASED, PRODUCT_BASED, TENDER, PER_UNIT.
....cartBasedActionObjectContains an action for the entire cart, present if action.type is CART_BASED.
......typeStringSpecifies the type of cart-based action. Possible value: ABSOLUTE.
......valueStringSpecifies the fixed monetary amount for the discount, returned as a string.
....tenderBasedActionObjectContains the reward for a tender-based promotion, present if action.type is TENDER.
......typeStringSpecifies the calculation method. Possible value: ABSOLUTE.
......valueStringSpecifies the fixed monetary amount to be discounted, sent as a string.
....perUnitActionObjectContains a repeating reward, present if action.type is PER_UNIT.
......perUnitKPIStringSpecifies the metric used to group items. Possible value: QUANTITY.
......perUnitDividerStringSpecifies the number of units required to trigger one instance of the rewardAction.
......includeItemsFromConditionSetBooleanSpecifies if the action applies to the same items that triggered the condition.
......rewardActionObjectContains the specific benefit granted for each qualifying unit group.
........typeStringSpecifies the type of per-unit reward. Possible values: PRODUCT_BASED, FREE_PRODUCT, FIXED_PRICE.
........productBasedActionObjectContains a discount on specific products, present if rewardAction.type is PRODUCT_BASED.
..........typeStringSpecifies the discount calculation method. Possible values: ABSOLUTE, PERCENTAGE.
..........valueStringSpecifies the discount amount or percentage, returned as a string.
..........includeItemsFromConditionSetBooleanSpecifies if the discount applies to a different set of products than the triggering ones.
..........productBasedConditionObjectContains the set of products to which the action's benefit will be applied.
............typeStringSpecifies the product targeting mode. Possible values: PRODUCT, COMBO_PRODUCT.
............productConditionObjectContains target products using a list of criteria.
..............criteriaListArrayContains an array of rule objects specifying the products.
................entityStringSpecifies the product attribute to evaluate (e.g., CATEGORY, SKU, BRAND).
................operatorStringSpecifies the operator for the list comparison. Possible values: IN, NOT_IN.
................valuesArrayContains an array of strings to match against the entity.
..............kpiStringSpecifies an optional metric for filtering products. Possible values: NONE, QUANTITY.
........freeProductActionObjectContains a reward where products are given for free, present if rewardAction.type is FREE_PRODUCT.
..........includeItemsFromConditionSetBooleanSpecifies if the free products are different from the triggering ones.
..........productBasedConditionObjectContains exactly which products are to be marked as free.
........fixedPriceActionObjectContains a reward where products are sold at a fixed price, present if rewardAction.type is FIXED_PRICE.
..........valueStringSpecifies the new, fixed price for the qualifying items, returned as a string.
..........includeItemsFromConditionSetBooleanSpecifies if the fixed price applies to products different from the triggering ones.
..........productBasedConditionObjectContains exactly which products are to be sold at the fixed price.
..customerActivationRequiredBooleanSpecifies if a customer must opt-in for a promotion before it can be redeemed.
..maxIssuancePerCustomerIntegerSpecifies the total number of times this promotion can be issued to a single customer.
..earningCriteriaObjectContains conditions for EARNING type promotions, present if the main type is EARNING.
....activeBooleanSpecifies if this specific earning rule is active.
....criteriaDslStringSpecifies a domain-specific language string representing the earning rule.
....criteriaDslJsonStringSpecifies an escaped JSON string representation of the criteriaDsl rule.
....criteriaNameStringSpecifies a human-readable name for the earning criteria rule.
....durationObjectContains a placeholder object for future duration-based earning rules.
....earnedFromTypeStringSpecifies the type of event that can trigger the rule. Possible value: ACTIVITY.
....eventTypeStringSpecifies the specific activity that triggers the rule. Possible value: TransactionAdd.
....groupIdIntegerSpecifies an identifier for grouping related earning criteria.
....milestoneIdIntegerSpecifies an identifier for a specific milestone within an earning program.
..maxEarningPerCustomerInteger or nullSpecifies the maximum number of times a customer can earn the reward from an EARNING promotion.
..promotionRestrictionsObjectContains usage limits and constraints on the promotion.
....PromotionArrayContains restrictions that apply to the overall promotion.
....CustomerArrayContains restrictions that apply per customer.
....CartArrayContains restrictions that apply per cart.
....CodeArrayContains restrictions for CODE type promotions.
......kpiStringSpecifies the metric to be limited. Possible values: REDEMPTION, TRANSACTION, DISCOUNT.
......frequencyStringSpecifies how often the restriction resets. Possible values: DAYS, WEEKS.
......minTimeBetweenRepeatLongSpecifies the minimum time between uses in milliseconds.
......limitStringSpecifies the maximum allowed value for the restriction, returned as a string.
..customFieldValuesObjectContains a key-value map for storing custom metadata.
..modeStringSpecifies the application mode of the promotion. Possible value: DISCOUNT.
..earnLimitedToSpecificAudienceBooleanSpecifies if earning is limited to a specific audience.
..expiryDateChangeJobListArrayContains a log of jobs created to change expiry dates for entities related to the promotion. This object only appears in the response to an Update Promotion call.
....jobTypeStringSpecifies the type of entity whose expiry date is being changed. Possible values: ISSUED, EARNED, CODE.
....statusStringSpecifies the current status of the change job. Possible values: OPEN, IN_PROGRESS, COMPLETED, FAILED, CANCELLED.
....createdOnLongSpecifies when the change job was created (epoch millis UTC).
....createdOnISOStringSpecifies when the change job was created in ISO 8601 format.
....createdByLongSpecifies the system-generated ID of the user or process that created this job.
....lastUpdatedOnLongSpecifies when the change job was last updated (epoch millis UTC).
....lastUpdatedOnISOStringSpecifies when the change job was last updated in ISO 8601 format.
....lastUpdatedByLongSpecifies the system-generated ID of the user that last updated this job.
....messageStringContains a descriptive message about the expiry date change, including the old and new dates.
....requestIdStringSpecifies the unique request ID associated with the update action.

Error codes

CodeDescription
400Invalid request. Check required parameters.
400Enum value is invalid. Check type, kpi, operator fields for valid values.
401Unauthorized. Check your authentication credentials.
500Internal server error. Retry the request after a short delay.
Language
URL
Click Try It! to start a request and see the response here!