You are here:
Design Promotions Programmatically
Use the Promotion Creation API to create, configure, and manage promotions. System integrators can seamlessly integrate the API with external systems where users such as store managers can create promotions.
Required Editions
| Available in: Lightning Experience |
| Available in: Enterprise, Unlimited, and Developer Editions with Real-Time Offer Management |
To create a promotion, specify the primary details, promotion rules, and rewards. When you specify the details of the rules and rewards, map the details that you specify with the type of promotion template that you want to use in the promotion. You can also specify eligibility criteria and limits for the promotion.
You can also use the API to update and delete promotions, and to retrieve promotion details. To understand how to design a promotion, see Quick Promotion Wizard steps.
Here's what the Promotion Creation API's request looks like when the API is executed:
{
"promotionDetails": {
"name": "Summer Sale",
"displayName": "Summer Sale Promotion",
"priorityNumber": 1,
"description": "Summer Sale promotion offering a 10% discount on purchases over $50",
"promotionCode": "SUMMER2025",
"startDateTime": "2025-06-01T00:00:00.000Z",
"endDateTime": "2025-06-30T23:45:00.000Z",
"loyaltyProgram": {
"name": "CloudKicksLoyalty"
},
"promotionEligibility": {
"productCatalog": {
"id": "0ZSxx000000001dGAA"
},
"eligibleProductCategories": [
{
"id": "Summer Sneakers"
}
],
"eligibleChannels": [
{
"channelType": "Online",
"channel": {
"name": "App"
}
}
],
"eligibleSegments": [
{
"name": "Loyal Customers"
}
],
"areAllLoyaltyMembersEligible": false
},
"promotionLimits": {
"usePerCustomerLimit": 5,
"totalUseLimit": 1000
}
},
"rules": [
{
"templateName": "BuyXToGetRewards",
"ruleName": "SummerSaleRule",
"priority": 1,
"eventConfiguration": [
{
"allOf": [
{
"anyOf": {
"purchaseType": "ProductCategory",
"applicablePurchaseList": [
{
"name": "Summer Sneakers"
}
],
"purchaseCriteria": {
"type": "Amount",
"value": 50
}
}
}
]
}
],
"rewardConfiguration": [
{
"type": "ProvideDiscount",
"rewardDetails": {
"discountValue": "10",
"discountType": "PercentageOff"
},
"targetAudience": {
"audienceType": "AllLoyaltyMembers"
}
}
]
}
]
}