openapi: 3.0.1
info:
title: Common Entities - Offers
description: Common Offers domain entities
x-audience: external-public
contact:
name: Offers support
email: support@fabric.inc
license:
name: fabric API License
url: https://fabric.inc/api-license
termsOfService: https://fabric.inc/terms-of-use
version: 3.0.0
servers:
- url: https://api.fabric.inc/v3
description: Production environment
tags:
- name: Product Prices
description: >-
Product prices endpoints calculate price details for one or more products
in real-time, so you can display the calculated price on your website.
- name: Cart Prices
description: >-
The cart prices endpoint evaluates promotions and discount coupons
instantly. The evaluate promotions endpoint let you submit a range of data
that will be referenced against the conditions that are set earlier using
the promotions, coupons or prices APIs. The response includes the details
of the promotions and discounts applied. These can be displayed on your
website to help shoppers know that they're getting their expected
discounts.
paths: {}
components:
schemas:
couponCodes:
type: array
description: Promotion codes to be applied
items:
type: string
description: Promotion code
example: SUPERCOUPON1
couponCode:
type: string
description: Promotion code
example: SUPERCOUPON1
priceOverride:
type: object
description: Price object that overrides the promotion evaluation response prices
example:
sale: 900.15
base: 5.15
properties:
sale:
type: number
description: Price at which the product is offered for sale
format: double
example: 10.15
base:
type: number
description: Minimum fixed price of a single item unit
format: double
example: 10.15
priceAttributes:
type: object
description: Price attributes
example:
floor: 1000.15
cost: 900.15
clearance: 2000.15
properties:
cost:
type: number
description: Cost price
format: double
example: 9.15
floor:
type: number
description: Lowest price at which a product is sold
format: double
example: 10.15
clearance:
type: number
description: Selling price
format: double
example: 10.15
notAppliedCoupon:
type: object
description: Coupon details
example:
couponCode: SUPERCOUPON
promotionId: 624b5aa2a8fd12000965dfdc
message: Invalid coupon
properties:
couponCode:
type: string
nullable: true
description: Coupon code
example: SUPERCOUPON
promotionId:
type: string
nullable: true
description: Promotion ID
example: 624b5aa2a8fd12000965dfdc
message:
type: string
nullable: true
description: Reason why coupon not applied
example: Invalid coupon
suggestedProduct:
type: object
description: >-
Complimentary or free products offered to shoppers in the context of
BuyGet and SpendGet promotions.
properties:
promotionId:
type: string
nullable: true
description: The promotion ID
example: 6197ec46e836ff000952c665
promotionName:
type: string
nullable: true
description: The promotion name
example: Buy shoes get socks for free
itemId:
type: integer
nullable: true
description: The item ID of the free product
format: int32
example: 234343
itemIds:
type: array
description: >-
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.
items:
type: integer
description: The item ID of the free product.
format: int32
example: 500001
sku:
type: string
description: The Stock Keeping Unit (SKU) of the free product.
example: SHOE1234
skus:
type: array
description: >-
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.
items:
type: string
description: The Stock Keeping Unit (SKU) of the free product.
example: SHOE-4
eligiblePriceLists:
type: array
description: >-
The price list IDs eligible for promotion. When they're not
specified, promotion applies to all price lists.
items:
type: integer
description: The price list ID.
format: int32
example: 1000
quantity:
type: integer
description: The number of complimentary items in the promotion.
format: int32
example: 2
promotionQuantity:
type: integer
description: >-
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.
format: int32
example: 10
isFree:
type: boolean
description: >-
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.
discountType:
type: string
description: The type of discount.
example: PERCENTAGE_OFF
amount:
type: number
description: The discount amount.
format: double
example: 100.15
segment:
type: object
description: The segments to which the user belong.
example:
- name: category
value:
- GOLD
- YELLOW
properties:
name:
description: The segment name.
type: string
example: category
value:
type: array
description: The segment values.
items:
type: string
example: GOLD
appliedDiscount:
type: object
description: Discount details
example:
promotionId: 6197ec46e836ff000952c665
promotionName: Buy shoes get socks for free
couponCode: SUPERCOUPON20
type: COUPON
amount: 105.15
properties:
promotionId:
type: string
nullable: true
description: Promotion ID
example: 6197ec46e836ff000952c664
couponCode:
type: string
nullable: true
description: Coupon code
example: SUPERCOUPON20
promotionName:
type: string
nullable: true
description: Promotion name
example: 20% off
type:
type: string
nullable: true
description: Promotion type
example: COUPON
amount:
type: number
nullable: true
description: Discount amount
format: double
example: 10.15
promotionDiscount:
type: object
description: Promotion discount
example:
amount: 100.15
quantity: 1
proratedAmount: 100.15
proratedQuantity: 1
application: 1
promotion:
id: 6197ec46e836ff000952d668
value: 2000.15
groupId: 61a6354d0d70e30009415f16
level: 1
isStackable: true
isAlwaysApplied: true
name: 20% OFF
type: Coupon
discountType: AMOUNT_OFF
properties:
amount:
type: number
description: Actual discount amount
format: double
example: 1000.15
quantity:
type: integer
description: The number of items eligible for the promotional discount.
format: int32
example: 5
proratedAmount:
type: number
description: >-
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.
format: double
example: 1000.15
proratedQuantity:
type: integer
description: >-
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.
format: int32
example: 5
application:
type: integer
nullable: true
description: >-
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.
format: int32
example: 1
promotion:
type: object
description: The promotion details.
example:
id: 6197ec46e836ff000952c668
value: 2000.15
groupId: 61a6354d0d70e30009415f16
level: 1
isStackable: true
isAlwaysApplied: true
name: 20% OFF
type: Coupon
discountType: AMOUNT_OFF
properties:
id:
type: string
description: A 24-character system-generated Promotion ID.
example: 6197ec46e836ff000952c667
value:
type: number
description: The discount in percent or amount.
format: double
example: 2000.15
groupId:
type: string
nullable: true
description: ID of the group or category this product belongs to
example: 61a6354d0d70e30009415f16
level:
type: integer
nullable: true
description: The order in which the current promotion is executed.
format: int32
example: 1
isStackable:
type: boolean
nullable: true
description: >-
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
isAlwaysApplied:
type: boolean
nullable: true
description: >-
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
name:
type: string
description: The name of the promotion.
example: 20% off
type:
type: string
description: The type of the promotion.
example: COUPON
discountType:
example: PERCENTAGE_OFF
type: string
description: The type of discount.
enum:
- PERCENTAGE_OFF
- AMOUNT_OFF
- FIXED_PRICE
arrayOfStrings:
type: array
description: Array of strings
example:
- blue
- red
items:
type: string
description: String value
example: blue
priceAdditionalProperties:
type: object
description: Parameters for calculating price
properties:
additionalProperties:
type: array
description: Additional properties for calculating price
example:
- id: length
value: 10
- id: width
value: 20
items:
type: object
properties:
id:
description: Variable ID
type: string
example: length
value:
description: Variable value
type: number
example: 10
format: double
promotionDiscountWithPromoMessage:
type: object
description: Promotion discount
example:
amount: 100.15
quantity: 1
application: 1
promotion:
id: 6197ec46e836ff000952d668
value: 2000.15
groupId: 61a6354d0d70e30009415f16
level: 1
isStackable: true
isAlwaysApplied: true
name: 20% OFF
type: Coupon
discountType: AMOUNT_OFF
properties:
amount:
type: number
description: Actual discount amount
format: double
example: 1000.15
quantity:
type: integer
description: The number of items eligible for the promotional discount.
format: int32
example: 5
application:
type: integer
nullable: true
description: >-
The number of times the BuyGet promotion can be used, indicating how
many times you can use the promotions, such as get a certain amount
or percentage off, or get free items when making a purchase.
format: int32
example: 1
promotion:
type: object
description: Promotion object
example:
id: 6197ec46e836ff000952c668
value: 2000.15
groupId: 61a6354d0d70e30009415f16
level: 1
isStackable: true
isAlwaysApplied: true
name: 20% OFF
type: Coupon
discountType: AMOUNT_OFF
properties:
id:
type: string
description: Promotion ID
example: 6197ec46e836ff000952c667
value:
type: number
description: Discount in percent or amount
format: double
example: 2000.15
groupId:
type: string
nullable: true
description: ID of the group or category this product belongs to
example: 61a6354d0d70e30009415f16
level:
type: integer
nullable: true
description: The order in which the current promotion is executed.
format: int32
example: 1
isStackable:
type: boolean
nullable: true
description: >-
Specifies whether the promotion is stackable. You can set one of
the following:
True: You can combine this promotion with
other promotions. The discount of the current promotion is
combined with other promotions, if applicable, to the item.
False: The promotion isn't stackable. You can't combine this
promotion with other promotions.
example: true
isAlwaysApplied:
type: boolean
nullable: true
description: >-
Specifies whether the promotion is applied regardless of the
exclusive promotions on the same item. You can set one of the
following values:
true: Promotion is applied regardless of
the exclusive promotions on the same item.
false: Promotion
isn't applied on the item
example: true
name:
type: string
description: Promotion name
example: 20% off
type:
type: string
description: Promotion type
example: COUPON
discountType:
example: PERCENTAGE_OFF
type: string
description: Discount type
enum:
- PERCENTAGE_OFF
- AMOUNT_OFF
- FIXED_PRICE
promotionMessages:
$ref: '#/components/schemas/promotionMessages'
promotionMessages:
type: array
description: The message displayed for the promotion.
required:
- title
- locales
- pages
items:
type: object
description: The message displayed for the promotion.
properties:
title:
type: string
description: Message name
example: Buy 1 get 1 free
message:
type: string
description: Message description
example: Offer valid at participating stores through September 5, 2023.
pages:
type: array
description: The types of web pages where the message is displayed.
items:
type: string
description: Page type
example: PDP
example:
- PDP
- Cart
locales:
type: array
description: >-
The locales in which the promotion message is displayed. Locale is
a set of language or country-based preferences for user interface.
items:
type: string
description: Locale
example: en-CA
example:
- en-CA
- fr-CA
promoId:
type: string
description: Promotion ID
example: 61df12345678900009b7091c