Eligible Promotions API

Use the Eligible Promotions API to provide customers with a list of promotions that are eligible for customer carts. The API can get the list of eligible promotions for contacts, accounts, and loyalty program members.

Required Editions

Available in: Lightning Experience

Available in: Enterprise, Unlimited, and Developer Editions with Real-Time Offer Management

Provide your customers a list of promotions that are eligible for their cart. The API takes a customer’s cart details as the request and provides the details of the eligible active promotions for the cart as the response. When looking for eligible promotions for an item, the API scans 5 levels of the product’s category hierarchy.

If a cart contains a product that doesn't exist in the Salesforce catalog, the API ignores the unsynced products while evaluating line-level and cross line level promotions and shows eligible promotions for the cart.

If an org has multiple Global Promotion Management type rule libraries, system integrators must specify which rule library that the API executes. They also must confirm that the API’s request contains values that the rule library’s context definition requires to evaluate carts.

Important When the API doesn’t find the value for a custom attribute or a product attribute in the request, the value is assumed to be absent in the cart.

The API response provides these promotion details.

Promotion’s primary details such as start and end dates
Promotion’s custom field values
Promotion’s limits
Promotion’s rules that are eligible for the customer’s cart
Promotion's custom field values that are mapped in the promotion context definition.

To provide customers their eligible promotions in real time, integrate the Eligible Promotions API with external systems that manage customer carts. See Eligible Promotions.

Tip While integrating the API with external systems such as shopping sites, point-of-sale systems (POS systems), and global distribution systems (GDS), you use either record ID or names to identify key attributes of the cart. For example, to identify the customer to whom the cart belongs, either specify the ID of the customer’s contact record or the last name and the email of the contact. To identify loyalty program members to whom the cart belongs, specify either the member’s Loyalty Program Member record ID or their membership number. To identify products or categories from which products are added to the customer’s cart, specify either the product ID or product name, or the category ID or name.

After a promotion’s usage meets the promotion’s limit for a particular cart, the Eligible Promotions API doesn’t provide the reward in the API output for any customer. After a customer’s usage of a reward meets the promotion’s customer-level limit, the Eligible Promotions API no longer offers the reward to the customer.

Example The admin and the marketing manager at Cloud Kicks have collaborated to create a custom context definition for a promotion that targets the Sneakerheads segment who purchase premium sneaker shields with a cart value of US$75.

Here’s how the Eligible Promotion API’s request looks like when the API is executed from Cloud Kicks’ online shopping site.

{
   "cart":{
      "Accessory":[
         {
            "activityStartDate":"2023-06-14T12:45:19Z",
            "contactId":"003xx000004WjzAAAS",
            "transactionAmount":85,
            "currencyISOCode":"INR",
            "cartLineDetails":[
               {
                  "CartLineProductCategory":"Sneaker Shields",
                  "cartLineProductCatalogId:"0ZSSB0000002d8X4AQ"",
                  "AttributeKey:"Premium"
               }
            ]
         }
      ]
   }
}