Create Cart Promotion

Lets you create any type of cart promotion.



Notes

  • Mandatory fields are indicated with an asterisk
  1. The condition and action parameters exist in nested structures in the JSON:

    • Cart condition parameters are nested under condition.cartCondition
    • Product condition parameters are nested under condition.productCondition
    • Combo product condition parameters are nested under condition.comboProductCondition
    • Tender condition parameters are nested under condition.tenderCondition
    • Cart-based action parameters are nested under action.cartBasedAction
    • Product-based action parameters are nested under action.productBasedAction
    • Product-based condition parameters are nested under action.productBasedAction.productBasedCondition
    • Tender-based action parameters are nested under action.tenderBasedAction
  2. Tender condition must be paired with a tender action for consistency.

  3. Default value for maxIssuancePerCustomer is 1, with valid range from -1 to 50.

  4. Default value for isStackable is false.

  5. Default value for priority is 0.

  6. Priority values should be unique within a campaign for deterministic behavior.

  7. All datetime values are in milliseconds since epoch in UTC timezone.

  8. When stacking is enabled, the stacking strategy at the organization level determines how multiple promotions are applied.

  9. Read-only fields cannot be set in requests but are included in responses.

  10. For tender conditions, CARD type requires an identifier specifying the card network or bank.

  11. The combo product condition is satisfied when ALL individual product conditions in the array are met, creating a bundle or meal-deal type of promotion.

  12. This API is not currently exposed externally.

  13. Validation Rules:

    • Percentage values must be between 0 and 100
    • Amount values must be positive and have up to 2 decimal places
    • Dates must be valid future timestamps
    • Priority values must be unique within a campaign
    • Product quantities must be positive integers
  14. Error Handling:

    • Invalid combinations of conditions and actions will return a 400 Bad Request
    • Missing required fields will return a 400 Bad Request
    • Invalid parameter values will return a 400 Bad Request
    • System errors will return a 500 Internal Server Error

Promotion API Parameters

Basic Parameters

ParameterData TypeDescription
Basic Promotion Info
name*stringUnique name for this cart promotion (max 50 characters).
orgId*longYour organization's ID number.
priority*intSets which cart promotions is applied first (higher number = higher priority). Default is 0.
active*booleanTurns cart promotion on (true) or off (false). Inactive promotions don't apply even if conditions match.
messageLabel*stringText shown to customers when cart promotion applies, like "Holiday Sale 25% Off".
type*enumCart promotion context: POS (in-store), CODE (discount code), CUSTOMER (specific customers), EARNING (points), REWARD (redeeming).
startDate*longStart time in epoch Time Stamp. Cart promotion won't work before this time.
endDate*longEnd time in milliseconds since epoch. Cart promotion stops working after this time.
campaignIdlongLinks this Cart promotion to a marketing campaign.
Metadata
createdBylongID of creator.
createdOnlongCreation time in epoch Time-Stamp.
lastUpdatedBylongID of last editor.
lastUpdatedOnlongLast update time in epoch Time-Stamp.
Customer Settings
customerActivationRequiredbooleanIf true, customers must enable this cart promotion manually. Default is false.
isLoyaltyOnly*booleanIf true, only loyalty program members can use this cart promotion.
mode*enumBasic promotion type: DISCOUNT (cheaper price) or REWARD (get a reward).
maxIssuancePerCustomer*intHow many times each customer can use this cart promotion (-1 means unlimited, max is 50). Default is 1.
isStackable*booleanIf true, works with other cart promotions on same item. Default is false.
expiryDateChangeJobListarrayScheduled tasks that update cart promotion end dates.
Custom Fields
customFieldValuesobjectExtra data fields for your business needs.

Condition Types

type*Description
CARTBased on cart total or item count. Examples: "Spend $50 get $10 off" or "Buy 3 items get 15% off"
PRODUCTBased on specific products. Example: "25% off all shoes"
COMBO_PRODUCTRequires buying certain products together. Example: "Buy burger and fries, get free drink"
TENDERBased on payment method. Example: "10% off when paying with VISA"

Cart Condition Parameters

ParameterData TypeDescription
kpi*enumWhat value is to be measured to issue cart promotion: SUBTOTAL (cart value) or ITEMCOUNT (number of items)
operator*enumHow to compare: EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL
value*decimalThe target amount or count (like $50 minimum spend). Must be positive, up to 2 decimal places.

Product Condition Parameters

ParameterData TypeDescription
kpi*enumWhat to measure: AMOUNT (product value), QUANTITY (item count), or NONE (just check if present)
operator*enumHow to compare: EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL
value*decimalThe target amount, count, or size needed
criteriaList*arrayRules for which products count. Can filter by SKU, CATEGORY, BRAND, TAG, ATTRIBUTE. (See Entity Types section for details)

Combo Product Condition Parameters

ParameterData TypeDescription
productConditions*arrayList of products required in the cart for promotion to work.

Each item in the productConditions array has the following structure:

ParameterData TypeDescription
criteriaList*arrayRules for which products count for this part of the combo.
kpi*enumWhat to measure: QUANTITY (item count) or AMOUNT (product value).
value*decimalHow many or how much is required for the criteria to be fullfilled.
operator*enumHow to compare (EQUALS or GREATER_THAN_OR_EQUAL).

Tender Condition Parameters

ParameterData TypeDescription
type*enumPayment type: CARD (credit/debit cards), CASH, or PAYMENT_VOUCHER (gift cards)
identifier*stringSpecific payment method code (like "VISA", "NETS"). Required for card payments.
conditionobjectOptional nested condition for additional rules (e.g., product conditions for card type)

Action Types

type*Description
FIXED_PRICESets exact price for items. Example: "Any pizza for $5"
CART_BASEDApplies to entire cart. Example: "10% off everything"
PRODUCT_BASEDApplies to specific items. Example: "30% off selected shirts"
FREE_PRODUCTGives free items. Example: "Buy one, get one free"
TENDERDiscount for payment method. Example: "5% off with store credit card"
PER_UNITDiscount per unit. Example: "50¢ off per gallon"

Cart-Based Action Parameters

ParameterData TypeDescription
type*enumDiscount type: PERCENTAGE (% off) or ABSOLUTE (fixed amount off)
value*decimalDiscount amount: for percentage (0-100) or actual money amount

Product-Based Action Parameters

ParameterData TypeDescription
type*enumDiscount type: PERCENTAGE (% off) or ABSOLUTE (fixed amount off)
value*decimalDiscount amount: for percentage (0-100) or actual money amount
includeItemsFromConditionSetbooleanIf true, discount applies to trigger items. If false (default), can discount different items.
productBasedCondition*objectSpecifies which items get discounted if different from trigger items.

Product-Based Condition Structure

ParameterData TypeDescription
type*enumCondition type: PRODUCT, CART, or COMBO_PRODUCT
productCondition*objectProduct rules when type is PRODUCT
cartCondition*objectCart rules when type is CART
comboProductCondition*objectCombo product rules when type is COMBO_PRODUCT

Tender-Based Action Parameters

ParameterData TypeDescription
type*enumDiscount type: PERCENTAGE (% off) or ABSOLUTE (fixed amount off)
value*decimalDiscount amount: for percentage (0-100) or actual money amount

Loyalty & Earning Parameters

ParameterData TypeDescription
loyaltyEarningExpiryDaysintDays until earned points expire. 0 means never expire.
maxEarningPerCustomerintMaximum points one customer can earn from this promotion.
earningCriteriaobjectRules for calculating points.
promotionRestrictionsobjectExtra limits on how cart promotion works.
earnLimitedToSpecificAudiencebooleanIf true, only certain customer groups can earn points.

Additional Criteria Parameters

ParameterData TypeDescription
timeCriteriaobjectTime rules: days of week, hours, holidays when cart promotion works.
storeCriteriaobjectStore location rules: which stores offer this cart promotion.
supplementaryCriteriaobjectExtra rules like loyalty tier or program membership.
redeemableFromCriteriaobjectRules for when promotion can be used after being earned.
ownershipCriteriaobjectRules for who can edit this cart promotion.

Communication Parameters

ParameterData TypeDescription
onEarnCommunicationChannelsobjectHow to notify customers (SMS, email, app) when they get this promotion.
languagesConfiguredarrayLanguages this promotion supports.

Additional KPI Values

KPIDescription
NONEJust checks if products exist in cart, ignores quantity and price.

Fixed Price Action Parameters

ParameterData TypeDescription
value*decimalThe price customers pay, replacing regular price.

Free Product Action Parameters

ParameterData TypeDescription
productCriteria*objectRules for which items can be given for free.
quantity*decimalHow many free items to give.

Per Unit Action Parameters

ParameterData TypeDescription
type*enumDiscount type: PERCENTAGE (% off) or ABSOLUTE (fixed amount off)
value*decimalDiscount per unit: percentage or amount per unit
unitTypeenumUnit type: EACH, LITER, GALLON, etc.

Entity Types for Product Selection

EntityDescriptionAdditional Parameters
SKUProduct codeNone
CATEGORYProduct group or departmentNone
BRANDManufacturer or brand nameNone
TAGCustom product tagNone
ATTRIBUTEProduct feature (size, color, etc.)attributeName: Required string specifying the feature to check

Common Operator Values

OperatorDescription
EQUALSValue must exactly match the specified amount
GREATER_THANValue must be strictly greater than the specified amount
GREATER_THAN_OR_EQUALValue must be greater than or equal to the specified amount
LESS_THANValue must be strictly less than the specified amount
LESS_THAN_OR_EQUALValue must be less than or equal to the specified amount
NONENo comparison needed. Used with KPI NONE.

List Operator Values

OperatorDescription
INValue must be in the specified list
NOT_INValue must not be in the specified list
Language
Credentials
Basic
base64
:
URL
Click Try It! to start a request and see the response here!