> ## Documentation Index
> Fetch the complete documentation index at: https://developer.fabric.inc/llms.txt
> Use this file to discover all available pages before exploring further.
# 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)
## OpenAPI
````yaml offers_v2_combined post /v1/promo/evaluate-promotions
openapi: 3.0.0
info:
title: Offers v2
description: >-
fabric's Offers APIs let you set up and manage stock keeping unit (SKU)
prices. Its wide range of coupon and promotion features let you design
discounts ranging from single-use, customer-specific coupons to site-wide
promotions applicable for all SKUs.
version: 2.0.0
contact:
email: support@fabric.inc
license:
url: https://fabric.inc/api-license
name: fabric API license
servers:
- url: https://live.copilot.fabric.inc
description: Production
security:
- AuthorizationToken: []
tags:
- name: Price List
description: >-
Price list is a collection of items and their assigned prices. An item can
exist in multiple price lists. This gives you the ability to assign
different prices to the same item. Price lists let you set currency and
duration of the prices. For example, if the price list expires, prices of
items within the price list will also expire. You can configure the
pricing API to include your default price.
When requesting pricelist
of items or evaluating promotions, you should mention the price list ID
that you want to use.
- name: Pricing
description: >-
Pricing endpoints let you create and manage price details for one or many
items. You can configure the pricing API to include your default price
list in all requests.
- name: Price Guard
description: >-
Price Guard allows you to create and manage more diversified price-kinds
for the item, such as manufacturer recommended retail price (MSRP),
minimum advertised price (MAP), floor price, ceiling price, clearance
price, and so on. Price guard works as a protection mechanism against
any further creation of prices for the item. These endpoints let you
create and manage such price-kinds.
- name: Price Kind
description: >-
Unlike price guard, price kind endpoint lets you get the fundamental price
kinds (for example, base price and sale price) that are created while
setting up the item information.
- name: Promotion
description: >-
Promotion is a discount on an item, cart or shipping method based on set
conditions. As promotions can be linked to specific price lists, it is
important to submit the correct price list ID. Promotion endpoints let you
create and manage discounts that will be applied to all customers' carts
that meet the required conditions.
- name: Coupon
description: >-
Coupon endpoints let you create and manage coupon codes that customers can
enter at checkout to receive a discount.
- name: Dynamic Pricing Engine
description: >-
fabric's Dynamic Pricing Engine APIs evaluate promotions and calculate
prices instantly for the cart items using real-time price calculation
method, that incorporates the latest information, to provide personalized
and competitive prices for specific customers. It supports formula based
custom SKU dynamic pricing, and shows discount breakdown details for
separate items having separate promotions. It uses the cache information,
instead of fetching offer details of items from database, to evaluate
promotions and calculate prices instantly. It is fast, scalable to
millions of pricing requests per day, and supports complex promotional
strategies.
- name: Global exclusion
description: >-
Global exclusions let you exclude SKUs from being discounted by active
promotions. These endpoints let you manage those sku-lists.
- name: Redemption
description: Redemption endpoints let you manage the records of coupon redemptions.
- name: Segment
description: >-
Segment endpoints let you target promotions at specific groups of
customers by linking the promotion to a segment identifier. A customer
segment is a group of customers that have been given a unique reference to
easily identify them. They may be grouped in a number of ways such as
demographics, locations, device type, and so on. fabric Offers supports
the assignment of a customer segment to a promotion so that the promotion
is applied only to a specific group of customers. You must enter your
customer segment identifiers in the *Settings* of the Copilot application.
- name: Upload price CSV
description: This endpoint lets you bulk upload price details using a CSV file.
- name: Product
description: >-
Product endpoint lets you get product and price information based on sku.
Product information is retrieved from Product Catalog and price details
are retrieved from Offers service.
- name: Item
description: >-
Item endpoints let you get products and prices information based on
itemId. Product information of an item is retrieved from Product Catalog
and price details are retrieved from Offers service.
- name: Attributes
description: >-
Attributes refer to a collection of attributes names and their values.
Using attributes, you can group entities, such as products or shoppers,
that share similar characteristics, such as dimension, age group,
location, device type, and more. For example, the shopper segmentation can
be used to tailor promotions to a specific customer segment by linking the
promotion to the segment identifier.
- name: Exports
description: >-
fabric Export endpoints let you export data to CSV files based on the
provided filters.
externalDocs:
description: Learn more about Offers
url: https://developer.fabric.inc/docs/offers-overview
paths:
/v1/promo/evaluate-promotions:
post:
tags:
- Dynamic Pricing Engine
summary: Evaluate promotions
description: >-
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)
operationId: evaluatePromotions
parameters:
- $ref: '#/components/parameters/xSiteContent'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/promotionEvaluationRequest'
required: true
responses:
'200':
description: Successfully evaluated the promotions
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/promotionEvaluationResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
'403':
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/apiError'
components:
parameters:
xSiteContent:
name: x-site-context
in: header
description: >-
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.
required: true
schema:
type: string
example: >-
{"date": "2023-01-01T00:00:00.000Z", "channel": 12, "account":
"1234abcd5678efgh9ijklmno","stage":"production"}
schemas:
promotionEvaluationRequest:
required:
- items
type: object
description: Prices conditions
properties:
traceId:
type: string
description: Trace ID, used to trace logs
example: '394823457'
isLoggedIn:
type: boolean
description: 'true: user logged in
false: user is not logged in'
example: true
userId:
type: string
description: User ID
example: 5e2cfb9b45570b000864c4b5
promoCodes:
type: array
description: >-
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.
example:
- SUPERCOUPON1
- FIRSTPURCHASE10
items:
type: string
shipping:
type: array
description: >-
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.
items:
$ref: '#/components/schemas/promotionRequestShipping'
items:
type: array
description: List of item information objects
items:
$ref: '#/components/schemas/promotionRequestItem'
date:
pattern: yyyy-MM-ddThh:mm:ssZ
type: string
description: Date for which the promotions to be evaluated
format: date-time
example: '2019-08-24T14:15:22Z'
userProfile:
type: array
description: Segment the user belongs to
example:
Customer Type:
- Wholesale
items:
type: object
additionalProperties:
type: array
items:
type: string
promotionEvaluationResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/promotionResponseItem'
errors:
type: array
example:
- Parameter does not exist
items:
type: string
shipping:
type: array
items:
$ref: '#/components/schemas/promotionResponseShipping'
appliedDiscounts:
type: array
items:
$ref: '#/components/schemas/appliedDiscount'
suggestedProducts:
type: array
items:
$ref: '#/components/schemas/suggestedProducts'
notAppliedCoupons:
uniqueItems: true
type: array
items:
$ref: '#/components/schemas/couponError'
promotionMessages:
$ref: '#/components/schemas/rtpePromotionMessages'
success:
type: boolean
description: Indicates if promotion is successfully evaluated
apiError:
type: object
properties:
status:
type: string
description: Http Status
example: NOT_FOUND
enum:
- 100 CONTINUE
- 101 SWITCHING_PROTOCOLS
- 102 PROCESSING
- 103 CHECKPOINT
- 200 OK
- 201 CREATED
- 202 ACCEPTED
- 203 NON_AUTHORITATIVE_INFORMATION
- 204 NO_CONTENT
- 205 RESET_CONTENT
- 206 PARTIAL_CONTENT
- 207 MULTI_STATUS
- 208 ALREADY_REPORTED
- 226 IM_USED
- 300 MULTIPLE_CHOICES
- 301 MOVED_PERMANENTLY
- 302 FOUND
- 302 MOVED_TEMPORARILY
- 303 SEE_OTHER
- 304 NOT_MODIFIED
- 305 USE_PROXY
- 307 TEMPORARY_REDIRECT
- 308 PERMANENT_REDIRECT
- 400 BAD_REQUEST
- 401 UNAUTHORIZED
- 402 PAYMENT_REQUIRED
- 403 FORBIDDEN
- 404 NOT_FOUND
- 405 METHOD_NOT_ALLOWED
- 406 NOT_ACCEPTABLE
- 407 PROXY_AUTHENTICATION_REQUIRED
- 408 REQUEST_TIMEOUT
- 409 CONFLICT
- 410 GONE
- 411 LENGTH_REQUIRED
- 412 PRECONDITION_FAILED
- 413 PAYLOAD_TOO_LARGE
- 413 REQUEST_ENTITY_TOO_LARGE
- 414 URI_TOO_LONG
- 414 REQUEST_URI_TOO_LONG
- 415 UNSUPPORTED_MEDIA_TYPE
- 416 REQUESTED_RANGE_NOT_SATISFIABLE
- 417 EXPECTATION_FAILED
- 418 I_AM_A_TEAPOT
- 419 INSUFFICIENT_SPACE_ON_RESOURCE
- 420 METHOD_FAILURE
- 421 DESTINATION_LOCKED
- 422 UNPROCESSABLE_ENTITY
- 423 LOCKED
- 424 FAILED_DEPENDENCY
- 425 TOO_EARLY
- 426 UPGRADE_REQUIRED
- 428 PRECONDITION_REQUIRED
- 429 TOO_MANY_REQUESTS
- 431 REQUEST_HEADER_FIELDS_TOO_LARGE
- 451 UNAVAILABLE_FOR_LEGAL_REASONS
- 500 INTERNAL_SERVER_ERROR
- 501 NOT_IMPLEMENTED
- 502 BAD_GATEWAY
- 503 SERVICE_UNAVAILABLE
- 504 GATEWAY_TIMEOUT
- 505 HTTP_VERSION_NOT_SUPPORTED
- 506 VARIANT_ALSO_NEGOTIATES
- 507 INSUFFICIENT_STORAGE
- 508 LOOP_DETECTED
- 509 BANDWIDTH_LIMIT_EXCEEDED
- 510 NOT_EXTENDED
- 511 NETWORK_AUTHENTICATION_REQUIRED
timestamp:
type: string
format: date-time
message:
type: string
description: Error message
example: Validation error
debugMessage:
type: string
description: More detailed message for debugging
example: Either item ID or SKU is mandatory.
subErrors:
type: array
description: Sub errors related to validations
items:
$ref: '#/components/schemas/apiSubError'
promotionRequestShipping:
type: object
properties:
shippingMethodId:
type: string
description: Shipping method ID to check if promotion is applied to it
example: 123
shippingPrice:
type: number
description: Shipping price for the entire cart
format: double
example: 20
promotionRequestItem:
required:
- priceList
- quantity
type: object
properties:
lineItemId:
type: integer
description: Item sequence number
format: int32
example: 1
priceList:
type: string
description: Price list ID or name
example: 100275
sku:
type: string
description: >-
SKU of the item. Either SKU or ItemId is mandatory. If both
provided, SKU overrides itemId.
example: 1111111
itemId:
type: integer
description: >-
ID of the item. Either SKU or ItemId is mandatory. If both provided,
SKU overrides itemId.
format: int32
example: 1111111
quantity:
type: number
description: Quantity of the item ordered
format: double
example: 5
group:
type: array
description: >-
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.
example:
- 5e2cfb9b45570b000863c4b5
items:
type: string
hierarchy:
type: array
description: Item hierarchy to evaluate promotions
example:
- - clothingId1
- footwear
- sandalsId1
- - nike
- sandalsId2
- - clothingId2
- beach
items:
type: array
items:
type: string
productAttributes:
type: object
additionalProperties:
description: Product attributes
oneOf:
- type: array
items:
type: string
example:
- red
- green
- type: string
example: red
example:
color:
- red
- green
brand: Nike
size: '10'
priceParams:
$ref: '#/components/schemas/pricePromoParam'
price:
$ref: '#/components/schemas/itemPriceOverride'
channel:
type: array
description: List of channel IDs from where the request is coming
example:
- 12
- 15
items:
type: integer
format: int32
shippingMethodId:
type: string
description: >-
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.
example: 123
shippingPrice:
type: number
description: >-
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.
format: double
example: 20
promotionResponseItem:
type: object
properties:
lineItemId:
type: integer
description: Sequence number of the item
format: int32
example: 1
sku:
type: string
description: Item SKU
example: 1111111
itemId:
type: integer
description: Item ID
format: int32
example: 1111111
priceList:
type: string
description: Price list ID or name, depending on configuration
example: 100275
group:
type: array
description: >-
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.
example:
- 5e2cfb9b45570b000863c4b5
- clothingId1
- footwear
items:
type: string
quantity:
type: number
description: Number of items
format: double
example: 5
price:
$ref: '#/components/schemas/itemPrice'
priceAttributes:
$ref: '#/components/schemas/itemPriceAttributes'
discount:
type: array
items:
$ref: '#/components/schemas/offerDiscount'
attributes:
type: object
additionalProperties:
type: object
description: Product attributes
example:
color: red
brand: Nike
size: '10'
description: Product attributes
example:
color: red
brand: Nike
size: '10'
shippingPrice:
type: number
description: Shipping price
format: double
example: 20
shippingMethodId:
type: string
description: >-
Shipping method ID used to check if promotion is applicable to the
shipping method
example: 123
shippingDiscount:
type: number
description: Shipping discount if any
format: double
example: 5
promotionResponseShipping:
type: object
properties:
shippingMethodId:
type: string
description: Shipping Method ID
example: 456
shippingPrice:
type: number
description: Shipping price
format: double
example: 5
shippingDiscount:
type: number
description: Shipping discount
format: double
example: 5
appliedDiscount:
type: object
description: Details of discounts that are applied
properties:
promoId:
type: string
description: Promotion ID
example: 6197ec46e836ff000952c668
promoCode:
type: string
description: Coupon code
example: SUPERCOUPON20
promoTitle:
type: string
description: Promotion title
example: 20% off
type:
type: string
description: Promotion type
example: COUPON
amount:
type: number
description: Discount amount
format: double
example: 10
suggestedProducts:
type: object
properties:
promotionId:
type: string
description: Promotion ID
example: 6197ec46e836ff000952c668
promotionTitle:
type: string
description: Promotion title
example: Buy Shoes, get socks for free
itemId:
type: string
description: Free Item's ID
example: 234343
sku:
type: string
description: Free SKU
example: SHOE1234
eligiblePriceLists:
type: array
description: >-
Price list IDs promotion applies to. If empty, promotion applies to
all price lists.
items:
type: string
example: 1000
quantity:
type: integer
description: Number of free items promotion gives
format: int32
example: 2
free:
type: boolean
description: true when a free item is provided as a promotion
example: true
discountType:
type: string
description: Type of discount
enum:
- '%OFF'
- AMOUNT_OFF
- FIXED_PRICE
example: '%OFF'
amount:
type: number
description: Amount for discount
format: double
example: 100
couponError:
type: object
description: Details of error in case coupon is not applied
properties:
promoCode:
type: string
description: Coupon code
example: SUPERCOUPON
promoId:
type: string
description: Promotion ID
example: 624b5aa2a8fd12000965dfdc
message:
type: string
description: Reason why coupon not applied
example: Invalid coupon
rtpePromotionMessages:
type: array
description: The promotion message that is displayed to the customer.
required:
- message
- locales
- type
items:
type: object
description: The promotion message that is displayed to the customer.
properties:
promoId:
type: string
description: Promotion ID
example: 61df12345678900009b7091c
title:
type: string
description: >-
The title of the promotion message, summarizing the offer or
discount type.
example: Buy 2 get 1 free
message:
type: string
description: >-
A promotional message providing details about the offer, including
eligibility, duration, and conditions.
example: Offer valid at participating stores through September 5, 2023.
pages:
type: array
description: >-
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.
items:
type: string
description: Page type
enum:
- PDP
- PLP
- Cart
- Checkout
example: PDP
locales:
type: array
description: >-
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.
items:
type: string
description: Locale
example: en-CA
type:
type: string
description: |-
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.
enum:
- DISCOUNT
- PROXIMITY
- POTENTIAL_DISCOUNT
example: DISCOUNT
threshold:
type: integer
format: int32
description: >-
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
apiSubError:
type: object
properties:
object:
type: string
description: Erroneous object
example: promotionsEvaluationRequest
field:
type: string
description: Request body field
example: items[0].quantity
rejectedValue:
type: object
description: Request body field value
example: -2
message:
type: string
description: Error message
example: Must be greater than 0
description: Sub errors related to validations
pricePromoParam:
type: object
description: Price parameters for calculating price
properties:
options:
type: object
additionalProperties:
type: object
description: >-
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.
example:
length: '2'
width: '15'
blindMotor: true
description: Pricing options for calculation
example:
length: '2'
width: '15'
blindMotor: true
itemPriceOverride:
type: object
description: >-
Price object. This will override the promotion evaluation response
prices.
properties:
sale:
type: number
description: Price at which the product is offered for sale
format: double
example: 10
base:
type: number
description: Minimum fixed price of a single unit of the item
format: double
itemPrice:
type: object
properties:
currency:
type: string
description: Currency code
example: USD
base:
type: number
description: Base price. It is the minimum fixed price of the item
format: double
example: 10
kind:
type: string
description: Price kind name
example: BASE
totalPrice:
type: number
description: Total price after all the discounts
format: double
example: 50
finalPrice:
type: number
description: Final Price of the item, does not include discounts
format: double
example: 50
sale:
type: number
description: Price at which the item is offered for sale
format: double
example: 50
itemPriceAttributes:
type: object
description: Returned if configured earlier
properties:
cost:
type: number
description: Cost price
format: double
example: 9
floor:
type: number
description: It is the lowest price at which a product can be sold
format: double
example: 10
clearance:
type: number
description: Selling price
format: double
example: 10
offerDiscount:
type: object
properties:
quantity:
type: integer
description: Number of items
format: int32
example: 5
amount:
type: number
description: Discount amount
format: double
example: 10
unit:
type: string
description: Unit of discount measurement
example: '%OFF'
value:
type: number
description: Discount value
format: double
example: 10
promoId:
type: string
description: Promotion ID
example: 6197ec46e836ff000952c668
promoCode:
type: string
description: Coupon code
example: SUPERCOUPON20
promoTitle:
type: string
description: Promotion title
example: 20% off
type:
type: string
description: Promotion type
example: COUPON
application:
type: integer
description: >-
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.
format: int32
example: 1
isStackable:
type: boolean
description: >-
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.
example: true
isAlwaysApplied:
type: boolean
description: >-
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.
example: false
level:
type: integer
format: int32
description: >-
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.
example: 1
stackingType:
type: string
description: >-
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.
enum:
- STACKABLE
- EXCLUSIVE
- TYPE_EXCLUSIVE
- UNIVERSAL
example: STACKABLE
proratedAmount:
type: number
format: double
description: >-
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`.
example: 10
proratedQuantity:
type: integer
format: int32
description: >-
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.
example: 1
securitySchemes:
AuthorizationToken:
type: http
scheme: bearer
bearerFormat: JWT
````