--- schema_version: "1" id: 4295722fdd6dd9e21b0303e79b3b2fe9d1739fbcac06e8ee08085d0ed65010d6 title: Promotion Events Webhook collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/promotion-events-webhook.md canonical_url: https://developer.salesforce.com/docs/commerce/retail-cloud/references/promotion-events-webhook source_site: developer.salesforce.com content_type: documentation content_hash: 0d0b3b366591fd5fb267f66eec372e02024013b994d00ddf993eaf58aad2b7ad products: - Point of Sale for Developers - Salesforce APIs --- Promotion Events Webhook # Promotion Events Webhook [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/promotion-events-webhook/promotion-events-webhook-oas-public.yaml) Sample API that demonstrates how to implement a webhook endpoint by the merchant's system. This endpoint is then to be configured in the Point of Sale (POS) CMS system, so that the POS platform can use it to send promotion lifecycle events' data (CREATE, UPDATE, and DELETE). The event type is indicated by the `promotionEventType` field in the payload. **Version:** 2.3.4 ## Tags ### Promotion Events Webhook [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/promotion-events-webhook/promotion-events-webhook-oas-public.yaml) Sample API that demonstrates how to implement a webhook endpoint by the merchant's system. This endpoint is then to be configured in the Point of Sale (POS) CMS system, so that the POS platform can use it to send promotion lifecycle events' data (CREATE, UPDATE, and DELETE). The event type is indicated by the `promotionEventType` field in the payload. ## Operations ### POST Receive promotion lifecycle event details `POST /merchant/spi/sample/endpoint/sa/customer/promotion/promotionExport` Operation ID: `promotionExportWebhook`. Tags: Promotion Events Webhook. Webhook to export promotion events (CREATE, UPDATE, DELETE) to the merchant's system. The payload contains the promotion details as a `PromotionWebhookPayload`. For all the events the `promotions` list is populated. The `promotionEventType` field indicates which lifecycle event occurred. Merchants should implement this endpoint per this specification and then configure it in CMS under **CMS** > **Store Management** > **Integration** > **Custom API Connectors** > **Create**. Make sure to create the endpoint in CMS with the following details 1. Under **API Config** * **API Key:** This should be `PROMOTION_EXPORT` * **API Endpoint:** Provide the external endpoint URL to receive the promotion payload 2. Under **JSON Config** * **Integration Type:** `HTTP_POST` * **JSON Headers:** Provide the headers for the API. Headers can include Content-Type, Authorization attributes like clientId/password eg. {"Content-Type":"application/json"}. #### Request body Media type: `application/json`. Schema: `PromotionWebhookPayload`. #### Responses * **default** default response. Media type: `application/json`. Schema: `SpiPSResponse`. ## Schemas ### PromotionWebhookPayload Payload delivered to external systems via the promotion webhook for CREATE, UPDATE, and DELETE events. * `promotionEventType` (_string_, required) Type of promotion lifecycle event: CREATE, UPDATE, or DELETE. Allowed values: `CREATE`, `UPDATE`, `DELETE`. * `promotions` (_array of SpiPromotion_, required) List of promotions included in this event. * `user` (_string_, nullable) CMS user ID who triggered this event (create, update, or delete). * `eventTimestamp` (_integer (int64)_, required) Unix epoch timestamp (milliseconds) indicating when this event was generated. ### SpiPSResponse * `errorMessage` (_string_, nullable) Error message shown to the user. Example: `Invalid request. Please check the request and try again.`. * `errorCode` (_string_, nullable) Error code shown to the user. Example: `INTERNAL_ERROR`. * `error` (_boolean_) ### SpiPromotion Promotion attributes included in a promotion webhook event. Represents a curated view of the Promotion for external consumers. * `promotionId` (_string_, required) Unique identifier assigned to the promotion. * `name` (_string_, required) Internal name used to identify the promotion. * `title` (_string_, required) Display title shown on the presentation layer. * `description` (_string_, required) Detailed description including disclaimer and other information shown on the presentation layer. * `inStorePromoCode` (_string_) Promo code entered by the customer for in-store (STORE channel) sales. * `appPromoCode` (_string_) Promo code entered by the customer for in-app (APP channel) sales. * `onlinePromoCode` (_string_) Promo code entered by the customer for online (WEB channel) sales. * `outletPromoCode` (_string_) Promo code entered by the customer for outlet store (OUTLET channel) sales. * `startTimeStamp` (_integer (int64)_, required) Promotion start time in Unix epoch milliseconds. * `endTimeStamp` (_integer (int64)_, required) Promotion end time in Unix epoch milliseconds. * `combinationTypes` (_array of string_) List of promotion types this promotion can be combined with, for example, ORDER\_PERCENT\_OFF or FREE\_SHIPPING. * `channel` (_array of string_, required) Sales channels this promotion applies to (ALL, WEB, APP, STORE, OUTLET). Not applicable for auto promotions. Each item: Different Channel Types supported by the Promotion Engine. Items: Allowed values: `ALL`, `WEB`, `APP`, `STORE`, `OUTLET`. * `priorityOrder` (_integer (int32)_) Priority order for promotion application. Lower number means higher priority. * `active` (_boolean_, required) Whether the promotion is active. Only active promotions are evaluated by the promo engine. * `auto` (_boolean_, required) Whether the promotion is applied automatically without requiring a promo code. * `redemptionLimit` (_number (double)_) Maximum number of times this promotion can be redeemed. * `promotionType` (_string_, required) Different promotion Types supported by the Promotion Engine. Allowed values: `ORDER_PERCENT_OFF`, `ORDER_AMOUNT_OFF`, `FREE_SHIPPING`, `BXGY`, `FREE_SAMPLES`, `X_FOR_Y`, `PRODUCT_FIXED_AMOUNT`, `FREE_SHIPPING_V2`. * `redeems` (_number (double)_) Current number of times this promotion has been redeemed. * `percentOff` (_number (double)_) Percentage discount applied by this promotion. * `amountOff` (_number_) Fixed amount discounted by this promotion. * `freeShippingMethods` (_array of string_) List of shipping method codes eligible for free shipping under this promotion. * `hasSingleUsePromoCodes` (_boolean_) Whether this promotion uses single-use (one-time) promo codes. * `imageUrl` (_string_) URL of the image associated with this promotion. * `freeSamples` (_array of CombinationGroup_) Free sample products awarded when this promotion is applied. * `merchantPromotionId` (_string_) Merchant-defined identifier for this promotion. * `amount` (_number_) Fixed promotional amount applied to qualifying items. * `qualifyingProducts` (_array of CombinationGroup_) Products that must be purchased to qualify for this promotion (used in BXGY and combination promotions). * `discountedProducts` (_array of CombinationGroup_) Products that receive the discount when the qualifying condition is met. * `discountedGroupProration` (_boolean_) Whether the discount is prorated across items in the discounted product group. * `productRules` (_array of PromotionRule_) Rules applied to specific products to determine promotion eligibility. * `customerRules` (_array of PromotionRule_) Rules applied to customer attributes to determine promotion eligibility. * `locationRules` (_array of PromotionRule_) Rules applied to store location attributes to determine promotion eligibility. * `orderRules` (_array of PromotionRule_) Rules applied to order-level attributes to determine promotion eligibility. * `bxgyDiscountType` (_string_) Buy X Get Y Discount Types. Allowed values: `PERCENT_OFF`, `AMOUNT_OFF`, `FIXED_PRICE`. ### CombinationGroup Products that receive the discount when the qualifying condition is met. * `quantity` (_integer (int32)_) * `quantityOperator` (_string_) Allowed values: `EQL`, `GTE`. * `productRules` (_array of PromotionRule_) ### PromotionRule Promotion rule provides the filtering criteria to determine if the order is eligible for promotion. * `promotionRuleId` (_string_) * `promotionId` (_string_) * `operator` (_string_, nullable) Operation to be performed for the rule depending on the value types. Allowed values: `DOES_NOT_CONTAIN`, `CONTAINS`, `GTE`, `LTE`, `EXISTS`, `NOT_EXISTS`. * `value` (_array of string_, nullable) Values are based on the value Types. They contain a list and for single value attributes use a list of size 1. Unique items. * `valueType` (_string_, nullable) Value Type provides the type of value.