Loading
Prepare for Email to Become the Default Login ExperienceRead More
The online Trailblazer Community becomes read-only Oct 30, 2026Read More
Important Advisory: iOS Update Impacting CG Mobile ApplicationRead More
Learn About Real-Time Offer Management
Design Promotions Programmatically

You are here:

  1. Salesforce Help
  2. Docs
  3. Real-Time Offer Management

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.

Important
Important You can't use Promotion Creation API to create promotions that use the Engagement Trail promotion template.

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.

You can turn on personalized values for promotion rules, and set purchaseCriteria to a static or a personalized value. See Turn On Global Promotions Management for prerequisites and setup steps. For a personalized value, also provide personalizationTarget with the customer's target, such as Easy, Moderate, or Hard.

Custom Promotions template and Decision Table-Based Promotion template don't support personalized values.

The API can also retrieve the readable summary that's shown when a promotion is reviewed in the Quick Promotion Wizard by its record ID. The promotion summary includes the promotion's primary details, promotion's eligibility criteria, and The promotion's rules, including what customers must do, what they receive, and each rule's priority.

Note
Note If a promotion is incomplete or in draft, the API returns the summary information that's available. Summary properties can be empty when the corresponding promotion information hasn't been configured.
Example
Example The marketing team at Cloud Kicks is planning their summer marketing campaign for the 'Cloud Kicks Loyalty' loyalty program. To boost sales and reward their loyal customers, they want to create a promotion called Summer Sale. This promotion will run during the month of June and will offer a 10% discount on purchases over $50. The promotion is specifically for the Summer Sneakers product category on their app and is targeted towards their Loyal Customers segment. To ensure the promotion is effective, they want to limit its usage to 1000 times overall and 5 times per customer.

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"
          }
        }
      ]
    }
  ]
}
 
Loading
Salesforce Help | Article