Evaluate promotions

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)

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-site-context

string

required

The x-site-context header is a JSON object that contains information about the source you wish to pull from. The mandatory account is the 24 character identifier found in Copilot. The channel (Sales channel ID), stage (environment name), and date attributes can be used to further narrow the scope of your data source.

Body

application/json

Prices conditions

items

object[]

required

List of item information objects

Show child attributes

items.priceList

string

required

Price list ID or name

items.quantity

number

required

Quantity of the item ordered

items.channel

integer[]

List of channel IDs from where the request is coming

items.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.

items.hierarchy

array

Item hierarchy to evaluate promotions

items.itemId

integer

ID of the item. Either SKU or ItemId is mandatory. If both provided, SKU overrides itemId.

items.lineItemId

integer

Item sequence number

items.price

object

Price object. This will override the promotion evaluation response prices.

Show child attributes

items.price.base

number

Minimum fixed price of a single unit of the item

items.price.sale

number

Price at which the product is offered for sale

items.priceParams

object

Price parameters for calculating price

Show child attributes

items.priceParams.options

object

Pricing options for calculation

Show child attributes

items.priceParams.options.{key}

object

Pricing options for calculation. If an add-on (blindmotor in this example) is set to true, price of the additional item will be calculated based on the price that was set earlier.

items.productAttributes

object

Show child attributes

items.productAttributes.{key}

Product attributes

items.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.

items.shippingPrice

number

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.

items.sku

string

SKU of the item. Either SKU or ItemId is mandatory. If both provided, SKU overrides itemId.

date

string

Date for which the promotions to be evaluated

isLoggedIn

boolean

true: user logged in<br /> false: user is not logged in

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

object[]

Shipping cost for the entire cart. You can use this shipping array if you want to add shipping cost for the entire cart.<br /> If you want to add shipping cost for individual items, you can provide details for each item using items.shippingMethodId and items.shippingPrice fields.

Show child attributes

shipping.shippingMethodId

string

Shipping method ID to check if promotion is applied to it

shipping.shippingPrice

number

Shipping price for the entire cart

traceId

string

Trace ID, used to trace logs

userId

string

User ID

userProfile

object[]

Segment the user belongs to

Show child attributes

userProfile.{key}

string[]

Response

200 - application/json

appliedDiscounts

object[]

Show child attributes

appliedDiscounts.amount

number

Discount amount

appliedDiscounts.promoCode

string

Coupon code

appliedDiscounts.promoId

string

Promotion ID

appliedDiscounts.promoTitle

string

Promotion title

appliedDiscounts.type

string

Promotion type

errors

string[]

items

object[]

Show child attributes

items.attributes

object

Product attributes

Show child attributes

items.attributes.{key}

object

Product attributes

items.discount

object[]

Show child attributes

items.discount.amount

number

Discount amount

items.discount.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.

items.discount.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.

items.discount.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.

items.discount.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.

items.discount.promoCode

string

Coupon code

items.discount.promoId

string

Promotion ID

items.discount.promoTitle

string

Promotion title

items.discount.proratedAmount

number

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.

items.discount.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.

items.discount.quantity

integer

Number of items

items.discount.stackingType

enum<string>

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.

Available options:

STACKABLE,

EXCLUSIVE,

TYPE_EXCLUSIVE,

UNIVERSAL

items.discount.type

string

Promotion type

items.discount.unit

string

Unit of discount measurement

items.discount.value

number

Discount value

items.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.

items.itemId

integer

Item ID

items.lineItemId

integer

Sequence number of the item

items.price

object

Show child attributes

items.price.base

number

Base price. It is the minimum fixed price of the item

items.price.currency

string

Currency code

items.price.finalPrice

number

Final Price of the item, does not include discounts

items.price.kind

string

Price kind name

items.price.sale

number

Price at which the item is offered for sale

items.price.totalPrice

number

Total price after all the discounts

items.priceAttributes

object

Returned if configured earlier

Show child attributes

items.priceAttributes.clearance

number

Selling price

items.priceAttributes.cost

number

Cost price

items.priceAttributes.floor

number

It is the lowest price at which a product can be sold

items.priceList

string

Price list ID or name, depending on configuration

items.quantity

number

Number of items

items.shippingDiscount

number

Shipping discount if any

items.shippingMethodId

string

Shipping method ID used to check if promotion is applicable to the shipping method

items.shippingPrice

number

Shipping price

items.sku

string

Item SKU

notAppliedCoupons

object[]

Show child attributes

notAppliedCoupons.message

string

Reason why coupon not applied

notAppliedCoupons.promoCode

string

Coupon code

notAppliedCoupons.promoId

string

Promotion ID

shipping

object[]

Show child attributes

shipping.shippingDiscount

number

Shipping discount

shipping.shippingMethodId

string

Shipping Method ID

shipping.shippingPrice

number

Shipping price

success

boolean

Indicates if promotion is successfully evaluated

suggestedProducts

object[]

Show child attributes

suggestedProducts.amount

number

Amount for discount

suggestedProducts.discountType

enum<string>

Type of discount

Available options:

%OFF,

AMOUNT_OFF,

FIXED_PRICE

suggestedProducts.eligiblePriceLists

string[]

Price list IDs promotion applies to. If empty, promotion applies to all price lists.

suggestedProducts.free

boolean

true when a free item is provided as a promotion

suggestedProducts.itemId

string

Free Item's ID

suggestedProducts.promotionId

string

Promotion ID

suggestedProducts.promotionTitle

string

Promotion title

suggestedProducts.quantity

integer

Number of free items promotion gives

suggestedProducts.sku

string

Free SKU