--- title: "Evaluate promotions" method: POST path: "/v1/promo/evaluate-promotions" tags: ["Dynamic Pricing Engine"] --- # Evaluate promotions `POST /v1/promo/evaluate-promotions` ## Request - Base URL: `https://live.copilot.fabric.inc` - URL: `https://live.copilot.fabric.inc/v1/promo/evaluate-promotions` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Evaluates a cart's promotions, discount coupons and implicit promotions, either by specified itemId or by SKU (based on the customer specific configuration set in the backend) ## Headers - `x-site-context` string, required ## Request body - PromotionEvaluationRequest: Prices conditions - `traceId` string: Trace ID, used to trace logs - `isLoggedIn` boolean: true: user logged in
false: user is not logged in - `userId` string: User ID - `promoCodes` string[]: A list of coupon codes that are applicable only for coupons. For coupons, the response includes promo codes associated with the coupon. For promotions, the response includes an empty array. - `shipping` PromotionRequestShipping[]: Shipping cost for the entire cart. You can use this `shipping` array if you want to add shipping cost for the entire cart.
If you want to add shipping cost for individual items, you can provide details for each item using `items.shippingMethodId` and `items.shippingPrice` fields. - `shippingMethodId` string: Shipping method ID to check if promotion is applied to it - `shippingPrice` number, double: Shipping price for the entire cart - `items` PromotionRequestItem[], required: List of item information objects - `lineItemId` integer: Item sequence number - `priceList` string, required: Price list ID or name - `sku` string: SKU of the item. Either SKU or ItemId is mandatory. If both provided, SKU overrides itemId. - `itemId` integer: ID of the item. Either SKU or ItemId is mandatory. If both provided, SKU overrides itemId. - `quantity` number, double, required: Quantity of the item ordered - `group` string[]: List of Group IDs. Groups the promotions belongs to. When a group of promotions is subject to non-stackable, it will be compared to other promotion groups and the highest discount providing group will be applied as promotion. - `hierarchy` array[]: Item hierarchy to evaluate promotions - string[] - `productAttributes` object - `priceParams` PricePromoParam: Price parameters for calculating price - `options` object: Pricing options for calculation - `price` ItemPriceOverride: Price object. This will override the promotion evaluation response prices. - `sale` number, double: Price at which the product is offered for sale - `base` number, double: Minimum fixed price of a single unit of the item - `channel` integer[]: List of channel IDs from where the request is coming - `shippingMethodId` string: Shipping Method ID to check if promotion is applicable to the shipping of the item. You can use this field if you want to add shipping cost for individual items. If you want to add shipping cost for the entire cart, use `shipping` array field. - `shippingPrice` number, double: Shipping cost for the individual item. You can use this field if you want to add shipping cost for individual items. If you want to add shipping cost for the entire cart, use `shipping` array field. - `date` string, date-time: Date for which the promotions to be evaluated - `userProfile` object[]: Segment the user belongs to ## Response `200` Successfully evaluated the promotions - PromotionEvaluationResponse[] - `items` PromotionResponseItem[] - `lineItemId` integer: Sequence number of the item - `sku` string: Item SKU - `itemId` integer: Item ID - `priceList` string: Price list ID or name, depending on configuration - `group` string[]: Group or category the promotion belongs to. When a group of promotions is subject to non-stackable, it will be compared to other promotion groups and the highest discount providing group will be applied as promotion. - `quantity` number, double: Number of items - `price` ItemPrice - `currency` string: Currency code - `base` number, double: Base price. It is the minimum fixed price of the item - `kind` string: Price kind name - `totalPrice` number, double: Total price after all the discounts - `finalPrice` number, double: Final Price of the item, does not include discounts - `sale` number, double: Price at which the item is offered for sale - `priceAttributes` ItemPriceAttributes: Returned if configured earlier - `cost` number, double: Cost price - `floor` number, double: It is the lowest price at which a product can be sold - `clearance` number, double: Selling price - `discount` OfferDiscount[] - `quantity` integer: Number of items - `amount` number, double: Discount amount - `unit` string: Unit of discount measurement - `value` number, double: Discount value - `promoId` string: Promotion ID - `promoCode` string: Coupon code - `promoTitle` string: Promotion title - `type` string: Promotion type - `application` integer: It is used specifically for BuyGet type that applies when you Buy something and Get discount of some amount or percentage or free items. This field indicates how many times this BuyGet promotion is applied. - `isStackable` boolean: A flag indicating whether the promotion can be stacked. Set it to `true` if multiple promotions can be applied together and `false` if the promotions cannot be combined. - `isAlwaysApplied` boolean: A flag indicating whether the promotion is always applied. Set it to `true` if the promotion is always applied, even on non-stackable promotions and `false` to apply promotions based on configured conditions. - `level` integer: The promotion execution order. Promotion types are assigned default execution orders. Initial evaluation begins with level 1 promotions. The result of level 1 is used as the base price for level 2. Similarly, the result of level 2 becomes the base price for level 3, and so on. - `stackingType` 'STACKABLE' | 'EXCLUSIVE' | 'TYPE_EXCLUSIVE' | 'UNIVERSAL': Defines the rules for how a promotion can be combined with other promotions. This field determines whether a specific promotion can be applied in conjunction with other active promotions during a transaction or if it must be used exclusively. Possible values: - `STACKABLE`: This promotion can be combined with other stackable promotions, allowing multiple discounts to be applied together. The order in which stackable promotions are applied is determined by the `level` field, with promotions having a higher priority (lower numeric value) being applied before those with a lower priority. - `EXCLUSIVE`: This promotion cannot be combined with any other promotions. The `level` field is used to determine which exclusive promotion will be evaluated and applied first. Once an exclusive promotion is applied, no other promotions can be used in the same transaction. - `TYPE_EXCLUSIVE`: This promotion cannot be combined with other promotions of the same type. The `level` field is used to determine which promotion within the same type will be evaluated and applied first. - `UNIVERSAL`: This promotion can be combined with any other promotions without restrictions. Universal promotions will be evaluated last. - `proratedAmount` number, double: The BuyGet promotions distribute the discount across specified parameters. For example, when buying A results in a discount on B, the discount amount on B is prorated across both A and B. The distributed amount is reflected in `proratedAmount`, while the quantity is captured in `proratedQuantity`. - `proratedQuantity` integer: The `proratedQuantity` is used in conjunction with `proratedAmount` to determine the discount portion allocated to the respective units of BuyGet promotions. This is applicable in partial return scenarios. - `attributes` object: Product attributes - `shippingPrice` number, double: Shipping price - `shippingMethodId` string: Shipping method ID used to check if promotion is applicable to the shipping method - `shippingDiscount` number, double: Shipping discount if any - `errors` string[] - `shipping` PromotionResponseShipping[] - `shippingMethodId` string: Shipping Method ID - `shippingPrice` number, double: Shipping price - `shippingDiscount` number, double: Shipping discount - `appliedDiscounts` AppliedDiscount[] - `promoId` string: Promotion ID - `promoCode` string: Coupon code - `promoTitle` string: Promotion title - `type` string: Promotion type - `amount` number, double: Discount amount - `suggestedProducts` SuggestedProducts[] - `promotionId` string: Promotion ID - `promotionTitle` string: Promotion title - `itemId` string: Free Item's ID - `sku` string: Free SKU - `eligiblePriceLists` string[]: Price list IDs promotion applies to. If empty, promotion applies to all price lists. - `quantity` integer: Number of free items promotion gives - `free` boolean: true when a free item is provided as a promotion - `discountType` '%OFF' | 'AMOUNT_OFF' | 'FIXED_PRICE': Type of discount - `amount` number, double: Amount for discount - `notAppliedCoupons` CouponError[] - `promoCode` string: Coupon code - `promoId` string: Promotion ID - `message` string: Reason why coupon not applied - `promotionMessages` object[]: The promotion message that is displayed to the customer. - `promoId` string: Promotion ID - `title` string: The title of the promotion message, summarizing the offer or discount type. - `message` string: A promotional message providing details about the offer, including eligibility, duration, and conditions. - `pages` string[]: The web pages where the message is displayed, whether the product display page (PDP), product list page (PLP), the customer's cart, or the checkout page. - `locales` string[]: The geographic regions where the promotion message is displayed, determined by the user's IP address. Locales define language and country-specific settings for promotions. - `type` 'DISCOUNT' | 'PROXIMITY' | 'POTENTIAL_DISCOUNT': Specifies the promotion message type. - `DISCOUNT`: The discount has been applied. - `PROXIMITY`: The product or cart is close to meeting discount conditions. - `POTENTIAL_DISCOUNT`: The product could qualify for a discount but has not yet. - `threshold` integer: Indicates a quantity or amount that is close to meeting the discount requirement. If the user reaches this value, a promotion message is displayed. This field is only valid for PROXIMITY messages. - `success` boolean: Indicates if promotion is successfully evaluated ## Other responses - `400`: Bad Request - `403`: Forbidden - `404`: Not Found - `500`: Internal Server Error --- [API](https://skmtc.dev/fabric/apis/offers-v2.md) - [All operations](https://skmtc.dev/fabric/apis/offers-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/fabric/apis/offers-v2/revisions/da2bd742b9bc?raw)