---
schema_version: "1"
id: ecf7be7ac94b402518c5ebf033a6b2cf0db0d663454baca0c5708d9c091c01e1
title: Design Promotions Programmatically
collection: admin
version: current
locale: en-us
portal_url: https://docs.salesforce.com/admin/current/en-us/mktg/264-0-0/global_promotions_management_create_promotions_programmatically.md
canonical_url: https://help.salesforce.com/s/articleView?id=mktg.global_promotions_management_create_promotions_programmatically.htm&release=264.0.0&type=5
source_site: help.salesforce.com
content_type: documentation
content_hash: b8eb8c26ead0cfe6cb77d3cb2bff292a08e6da82fd1540b45f59ff59dc56ac3a
description: 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.
products:
  - Marketing
release: "264"
---
# 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

<table class="slds-table slds-table_bordered slds-max-medium-table_stacked slds-m-bottom_small edition"><colgroup><col></colgroup><tbody><tr class=""><td class="slds-cell-wrap" style="vertical-align:top;">Available in: Lightning Experience</td></tr><tr class=""><td class="slds-cell-wrap" style="vertical-align:top;">Available in: <strong>Enterprise</strong>,&nbsp;<strong>Unlimited</strong>, and&nbsp;<strong>Developer</strong>&nbsp;Editions with Real-Time Offer Management</td></tr></tbody></table>

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](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-mktg-real_time_offer_management-264-0-0-production-enus/9bd7649d-776f-43e6-b210-f781a48bbc79/images/icon_important.png)

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](https://help.salesforce.com/s/articleView?id=mktg.global_promotions_management_design_promotion_wizard.htm&language=en_US).

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](https://help.salesforce.com/s/articleView?id=mktg.global_promotions_management_setup_enable.htm&type=5&language=en_US) 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](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-mktg-real_time_offer_management-264-0-0-production-enus/9bd7649d-776f-43e6-b210-f781a48bbc79/images/icon_note.png)

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](https://sf-zdocs-cdn-prod.zoominsoftware.com/tdta-mktg-real_time_offer_management-264-0-0-production-enus/9bd7649d-776f-43e6-b210-f781a48bbc79/images/icon_example.png)

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"
          }
        }
      ]
    }
  ]
}
```