name

String

Yes

Indicates a unique name of the promotion.Character limit : 1-50.

priority

Integer

Yes

Specifies the order in which promotions are applied. Lower numbers have higher priority. By default, the priority value is 0. Promotions with priority 0 are applied first. Example If there are three promotions—A (priority 0), B (priority 1), and C (priority 2)

The order of application will be: Promotion A(priority 0) Promotion A (priority 1) Promotion C (priority 2)

Note: If customerActivationRequired is enabled for a promotio, the customer must activate it. In this case, the priority order does not apply.

active

Boolean

Yes

Indicates if the promotion is active. Supported values are true and false.

messageLabel

String

Yes

Specifies a label for the promotion message. There is no character limit set for labels. Example: SummerSale2025

type

Enum

Yes

Specifies the type of promotion. Supported values are: POS (Point of Sale): Applies automatically at checkout when cart or purchase conditions are met. No code or customer action is required. CODE: Requires the customer to enter a promotion code for redemption. CUSTOMER: Targets specific customer segments or individuals based on attributes or behaviour. Applies automatically when criteria are met. 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.

.condition

Object

Yes

Specifies the rules that determine how the promotion applies. Conditions can be based on factors such as cart subtotal or on the type of items in the cart.

..type

Enum

Yes

Specifies the type of condition used to evaluate a promotion. Supported values are: CART: Conditions based on the entire shopping cart. Example: “Receive free shipping when you buy 5 or more items.” ITEM: Conditions based on individual items in the cart. Example: “Get 20% off laptops priced over $800.”

..cartCondition

Object

Conditional

Defines rules that apply to the entire shopping cart. This object is required when condition.type is set to CART. Example Cart subtotal GREATER_THAN 500 Total item count EQUALS 3

....kpi

Enum

Yes

Specifies the metric used to evaluate the cart condition. Supported values are: SUBTOTAL: The total price of all items in the cart. TOTAL_QUANTITY: The sum of quantities of all items in the cart. ITEM_COUNT: The count of unique items in the cart. Examples SUBTOTAL GREATER_THAN 500 Apply promotion if the cart total exceeds $500. Business example: “Spend more than $500 and get free shipping.” TOTAL_QUANTITY EQUALS 3 Apply promotion if the cart has exactly 3 items (regardless of type). Business example: “Buy any 3 products and get 10% off.” TOTAL_ITEMS GREATER_THAN_OR_EQUALS 2 Apply promotion if the cart contains 2 or more unique products. Business example: “Purchase 2 different categories of items and receive a free gift.”

....operator

Enum

Yes

Specifies the comparison operator used for the cart condition. Supported values: EQUALS GREATER_THAN LESS_THAN GREATER_THAN_OR_EQUALS LESS_THAN_OR_EQUALS Examples TOTAL_QUANTITY EQUALS 3 “Apply the promotion if the cart has exactly 3 items.” SUBTOTAL GREATER_THAN 500 “Apply the promotion if the cart total exceeds $500.” TOTAL_ITEMS LESS_THAN_OR_EQUALS 1 “Apply the promotion if the cart has only 1 unique product.”

....value

Number

Yes

Specifies the number to compare against for the cart condition. The value can be an integer or a decimal. Examples SUBTOTAL GREATER_THAN_OR_EQUALS 250 “Apply the promotion if the cart subtotal is $250 or more.” TOTAL_QUANTITY EQUALS 3 “Apply the promotion if the cart has exactly 3 items.” SUBTOTAL LESS_THAN 100.50 “Apply the promotion if the cart subtotal is less than $100.50.”.

action

Object

Yes

Specifies what happens when the promotion is applied. The action defines the scope of the discount or reward. Example If action.type = CART_BASED The promotion applies to the entire cart. If action.type =ITEM_BASED The promotion applies only to specific items.

..type

Enum

Yes

Specifies the scope of the action when the promotion is applied. Supported values: CART_BASED: Applies to the entire cart. Example: “Get 10% off the total cart value when you spend $500 or more.” ITEM_BASED: Applies to specific items in the cart. Example: “Buy any 2 shirts and get 1 free.”

..cartBasedAction

Object

Conditional

Defines the action that applies to the entire shopping cart. Use this when actionType is set to CART_BASED. Examples “15% discount on the total cart amount.” “$50 off when the cart subtotal is $500 or more.”

....type

Enum

Yes

Specifies the type of cart-based action. Supported values: ABSOLUTE: A fixed monetary discount. Example: “Get $100 off purchases above $600.” PERCENTAGE: A percentage discount on the cart total. Example: “Get 20% off purchases above $1,000.”

....value

Number

Yes

Specifies the value for the cart-based action. This can be an integer or a decimal, depending on the action type. For ABSOLUTE, the value is a currency amount. Example: 100 → “$100 discount.” For PERCENTAGE, the value is a percentage. Example: 20 → “20% discount.”

startDate

Long

Yes

Specifies the date and time when the promotion becomes active. The value is expressed 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 promotion was created. The value is expressed as a Unix epoch timestamp in milliseconds (UTC). Example 1726123456789 corresponds to 2024-09-12 10:24:16 UTC

campaignId

Long

Yes

Specifies the unique identifier of the campaign that the promotion is linked to. Example If a promotion belongs to the “Holiday Sale 2025” campaign with ID 12345, then campaignId = 12345.

mode

Enum

Yes

Specifies how the promotion is applied. Supported values: DISCOUNT: Provides a direct monetary reduction in the current purchase. Example: “Spend $100 and get $20 off instantly.” PAYMENT_VOUCHER: Issues a voucher that the customer can redeem on a future purchase. Example: “Spend $100 and receive a $20 voucher for your next order.”

.promotionRestrictions

Object

Optional

Defines the limitations applied to the promotion, if any. Restrictions are grouped by level, which specifies where the restriction applies. Supported levels include: CODE: Restricts usage to specific promotion codes. CUSTOMER: Restricts eligibility to certain customers or segments. CART: Restricts based on cart conditions (e.g., minimum subtotal). EARN: Restricts how rewards are earned. PROMOTION: Restricts promotion usage or stacking with other promotions.

..Code

Array of Objects

Optional

Specifies restrictions that apply to promotion codes. This is an array of objects, where each object defines a key performance indicator (KPI) and its limit.

....kpi

Enum

Yes

Specifies the metric used to apply the restriction. Supported values: REDEMPTION: Limits how many times a specific promotion can be redeemed. Example: A promotion code with a REDEMPTION limit of 1 per customer: “Each customer can use this code only once.” TRANSACTION: Limits the number of transactions in which a promotion can be applied. Example: A “first-time buyer” promotion with a TRANSACTION limit of 1: “The promotion applies only on the customer’s first purchase.” DISCOUNT: Caps the total monetary value of the discount a promotion can provide. Example: A “10% off” promotion with a DISCOUNT limit of 50 : “Even if 10% of the order is $100, the customer receives only $50 off.”

....limit

Number

Yes

Specifies the maximum allowed value for the restriction. Must be a positive integer. Examples REDEMPTION limit = 1 : A customer can redeem the promotion only once. TRANSACTION limit = 1 : The promotion applies only to the customer’s first purchase. DISCOUNT limit = 50: The maximum discount a customer can receive is $50. .

isStackable

Boolean

Yes

Indicates whether this promotion can be used together with other promotions. Supported values: true, false Default: false (if not specified) Examples true → “This promotion can be combined with other active promotions.” false → “This promotion cannot be combined with any other promotion.”