Evaluate cart promotions

Authorizations

Authorization

string

header

required

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

Headers

x-fabric-tenant-id

string

required

A header used by fabric to identify the tenant making the request. You must include tenant id in the authentication header for an API request to access any of fabric’s endpoints. You can retrieve the tenant id , which is also called account id, from Copilot. This header is required.

Required string length: 24

x-fabric-date

string

The Date and time, in ISO 8601 format, for which the evaluation should be done. The prices and promotions that are active on this date will be considered for evaluation.

Example:

"2022-09-06T14:07:17.000Z"

x-fabric-request-id

string

A unique request ID.

Example:

"263e731c-45c8-11ed-b878-0242ac120002"

x-fabric-channel-id

string

x-fabric-channel-id identifies the sales channel where the API request is being made; primarily for multichannel use cases. The channel ids are 12 corresponding to US and 13 corresponding to Canada. The default channel id is 12. This field is required.

Example:

"12"

Body

application/json

A sample cart evaluation request.

cartItems

object[]

required

The details of items in the cart.

Show child attributes

cartItems.itemId

integer<int32>

required

Item ID obtained from Product Catalog.

Example:

1730902008

cartItems.quantity

integer<int32>

required

Line item quantity within the cart

Example:

15

cartItems.position

integer<int32>

Line item position (starts at 1)

Required range: x >= 1

Example:

1

cartItems.sku

string

Line item SKU

Example:

"16B2GS8LD5FDS"

cartItems.productAttributes

object[] | null

Line item product attributes

Show child attributes

cartItems.productAttributes.name

string

required

Attribute name

Example:

"gift wrapping (small)"

cartItems.productAttributes.value

string | null

required

Attribute value

Example:

"true"

cartItems.productAttributes.attributeId

string

Attribute ID

Example:

"60c2a358eb2ec30008ae70a1"

cartItems.productAttributes.description

string | null

Attribute description

Example:

"Gift wrapping for a small package"

cartItems.productAttributes.mapping

string | null

Attribute mapping

Example:

"ITEM"

cartItems.productAttributes.type

string | null

Attribute type

Example:

"GIFT"

cartItems.productAttributes.price

number<double> | null

Attribute price

Example:

10

cartItems.productAttributes.level

string | null

Attribute level

Example:

"order"

cartItems.priceListId

integer<int32> | null

The price list ID associated with the item generated using the create price list endpoint.

Example:

108674

cartItems.price

object

Individual line item price

Show child attributes

cartItems.price.sale

number<double> | null

Sale price of the product.

Example:

1000.15

cartItems.price.cost

number<double>

Cost of goods sold, from either producing or purchasing from other vendors.

Example:

900.15

cartItems.price.base

number<double>

The base price of a single item before any discounts.

Example:

2000.15

cartItems.price.unitPriceWithoutDiscounts

number<double> | null

Price of a single item without discount. This price is either the base or sale price. The type used is noted in the type property.

Example:

2000.15

cartItems.price.lineTotalWithoutDiscounts

number<double> | null

Total price of all items without calculating discounts. This is the unitPriceWithoutDiscounts multiplied by the quantity.

Example:

5000.15

cartItems.price.lineTotalWithDiscounts

number<double> | null

Total price of all items after all discounts. This is the unitPriceWithoutDiscounts multiplied by the quantity, less the promotion discounts.

Example:

5000.15

cartItems.price.type

string | null

Price type

Example:

"BASE"

cartItems.price.currency

string

Currency string value

Example:

"USD"

Example:

{
  "sale": 1000.15,
  "cost": 900.15,
  "base": 2000.15,
  "unitPriceWithoutDiscounts": 2000.15,
  "lineTotalWithoutDiscounts": 2000.15,
  "lineTotalWithDiscounts": 2000.15,
  "type": "BASE"
}

cartItems.groups

string[] | null

List of group IDs for groups or category the line items belongs to

ID of group or category to which line item belongs

cartItems.attributes

object

Line item attributes passed by caller

Example:

{ "productFamily": "Laptop computers" }

cartItems.shippingDetails

object

Shipping details

Show child attributes

cartItems.shippingDetails.shippingCost

number<double>

Shipping cost

Example:

150.25

cartItems.shippingDetails.shippingMethodId

string

Shipping method ID

Example:

"dfsae-2d32113-32lpdd"

cartItems.shippingDetails.shippingDiscount

number<double>

Discount amount

Example:

150.25

cartItems.shippingDetails.shippingMethodName

string | null

Shipping method name

Example:

"Express Delivery"

cartItems.productCollections

string[]

The collections associated with given item.

A 24-character system-generated collection ID.

customer

object

Customer details

Show child attributes

customer.id

string

Unique identifier for the customer

Example:

"5e2cfb9b45570b000864c4b5"

customer.segments

object[]

A list of segments the customer belongs to.

Show child attributes

customer.segments.name

string

The name of the segment the customer belongs to.

Example:

"category"

customer.segments.value

string[]

The values of the segment associated with the customer.

Segment item

Example:

[
  {
    "name": "category",
    "value": ["GOLD", "YELLOW"]
  },
  { "name": "ageGroup", "value": ["elderly"] }
]

couponCodes

string[]

Promotion codes to be applied

Promotion code

locale

string

The language code, which is a combination of language in ISO 639 format and country in ISO 3166 format. The default value is en-US.

Example:

"en-US"

Response

The response of the evaluation request of the cart promotion.

cartItems

object[]

The list of items in the cart.

Show child attributes

cartItems.itemId

integer<int32>

required

Item ID obtained from Product Catalog.

Example:

1730902008

cartItems.quantity

integer<int32>

required

Line item quantity within the cart

Example:

15

cartItems.position

integer<int32>

Line item position (starts at 1)

Required range: x >= 1

Example:

1

cartItems.sku

string

Line item SKU

Example:

"16B2GS8LD5FDS"

cartItems.productAttributes

object[] | null

Line item product attributes

Show child attributes

cartItems.productAttributes.name

string

required

Attribute name

Example:

"gift wrapping (small)"

cartItems.productAttributes.value

string | null

required

Attribute value

Example:

"true"

cartItems.productAttributes.attributeId

string

Attribute ID

Example:

"60c2a358eb2ec30008ae70a1"

cartItems.productAttributes.description

string | null

Attribute description

Example:

"Gift wrapping for a small package"

cartItems.productAttributes.mapping

string | null

Attribute mapping

Example:

"ITEM"

cartItems.productAttributes.type

string | null

Attribute type

Example:

"GIFT"

cartItems.productAttributes.price

number<double> | null

Attribute price

Example:

10

cartItems.productAttributes.level

string | null

Attribute level

Example:

"order"

cartItems.priceListId

integer<int32> | null

The price list ID associated with the item generated using the create price list endpoint.

Example:

108674

cartItems.price

object

Individual line item price

Show child attributes

cartItems.price.sale

number<double> | null

Sale price of the product.

Example:

1000.15

cartItems.price.cost

number<double>

Cost of goods sold, from either producing or purchasing from other vendors.

Example:

900.15

cartItems.price.base

number<double>

The base price of a single item before any discounts.

Example:

2000.15

cartItems.price.unitPriceWithoutDiscounts

number<double> | null

Price of a single item without discount. This price is either the base or sale price. The type used is noted in the type property.

Example:

2000.15

cartItems.price.lineTotalWithoutDiscounts

number<double> | null

Total price of all items without calculating discounts. This is the unitPriceWithoutDiscounts multiplied by the quantity.

Example:

5000.15

cartItems.price.lineTotalWithDiscounts

number<double> | null

Total price of all items after all discounts. This is the unitPriceWithoutDiscounts multiplied by the quantity, less the promotion discounts.

Example:

5000.15

cartItems.price.type

string | null

Price type

Example:

"BASE"

cartItems.price.currency

string

Currency string value

Example:

"USD"

Example:

{
  "sale": 1000.15,
  "cost": 900.15,
  "base": 2000.15,
  "unitPriceWithoutDiscounts": 2000.15,
  "lineTotalWithoutDiscounts": 2000.15,
  "lineTotalWithDiscounts": 2000.15,
  "type": "BASE"
}

cartItems.groups

string[] | null

List of group IDs for groups or category the line items belongs to

ID of group or category to which line item belongs

cartItems.attributes

object

Line item attributes passed by caller

Example:

{ "productFamily": "Laptop computers" }

cartItems.shippingDetails

object

Shipping details

Show child attributes

cartItems.shippingDetails.shippingCost

number<double>

Shipping cost

Example:

150.25

cartItems.shippingDetails.shippingMethodId

string

Shipping method ID

Example:

"dfsae-2d32113-32lpdd"

cartItems.shippingDetails.shippingDiscount

number<double>

Discount amount

Example:

150.25

cartItems.shippingDetails.shippingMethodName

string | null

Shipping method name

Example:

"Express Delivery"

cartItems.discounts

object[]

A list of applicable discounts.

Show child attributes

cartItems.discounts.amount

number<double>

The actual discount amount applied to the price. For example, specifying 100.15 for a product with a base price of 2000.15 results in a discounted price of 1900.

Example:

100.15

cartItems.discounts.quantity

integer<int32>

The number of items eligible for the promotional discount.

Example:

5

cartItems.discounts.proratedAmount

number<double>

The discount amount distributed proportionally among all the selected items. The distribution is determined based on each item's price relative to the total price of all participating items. Typically, proratedAmount matches the amount. However, there might be variations, particularly in the context of Buy-Get promotions.

Example:

1000.15

cartItems.discounts.proratedQuantity

integer<int32>

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

Example:

5

cartItems.discounts.application

integer<int32> | null

An identifier for an instance of the Buy-Get promotion that can be applied repeatedly. For example, consider a promotion - Buy 1 shirt and get 1 pant at a 20% off. If a shopper buys three shirts, 20% discount is individually applied to each shirt-pant pair. Each such discounted pair is assigned a unique application number for tracking purposes.

Example:

1

cartItems.discounts.promotion

object

The promotion details.

Show child attributes

cartItems.discounts.promotion.id

string

A 24-character system-generated coupon ID generated using the create coupon endpoint.

Example:

"6197ec46e836ff000952c667"

cartItems.discounts.promotion.value

number<double>

The discount in percent or amount.

Example:

2000.15

cartItems.discounts.promotion.groupId

string | null

ID of the group or category this product belongs to

Example:

"61a6354d0d70e30009415f16"

cartItems.discounts.promotion.level

integer<int32> | null

The order in which the current promotion is executed.

Example:

1

cartItems.discounts.promotion.isStackable

boolean | null

A flag indicating whether the promotion is stackable. Set to true to combine the given promotion with other promotions. The discount of the current promotion is combined with other promotions, if applicable, to the item. Set to false if the promotion isn't stackable; the given promotion can't be combined with other promotions.

Example:

true

cartItems.discounts.promotion.isAlwaysApplied

boolean | null

A flag indicating whether the promotion is always applied regardless of any exclusive promotions on the same item. Set to true if the promotion is always applied and set to false if the promotion isn't applied on the item by default.

Example:

true

cartItems.discounts.promotion.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 can't 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 can't 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

Example:

"STACKABLE"

cartItems.discounts.promotion.name

string

The name of the promotion.

Example:

"20% off"

cartItems.discounts.promotion.type

string

The type of the promotion.

Example:

"COUPON"

cartItems.discounts.promotion.discountType

enum<string>

The type of discount.

Available options:

PERCENTAGE_OFF,

AMOUNT_OFF,

FIXED_PRICE

Example:

"PERCENTAGE_OFF"

Example:

{
  "id": "6197ec46e836ff000952c668",
  "value": 2000.15,
  "groupId": "61a6354d0d70e30009415f16",
  "level": 1,
  "isStackable": true,
  "isAlwaysApplied": true,
  "name": "20% OFF",
  "type": "Coupon",
  "discountType": "AMOUNT_OFF",
  "stackingType": "STACKABLE"
}

cartItems.priceAttributes

object

Price attributes

Show child attributes

cartItems.priceAttributes.cost

number<double>

Cost price

Example:

9.15

cartItems.priceAttributes.floor

number<double>

Lowest price at which a product is sold

Example:

10.15

cartItems.priceAttributes.clearance

number<double>

Selling price

Example:

10.15

Example:

{
  "floor": 1000.15,
  "cost": 900.15,
  "clearance": 2000.15
}

cartItems.productCollections

string[]

The collections associated with given item.

A 24-character system-generated collection ID.

errors

string[]

The error details.

The list of errors.

Example:

["Parameter doesn't exist"]

appliedDiscounts

object[]

The details of the discounts applied to the cart.

Show child attributes

appliedDiscounts.promotionId

string | null

A 24-character system-generated coupon ID generated using the create coupon endpoint.

Example:

"6197ec46e836ff000952c664"

appliedDiscounts.couponCode

string | null

Coupon code

Example:

"SUPERCOUPON20"

appliedDiscounts.promotionName

string | null

Promotion name

Example:

"20% off"

appliedDiscounts.type

string | null

Promotion type

Example:

"COUPON"

appliedDiscounts.amount

number<double> | null

Discount amount

Example:

10.15

Example:

[
  {
    "promotionId": "6197ec46e836ff000952c665",
    "promotionName": "Buy shoes get socks for free",
    "couponCode": "SUPERCOUPON20",
    "type": "COUPON",
    "amount": 105.15,
    "discountScope": "SKU",
    "discountType": "AMOUNT_OFF",
    "value": 10
  }
]

suggestedProducts

object[]

Suggested free products

Show child attributes

suggestedProducts.promotionId

string | null

A 24-character system-generated coupon ID generated using the create coupon endpoint.

Example:

"6197ec46e836ff000952c665"

suggestedProducts.promotionName

string | null

The promotion name

Example:

"Buy shoes get socks for free"

suggestedProducts.itemId

integer<int32> | null

The item ID of the free product

Example:

234343

suggestedProducts.itemIds

integer<int32>[]

The suggested item IDs from which shoppers can choose one or more items based on the configuration of BuyGet promotion. Even if an item ID is already in the cart, they appear in the list of potential item IDs. This ensures visibility and enables shoppers to make informed decisions during the checkout process.

The item ID of the free product.

suggestedProducts.sku

string

The Stock Keeping Unit (SKU) of the free product.

Example:

"SHOE1234"

suggestedProducts.skus

string[]

The suggested SKUs from which shoppers can choose one or more items based on the configuration of BuyGet promotion. Even if an SKU is already in the cart, they appear in the list of potential SKUs. This ensures visibility and enables shoppers to make informed decisions during the checkout process.

The Stock Keeping Unit (SKU) of the free product.

suggestedProducts.eligiblePriceLists

integer<int32>[]

The price list IDs, eligible for promotions. When they're not specified, the promotion applies to all price lists. specified, promotion applies to all price lists.

The price list ID associated with the item generated using the create price list endpoint.

suggestedProducts.quantity

integer<int32>

The number of complimentary items in the promotion.

Example:

2

suggestedProducts.promotionQuantity

integer<int32>

The maximum limit of complimentary items available for the BuyGet promotion. For example, consider the promotionQuantity is 10 and promotion condition is Buy 1 pair of shoes and Get 1 pair of socks free. If a shopper purchases up to 10 pairs of shoes, they will get an equivalent number of socks for free. However, even if they buy more than 10 pairs of shoes, the maximum free pairs of socks will remain 10, as defined by the promotionQuantity parameter.

Example:

10

suggestedProducts.isFree

boolean

A flag indicating whether a free item is included as part of promotion. Set to true to indicate a free item is offered as promotion and false to indicate otherwise.

suggestedProducts.discountType

string

The type of discount.

Example:

"PERCENTAGE_OFF"

suggestedProducts.amount

number<double>

The discount amount.

Example:

100.15

Example:

[
  {
    "promotionId": "6197ec46e836ff000952c665",
    "promotionName": "Buy shoes get socks for free",
    "itemId": 234343,
    "itemIds": [1120201, 1120202],
    "sku": "SHOE1234",
    "skus": ["SHOE-1", "SHOE-2"],
    "eligiblePriceLists": [10000],
    "quantity": 2,
    "promotionQuantity": 10,
    "isFree": true,
    "discountType": "PERCENTAGE_OFF",
    "amount": 105.15
  }
]

notAppliedCoupons

object[]

Rejected coupons

Show child attributes

notAppliedCoupons.couponCode

string | null

Coupon code

Example:

"SUPERCOUPON"

notAppliedCoupons.promotionId

string | null

A 24-character system-generated coupon ID generated using the create coupon endpoint.

Example:

"624b5aa2a8fd12000965dfdc"

notAppliedCoupons.message

string | null

Reason why coupon not applied

Example:

"Invalid coupon"

Example:

[
  {
    "couponCode": "SUPERCOUPON",
    "promotionId": "624b5aa2a8fd12000965dfdc",
    "message": "Invalid coupon"
  }
]

promotionMessages

object[]

The promotion message that is displayed to the customer.

Show child attributes

promotionMessages.title

string

Message name

Example:

"Buy 2 get 1 free"

promotionMessages.message

string

Message description

Example:

"Offer valid at participating stores through September 5, 2023."

promotionMessages.pages

enum<string>[]

The types of web pages where the message is displayed.

Page type

Available options:

PDP,

PLP,

Cart,

Checkout

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

Locale

promotionMessages.type

enum<string>

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.

Available options:

DISCOUNT,

PROXIMITY,

POTENTIAL_DISCOUNT

Example:

"DISCOUNT"

promotionMessages.threshold

integer<int32>

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.

Example:

2

A 24-character system-generated coupon ID generated using the create coupon endpoint.

Example:

"61df12345678900009b7091c"

Offers User Guides

Offers API

Evaluate cart promotions

Authorizations

Headers

Body

Response