This document explains how to create different promotions and coupons based on different conditions.
API mappings
-
Promotion Create: POST /api-offers/promo/create
-
Coupon Create: POST /api-offers/coupon/create
General Rules:
-
evaluate-promotions(under Dynamic Pricing Engine) API evaluates if discounts can be applied based on Price_Kind value.- If PriceKind is _not specified, discounts are applied on any item irrespective if the item is a sale (clearance) item or not.
- If Price_Kind is specified, the item will be checked if it is on clearance or not.
- If PRICEKIND is _set for SALE, then only clearance items will be considered for discount.
- If PRICEKIND is _set for BASE, then only non-clearance items will be considered for discount.
- If free items discount is applied (free items are provided on purchase of a particular product), Price_Kind will be ignored under targetProducts.
{ "key": "PRICE_KIND", "value": "BASE", // could also be SALE "operator": "EQUAL" } -
targetProductkey will define the items that will get discounts. It includes SKU, CATEGORY, ATTRIBUTE and the value should be array of itemIds, array of category Ids, and array of attribute objects respectively. -
Based on the promotion
typementioned,conditionarray will define a different selection of items. -
discountkey defines discount details. -
If you want to select all products, use
kindasSKU, and value as "*". -
"
*" indicates that all SKUs are selected. -
isExclusiveboolean indicates if a coupon could be stacked on promotions. It should always be false for Promotion. If it isfalsefor a coupon, then the coupon could be applied even after a promotion discount is applied on the same item. -
For
eligiblePriceList, if no priceList ID is provided, then by default the discount will be applied to all priceLists. -
Segmentation feature applies to any kind of promotions/coupons as long as
USER_SEGMENTcondition is included, which means promotions/coupons can be applied to a certain segment of customers. Following is an example:
{
"key": "USER_SEGMENT",
"value":[
{
"name": "Membership",
"value": ["Gold", "Silver"]
}
],
"operator": "IN"
}
Different Types of Promotions
Promotion on SKU
- You can create discounts on all SKUs or on selected items based on the value you provide in
targetProductsarray typeshould be PRODUCT
Note:
operator:INindicates the target product is included for discountsoperator:NOT_INindicates the target product is not included for discounts
Following is an example of a discount: Get 10% off on any item
Request Body:
{
"title": "SKU Promo Example",
"startDate": "2023-12-12T13:50:07.589Z",
"endDate": "2023-12-14T08:19:33.453Z",
"isExclusive": false,
"eligiblePriceList": [10000056], // could provide eligible priceListIds if needed
"type": "PRODUCT",
"promo": [
{
"discount": [
{
"unit": "%OFF", // could be "AMOUNT_OFF"
"value": 10,
"ON": {
"kind": "SKU",
"value": null
}
}
],
"targetProducts": [
{
"kind": "SKU",
"value": "*", // [1000000234, 1000000445], could be array of itemIds if want to apply on selected items
"operator": "IN"
}
],
"condition": [ // depending upon number of condition objects, number of condtion IDs will be created in the response body
{
"operator": "AND",
"conditions": [
{
"value": "*", // [1000000234, 1000000445], could be array of itemIds if want to apply on selected items
"operator": "IN",
"key": "SKU"
}
]
}
]
}
],
"termsAndConditions": [
{
"title": "Promotion Example Terms",
"description": "This Promotion is created as an example"
}
]
}
Response:
{
"_id": "abcdefg1ee7ce20123456789",
"promoId": 100013,
"state": "SCHEDULED",
"type": "PRODUCT",
"isImplicit": true,
"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-25T14:15:22Z",
"isExclusive": false,
"title": "CREATE PROMO",
"eligiblePriceList": [10000056],
"createdAt": "2019-08-20T14:15:22Z",
"updatedAt": "2019-08-20T14:15:22Z"
"buyOperator": "OR",
"promo": [
{
"discount": [
{
"unit": "%OFF",
"value": 10,
"ON": {
"kind": "SKU",
"value": null
}
}
],
"targetProducts": [
{
"kind": "SKU",
"value": "*",
"operator": "IN"
}
],
"condition": [
"620d84a715f2d00001234567" // contains one condition ID based on one condition object passed in the request body
]
}
],
"termsAndConditions": [
{
"title": "Terms Applied",
"description": "Items cannot be exchanged"
}
],
}
Promotion on Cart Items
-
Cart Promotion applies discounts when the cart value reaches the set order value
-
Cart Promotion supports tier structure
-
typeshould be CART -
Specify ORDER_VALUE in the
conditionarray for CART promotion
Following is an example of a discount:
-
Spend over $100 on Wooden items and get $10 off
-
Spend over $200 on Wooden items and get $30 off
Request Example:
{
"title": "Cart Promotion Example",
"startDate": "2023-02-08T07:17:24.412Z",
"endDate": "2023-02-09T07:17:24.412Z",
"isExclusive": false,
"type": "CART",
"promo": [
{ // first tier, Buy order value over $100 (and less than $200) for Wooden items, get $10 off
"discount": [
{
"unit": "AMOUNT_OFF",
"value": 10,
"ON": {
"kind": "SKU",
"value": null
}
}
],
"targetProducts": [
{
"value": [
{
"name": "Material",
"value": "Wood"
}
],
"operator": "IN",
"kind": "ATTRIBUTE"
}
],
"condition": [
{
"operator": "AND",
"conditions": [
{
"value": [
{
"name": "Material",
"value": "Wood"
}
],
"operator": "IN",
"key": "ATTRIBUTE"
},
{
"key": "ORDER_VALUE",
"value": "100",
"operator": "GREATER_THAN_OR_EQUAL_TO"
},{
"key": "ORDER_VALUE",
"value": "200",
"operator": "LESS_THAN"
}
]
}
]
},
{ // second tier, Buy order value over $200 for Wooden items, get $30 off
"discount": [
{
"unit": "AMOUNT_OFF",
"value": 30,
"ON": {
"kind": "SKU",
"value": null
}
}
],
"targetProducts": [
{
"value": [
{
"name": "Material",
"value": "Wood"
}
],
"operator": "IN",
"kind": "ATTRIBUTE"
}
],
"condition": [
{
"operator": "AND",
"conditions": [
{
"value": [
{
"name": "Material",
"value": "Wood"
}
],
"operator": "IN",
"key": "ATTRIBUTE"
},
{
"key": "ORDER_VALUE",
"value": "200",
"operator": "GREATER_THAN_OR_EQUAL_TO"
}
]
}
]
}
]
}
Response Example:
{
"_id": "abcdefg1ee7ce20123456789",
"promoId": 100013,
"state": "SCHEDULED",
"type": "CART",
"isImplicit": true,
"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-25T14:15:22Z",
"isExclusive": false,
"title": "CART PROMO",
"eligiblePriceList": [] //empty array indicates that promotion is applicable to all pricelists
"createdAt": "2019-08-20T14:15:22Z",
"updatedAt": "2019-08-20T14:15:22Z"
"buyOperator": "OR",
"promo": [
{
"discount": [
{
"unit": "AMOUNT_OFF",
"value": 10,
"ON": {
"kind": "SKU",
"value": null
}
}
],
"targetProducts": [
{
"value": [
{
"name": "Material",
"value": "Wood"
}
],
"operator": "IN",
"kind": "ATTRIBUTE"
}
],
"condition": [
"620d84a715f2d00001234567"
]
},
{
"discount": [
{
"unit": "AMOUNT_OFF",
"value": 30,
"ON": {
"kind": "SKU",
"value": null
}
}
],
"targetProducts": [
{
"value": [
{
"name": "Material",
"value": "Wood"
}
],
"operator": "IN",
"kind": "ATTRIBUTE"
}
],
"condition": [
"620d84a715f2d00001234567"
]
}
],
}
Promotion on Defined Quantity
You can create Quantity based promotion on the rule you have set while creating a promotion.
-
Quantity promotion supports tier structure
-
typeshould be QUANTITY -
Specify QUANTITY in the
conditionarray for QUANTITY promotion
Following is an example of discount:
- Buy item with quantity more than 5 units but less than 10 units from all other categories except from kitchen category, and get 10% off
- Buy item with quantity over 10 units from all other categories except from kitchen category, and get 15% off
Request Example:
{
"title": "Quantity Promotion Example",
"startDate": "2023-02-08T07:17:24.412Z",
"endDate": "2023-02-09T07:17:24.412Z",
"isExclusive": false,
"type": "QUANTITY",
"promo": [
{ // first tier, Buy quantity over 5 units (less than 10 units) from all other categories except from kitchen category, get 10% off
"discount": [
{
"unit": "%OFF",
"value": 10,
"ON": {
"kind": "SKU",
"value": null
}
}
],
"targetProducts": [
{
"value": ["628f7cc562eb6500094ae116"], // kitchen category id
"operator": "NOT_IN",
"kind": "KITCHEN_CATEGORY"
}
],
"condition": [
{
"operator": "AND",
"conditions": [
{
"value": ["628f7cc562eb6500094ae116"], // kitechen category id
"operator": "NOT_IN",
"key": "KITCHEN_CATEGORY"
},
{
"key": "QUANTITY",
"value": "5",
"operator": "GREATER_THAN_OR_EQUAL_TO"
},{
"key": "QUANTITY",
"value": "10",
"operator": "LESS_THAN"
}
]
}
]
},
{ // second tier, Buy quantity over 10 units from all other categories except from kitchen category, get 15% off
"discount": [
{
"unit": "%OFF",
"value": 15,
"ON": {
"kind": "SKU",
"value": null
}
}
],
"targetProducts": [
{
"value": ["628f7cc562eb6500094ae116"], // kitchen category id
"operator": "NOT_IN",
"kind": "KITCHEN_CATEGORY"
}
],
"condition": [
{
"operator": "AND",
"conditions": [
{
"value": ["628f7cc562eb6500094ae116"], // kitchen category id
"operator": "NOT_IN",
"key": "KITCHEN_CATEGORY"
},
{
"key": "QUANTITY",
"value": "10",
"operator": "GREATER_THAN_OR_EQUAL_TO"
}
]
}
]
}
]
}
Response Example:
{
"_id": "abcdefg1ee7ce20123456789",
"promoId": 100013,
"state": "SCHEDULED",
"type": "QUANTITY",
"isImplicit": true,
"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-25T14:15:22Z",
"isExclusive": false,
"title": "QUANTITY PROMOTION EXAMPLE",
"eligiblePriceList": [] //empty array indicates that promotion is applicable to all pricelists
"createdAt": "2019-08-20T14:15:22Z",
"updatedAt": "2019-08-20T14:15:22Z"
"buyOperator": "OR",
"promo": [
{
"discount": [
{
"unit": "%OFF",
"value": 10,
"ON": {
"kind": "SKU",
"value": null
}
}
],
"targetProducts": [
{
"value": ["628f7cc562eb6500094ae116"], // kitchen category id
"operator": "NOT_IN",
"kind": "KITCHEN_CATEGORY"
}
],
"condition": [
"620d84a715f2d00001234567"
]
},
{
"discount": [
{
"unit": "%OFF",
"value": 15,
"ON": {
"kind": "SKU",
"value": null
}
}
],
"targetProducts": [
{
"value": ["628f7cc562eb6500094ae116"], // kitchen category id
"operator": "NOT_IN",
"kind": "KITCHEN_CATEGORY"
}
],
"condition": ["620d84a715f2d00001234567"]
}
]
}
Promotion on Shipping Cost
-
Promotions can also be applied on shipping costs. You should specify shipmentMethodIds while creating promotions on shipping cost.
-
typeshould be SHIPPING -
If
discount.ON.kindis set as SERVICE, discount is applied at SKU level. Discount will be applied to each unit. -
If
discount.ON.kindis set as SERVICE_CART, discount is applied at cart level. Discount will split between items.
Following is an example of discount: Get $10 shipping off on selected SKUs
Request Example:
{
"title": "SHIPPING Promo Example",
"startDate": "2023-12-12T13:50:07.589Z",
"endDate": "2023-12-14T08:19:33.453Z",
"isExclusive": false,
"eligiblePriceList": ["10000056"] // price list that is eligible for shipping discount
"type": "SHIPPING",
"shipmentMethodIds": ["1000001"], // shipment method Ids that is eligible for shipping discount
"promo": [
{
"discount": [
{
"unit": "AMOUNT_OFF",
"value": 10,
"ON": {
"kind": "SERVICE",
"value": [
// could provide the shipping service info (no restriction in object), for example
{
"label":"DHL - Next Day Delivery"
"isSelected":true
"key":"DHL - Next Day Delivery"
"methodIds":[1000001]
}
]
}
}
],
"targetProducts": [
{
"kind": "SKU",
"value": [1000000234, 1000000445],
"operator": "IN"
}
],
"condition": [
{
"operator": "AND",
"conditions": [
{
"value": [1000000234, 1000000445],
"operator": "IN",
"key": "SKU"
}
]
}
]
}
],
"termsAndConditions": [
{
"title": "Promotion Example Terms",
"description": "This Promotion is created as an example"
}
]
}
Response Example:
{
"_id": "abcdefg1ee7ce20123456789",
"promoId": 100013,
"state": "SCHEDULED",
"type": "SHIPPING",
"isImplicit": true,
"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-25T14:15:22Z",
"isExclusive": false,
"title": "SHIPPING PROMO EXAMPLE",
"shipmentMethodIds": ["1000001"],
"eligiblePriceList": [10000056],
"createdAt": "2019-08-20T14:15:22Z",
"updatedAt": "2019-08-20T14:15:22Z"
"buyOperator": "OR",
"promo": [
{
"discount": [
{
"unit": "AMOUNT_OFF",
"value": 10,
"ON": {
"kind": "SERVICE",
"value": [
{
"label":"DHL - Next Day Delivery"
"isSelected":true
"key":"DHL - Next Day Delivery"
"methodIds":[1000001]
}
]
}
}
],
"targetProducts": [
{
"kind": "SKU",
"value": [1000000234, 1000000445],
"operator": "IN"
}
],
"condition": [
"620d84a715f2d00001234567"
]
}
],
"termsAndConditions": [
{
"title": "Terms Applied",
"description": "Items cannot be exchanged"
}
],
}
BuyGet Promotion
-
BuyGet promotion specifies Buy based on conditions and Get discounts
-
typeshould be BUYGET -
You should specify discountId in discount objects and targetProducts to link the discount to selected products
-
If
discount.ON.kindis set as SKU, quantity should be specified in discount object to limit max quantity the discount can be applied to. Discount will be applied on each unit. -
If
discount.ON.kindis set as CART, quantity should not be specified in discount object. Discount will split between items. -
buyOperatoris used to define operator between different buy conditions (values between theconditionarray) -
BuyGet should not have duplicated items between different buy condition sets
-
BuyGet should not have duplicated items between different get discount sets
-
BuyGet will only support included SKU and Category selection
-
For a free item to be considered in suggestion,
autoAddshould be set astrueand100% offin discount
Following is an example of discount: Buy 5 units from (itemA, itemB, itemC) AND Buy 2 units from (itemD, itemE) , get max 2 units 10% off from (itemF, itemG) AND get max 1 units from (itemA, itemB, itemC) for free
Request Example:
{
"title": "BuyGet Promotion Example",
"startDate": "2023-02-08T07:17:24.412Z",
"endDate": "2023-02-09T07:17:24.412Z",
"isExclusive": false,
"type": "BUYGET",
"buyOperator": "AND",
"promo": [
{
"discount": [
{
"unit": "%OFF",
"value": 10,
"ON": {
"kind": "SKU",
"value": null,
"quantity": 2 // max Quantity limit
},
"discountId": "1"
},{
"unit": "%OFF",
"value": 100,
"ON": {
"kind": "SKU",
"value": null,
"quantity": 1 // max Quantity limit
},
"discountId": "2",
"autoAdd": true // BuyGet Free items could have autoAdd true to be considered as suggested items
}
],
"targetProducts": [
{
"value": [itemG, itemF],
"operator": "IN",
"kind": "SKU",
"discountId": "1"
},
{
"value": [itemA, itemB, itemC],
"operator": "IN",
"kind": "SKU",
"discountId": "2"
}
],
"condition": [
{
"operator": "AND",
"conditions": [
{
"value": [itemA, itemB, itemC], // itemIds
"operator": "IN",
"key": "SKU"
},
{
"key": "QUANTITY",
"value": "5",
"operator": "GREATER_THAN_OR_EQUAL_TO"
}
]
},{
"operator": "AND",
"conditions": [
{
"value": [itemD, itemE], // itemIds
"operator": "IN",
"key": "SKU"
},
{
"key": "QUANTITY",
"value": "2",
"operator": "GREATER_THAN_OR_EQUAL_TO"
}
]
}
]
}
]
}
Response Example:
{
"_id": "abcdefg1ee7ce20123456789",
"promoId": 100013,
"state": "SCHEDULED",
"type": "BUYGET",
"isImplicit": true,
"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-25T14:15:22Z",
"isExclusive": false,
"title": "BuyGet Promotion Example",
"eligiblePriceList": [] //empty array indicates that cart promotion is applicable to all pricelists
"createdAt": "2019-08-20T14:15:22Z",
"updatedAt": "2019-08-20T14:15:22Z"
"buyOperator": "OR",
"promo": [
{
"discount": [
{
"unit": "%OFF",
"value": 10,
"ON": {
"kind": "SKU",
"value": null,
"quantity": 2 // max Quantity limit
},
"discountId": "1"
},{
"unit": "%OFF",
"value": 100,
"ON": {
"kind": "SKU",
"value": null,
"quantity": 1 // max Quantity limit
},
"discountId": "2",
"autoAdd": true // BuyGet Free items could have autoAdd true to be considered as suggested items
}
],
"targetProducts": [
{
"value": [itemG, itemF],
"operator": "IN",
"kind": "SKU",
"discountId": "1"
},
{
"value": [itemA, itemB, itemC],
"operator": "IN",
"kind": "SKU",
"discountId": "2"
}
],
"condition": [
"620d84a715f2d00001234567", "990e67a899f3g01112345678" // two condition IDs for two condition objects passed in the reqest body
]
}
],
}
SPEND_GET Promotion
-
SpendGet promotion specifies the requirement of cart order value and the corresponding Get discounts
-
typeshould beSPEND_GET -
You should specify ORDER_VALUE in condition
-
You should specify discountId (for discount objects) and targetProducts to link the discount to selected products
-
SPEND_GET should not have duplicated items between different discounts
-
You should specify the max
quantityrequirement in discount
Following is an example of discount: Buy order value more than $100, get 3 units of (itemA, itemB) 10% off
Request Example:
{
"title": "SpendGet Promotion Example",
"startDate": "2023-02-08T07:17:24.412Z",
"endDate": "2023-02-09T07:17:24.412Z",
"isExclusive": false,
"type": "SPEND_GET",
"promo": [
{
"discount": [
{
"unit": "%OFF",
"value": 10,
"ON": {
"kind": "SKU",
"value": null,
"quantity": 3 // max Quantity limit
},
"discountId": "1"
}
],
"targetProducts": [
{
"value": [itemA, itemB],
"operator": "IN",
"kind": "SKU",
"discountId": "1"
}
],
"condition": [
{
"operator": "AND",
"conditions": [
{
"value": [itemA, itemB], // Buy requirement items, if not required, could set it to "*" to select All
"operator": "IN",
"key": "SKU"
},
{
"key": "ORDER_VALUE",
"value": "100",
"operator": "GREATER_THAN_OR_EQUAL_TO"
}
]
}
]
}
]
}
Response Example:
{
"_id": "abcdefg1ee7ce20123456789",
"promoId": 100013,
"state": "SCHEDULED",
"type": "SPEND_GET",
"isImplicit": true,
"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-25T14:15:22Z",
"isExclusive": false,
"title": "SpendGet Promotion Example",
"eligiblePriceList": [] //empty array indicates that cart promotion is applicable to all pricelists
"createdAt": "2019-08-20T14:15:22Z",
"updatedAt": "2019-08-20T14:15:22Z"
"buyOperator": "OR",
"promo": [
{
"discount": [
{
"unit": "%OFF",
"value": 10,
"ON": {
"kind": "SKU",
"value": null,
"quantity": 3 // max Quantity limit
},
"discountId": "1"
}
],
"targetProducts": [
{
"value": [itemA, itemB],
"operator": "IN",
"kind": "SKU",
"discountId": "1"
}
],
"condition": [
"620d84a715f2d00001234567"
]
}
],
}
Coupon Examples
Coupons have the same structure as promotion with certain differences as follows:
-
Coupons should include
promoCodesarray in the request- If
promoCodesarray contains only one element or one coupon code, it indicates that the promo codes can be reused. - If
promoCodesarray contains multiple elements or multiple coupon codes, it indicates that each promo code can be reused only once.
- If
-
If you want coupons to be stacked on promotions, set
isExclusiveas false (stackable) -
If you do not want coupons to be stacked on promotions, set
isExclusiveas true (non-stackable) -
coupons can have limit options:
PER_USER,SITE_WIDE,ORDER-
PER_USERwill restrict on the number of times a user can redeem this coupon -
SITE_WIDEwill restrict on the number of times the coupon can be redeemed -
ORDERis applicable to PRODUCT type and BUYGET type only
-
Following is an example of discount: 10% off on Kitchen category that is limited for 2 times per user and total 100 times site wide.
Request Example:
{
"title": "SKU Coupon Example",
"startDate": "2023-12-12T13:50:07.589Z",
"endDate": "2023-12-14T08:19:33.453Z",
"promoCodes": ["SUMMER10"]
"isExclusive": false, // coupon could be stacked on promotion
"type": "PRODUCT",
"promo": [
{
"discount": [
{
"unit": "%OFF",
"value": 10,
"ON": {
"kind": "SKU",
"value": null
}
}
],
"targetProducts": [
{
"kind": "CATEGORY",
"value": ["kitchenCategoryId"],
"operator": "IN"
}
],
"condition": [
{
"operator": "AND",
"conditions": [
{
"value": ["kitchenCategoryId"],
"operator": "IN",
"key": "CATEGORY"
}
]
}
]
}
],
"limits":[
{
"kind": "PER_USER",
"value": 2
},{
"kind": "SITE_WIDE",
"value": 100
}
],
"termsAndConditions": [
{
"title": "Coupon Example Terms",
"description": "This Coupon is created as an example"
}
]
}
Response Example:
{
"_id": "abcdefg1ee7ce20123456789",
"promoId": 100013,
"promoCodes": ["SUMMER10"]
"state": "SCHEDULED",
"type": "PRODUCT",
"isImplicit": false,
"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-25T14:15:22Z",
"isExclusive": false,
"title": "SKU Coupon Example",
"eligiblePriceList": [1000056],
"createdAt": "2019-08-20T14:15:22Z",
"updatedAt": "2019-08-20T14:15:22Z"
"buyOperator": "OR",
"promo": [
{
"discount": [
{
"unit": "%OFF",
"value": 10,
"ON": {
"kind": "SKU",
"value": null
}
}
],
"targetProducts": [
{
"kind": "CATEGORY",
"value": ["kitchenCategoryId"],
"operator": "IN"
}
],
"condition": [
"620d84a715f2d00001234567"
]
}
],
"limits": [
{
"kind": "PER_USER",
"value": 2
},{
"kind": "SITE_WIDE",
"value": 100
}
],
"termsAndConditions": [
{
"title": "Terms Applied",
"description": "Items cannot be exchanged"
}
]
}