--- schema_version: "1" id: 0d5858ef78ba884a51f7f3b909724322063950ea5593563bdc21b0df250951d8 title: Eligible Promotions API collection: admin version: current locale: en-us portal_url: https://docs.salesforce.com/admin/current/en-us/mktg/264-0-0/global_promotions_management_run_pricing_eligible_api.md canonical_url: https://help.salesforce.com/s/articleView?id=mktg.global_promotions_management_run_pricing_eligible_api.htm&release=264.0.0&type=5 source_site: help.salesforce.com content_type: documentation content_hash: 772fe813b1f3175ab25cea94a5eddd9cb0874bf4bcc21b341217d1e563c769a4 description: Use the Eligible Promotions API to provide customers with a list of pricing promotions that are eligible for customer carts. The API can get the list of eligible promotions for contacts, accounts, and loyalty program members. products: - Marketing release: "264" --- # Eligible Promotions API Use the Eligible Promotions API to provide customers with a list of pricing 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](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 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. ![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 The API response contains only pricing promotions and doesn't contain loyalty promotions. To provide customers their eligible promotions in real time, integrate the Eligible Promotions API with external systems that manage customer carts. See [Eligible Promotions](https://developer.salesforce.com/docs/atlas.en-us.loyalty.meta/loyalty/connect_resources_eligible_promotions.htm). ![Tip](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_tip.png) 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](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 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" } ] } ] } }` ## Eligible Promotions API for Promotions with Coupons When coupons are added to a promotion, the Eligible Promotions API takes a customer’s cart details as the request and responds with the details of the active coupons for the promotions eligible for the customer’s cart. The customer can use the coupon of the promotion that they want to apply to their cart. For eligible promotions that include a coupon, the API’s response includes these coupon details. - Coupon code - Start and end dates - Status The API only returns promotions that have at least one active and valid coupon for the customer's activity date. Though a promotion can consist of multiple coupons, the API doesn’t show the coupon code in these scenarios. - If there are multiple active coupons eligible for the activity date and the cart or cart line item doesn’t include a coupon code that matches one of the promotion’s active coupons - If no coupon is active for the activity date - If the eligible active coupon has reached its usage limit ![Tip](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_tip.png) Tip To confirm whether a manually entered coupon code is valid for a cart before you apply the coupon—use the Coupon Validation API. See [Coupon Validation API](https://help.salesforce.com/s/articleView?id=mktg.global_promotions_management_run_pricing_coupon_validation_api.htm&release=264.0.0&type=5 "Use the Coupon Validation API to verify manually entered coupon codes before applying discounts. Validating coupons upfront—rather than waiting until checkout—gives customers immediate feedback on whether their code works. The API checks if the coupon exists, is active, hasn't reached redemption limits, and if the cart is eligible for the promotion.").