Create promotion

Getting Started

Authentication v3

Concepts
System Apps
User Apps
Authentication Endpoints

Product Catalog

Product Catalog API - Overview
Developer Guide
Data Ingestion Best Practices
Attributes & Attribute Mapping
Categories
Products
Collections
Background Jobs
Bulk Import & Export
Published Products

Orders

Orders (3.0.0)
Developer Guide
Orders FAQ
Shopping Lists
Shipping Methods
Imports
Exports
Orders
Frauds
Notifications
Backorders Preorders
Cancellations
Allocations
Shipments
Inventory Transfers
Tracking
Invoices
Payments
Credits
Appeasements
Returns

Inventory

Inventory (3.0.0)
Inventory FAQ
Imports
Counters
Inventory
Locations
Networks

Integrations

Offers

Offers (3.0.0)
Developer Guide
Real-time Pricing Engine
Price Lists
Prices
Price Types
Price Controls
Price Methods
Priced Products
Add-ons
Promotions
- Overview
- POST
  Create promotion
- GET
  Get a specific promotion
- PUT
  Update a specific promotion
- POST
  Enable or disable a promotion
- POST
  End a promotion
- DEL
  Delete a specific promotion
- POST
  Search for promotions
- GET
  Get all promotions
Coupons
Coupon Codes
Redemptions
Product Exclusion Lists
Segments
Imports
Exports
Attributes
Webhook Events

Carts

Overview
Developer Guides
Carts
Order Draft
Items
Addresses
Payments
Fulfillment
Customer
Coupons
Validations
Cart Orchestrator

Customers

Customer Profile
Customer Address
Customer Self

POST

promotions

object

name

string

startAt

string

endAt

string

type

enum<string>

buyOperator

enum<string>

details

array

termsAndConditions

array

promotionMessages

array

proximityMessages

object

threshold

integer

localizedMessages

array

promotionConditionDetail

object

type

enum<string>

values

string

operator

enum<string>

shipmentMethodIds

array

eligiblePriceLists

array

limits

array

additionalAttributes

array

note

string

level

integer

stackingType

enum<string>

isStackable

boolean

isAlwaysApplied

boolean

Authorizations

Authorization

string

headerrequired

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

x-client-id

string

A unique identifier obtained from Copilot for the System app in the fabric ecosystem, essential for OpenID Connect authentication flows.

x-fabric-request-id

string

A unique request ID.

Body

application/json

Promotion details to be created

name

string

required

The name of the promotion.

Required string length: 3 - 120

startAt

string

required

Promotion start time

endAt

string

required

Promotion end time

type

enum<string>

required

The type of promotion you want to create. The following are the promotion types you can create:

PRODUCT: A SKU promotion. Applies a discount to SKUs based on the value specified in the discount object of the request body.
CART: A cart promotion. Applies a discount to the minimum order amount of the cart based on the ORDER_VALUE specified in the condition object of the request body.
QUANTITY: A quantity promotion. Provides discounts on items based on the quantity requirement set in the promotion.
SHIPPING: A shipping promotion. Provides discounts on the shipping cost.
BUYGET: A BuyGet promotion. Specifies the Buy conditions and corresponding Get discounts.
SPEND_GET: A SpendGet promotion. Specifies the total order value required to qualify for discounts and the applicable discounts based on the order value.

Available options:

PRODUCT,

CART,

QUANTITY,

SHIPPING,

BUYGET,

SPEND_GET

details

object[]

required

Promotion setup details

details.discounts

object[]

required

An array containing discount details.

details.discounts.unit

enum<string>

required

Discount type

Available options:

PERCENTAGE_OFF,

AMOUNT_OFF,

FIXED

details.discounts.amount

number

required

Discount amount to be given

details.discounts.type

enum<string>

required

Discount type for where the discount applies. The following are valid target options for applying the discount:

SKU: Discount is applied to products.
CART: Discount is applied to the entire cart value.
SERVICE: Discount is applied to SKU shipping.
SERVICE_CART: Discount is applied to cart shipping cost.

Available options:

SKU,

CART,

SERVICE,

SERVICE_CART

details.discounts.values

Should be null for SKU and CART

details.discounts.maximumQuantity

number

Maximum quantity of items that can receive the discount. Quantity is required when the promotion type is SPEND_GET or BUYGET.

details.discounts.includeOperator

enum<string>

default: OR

Select the AND or OR condition to include products in a promotion.

Use the OR condition to apply a single rule for product inclusion.
Use the AND condition to apply multiple rules for product inclusion.

Available options:

AND,

OR

details.discounts.excludeOperator

enum<string>

default: AND

Select the AND or OR condition to exclude products from a promotion.

Use the OR condition to apply a single rule for product exclusion.
Use the AND condition to apply multiple rules for product exclusion.

Available options:

AND,

OR

details.discounts.discountId

string

Discount ID to link discount and targetProduct. It's required for BUYGET and SPEND_GET promotions.

details.discounts.isAutoAdd

boolean

default: false

Represents if validate endpoint (evaluation endpoint from Real-time Pricing Engine) should suggest free items. Currently used for BUY-GET type of promotion.

details.discounts.sets

enum<string>[]

Reserved for additional information. It's used to create a group of items in a set so that you can easily apply promotions or coupons to the defined set of items.

Available options:

A,

B,

C,

D,

E,

F,

G,

H,

I,

J,

K,

L,

M,

N,

O,

P,

Q,

R,

S,

T,

U,

V,

W,

X,

Y,

Z

details.targetProducts

object[]

required

A list of target products for applying the discount.

details.conditions

object[]

required

Conditions list for the promotion to be applied

buyOperator

enum<string>

default: OR

Operator for conditions array. It's applied only when the promotion type is BUYGET. It's used as an operator between different conditions mentioned in the details array.

Available options:

AND,

OR

termsAndConditions

object[]

Terms and conditions for the promotion

promotionMessages

object[]

Message description for the promotion

proximityMessages

object

promotionConditionDetail

object

Represents the conditions based on which the promotions apply. For example, consider the type is USER_SEGMENT with multiple values. To target all the specified segments, use the AND operator and to target any one of the segments, use the OR operator.

shipmentMethodIds

string[]

Required for Shipping type promotion to provide eligible shipment methods.

eligiblePriceLists

integer[]

Price list IDs to be considered for this promotion.

limits

object[]

Restrictions or conditions that apply to the use of a promotion

additionalAttributes

object[]

Merchant-specified attributes associated with the promotion.

note

string

Promotion note or description

level

integer

Promotion execution order. Promotion types are assigned a default execution order. First, level 1 promotions will be evaluated. The result of level 1 will be used as a base price for level 2. Similarly, the result of level 2 will be used as a base price for level 3.

Required range: 0 < x < 5

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. If configured, stackingType will have precedence over the isStackable and isAlwaysApplied. The following are possible stackingType 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

isStackable

boolean

true: The promotion can be stacked, and its discounts will be summed together with other promotions.
false: The promotion can't be applied with any other promotions.

isAlwaysApplied

boolean

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.

Response

201 - application/json

The details of the promotion.

string

required

A 24-character system-generated The promotion ID generated when using the create promotion endpoint.

name

string

required

The name of the promotion.

status

enum<string>

required

The current status of the promotion.

Available options:

ACTIVE,

SCHEDULED,

DISABLED,

EXPIRED

startAt

string

required

The start time of the promotion, in UTC format.

endAt

string

required

The end time of the promotion, in UTC format.

type

enum<string>

required

The type of promotion you want to create. The following are the promotion types you can create:

PRODUCT: A SKU promotion. Applies a discount to SKUs based on the value specified in the discount object of the request body.
CART: A cart promotion. Applies a discount to the minimum order amount of the cart based on the ORDER_VALUE specified in the condition object of the request body.
QUANTITY: A quantity promotion. Provides discounts on items based on the quantity requirement set in the promotion.
SHIPPING: A shipping promotion. Provides discounts on the shipping cost.
BUYGET: A BuyGet promotion. Specifies the Buy conditions and corresponding Get discounts.
SPEND_GET: A SpendGet promotion. Specifies the total order value required to qualify for discounts and the applicable discounts based on the order value.

Available options:

PRODUCT,

CART,

QUANTITY,

SHIPPING,

BUYGET,

SPEND_GET

createdAt

string

Record's creation time

updatedAt

string

Record's last updated time

level

integer

Required range: 0 < x < 5

stackingType

enum<string>

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

isStackable

boolean

true: The promotion can be stacked, and its discounts will be summed together with other promotions.
false: The promotion can't be applied with any other promotions.

isAlwaysApplied

boolean

additionalAttributes

object[]

A placeholder for additional attributes related to promotions, in name-values pairs.

promotionMessages

object[]

Message description for the promotion

Was this page helpful?

Overview Get a specific promotion