Create coupon

Create a coupon with the requested conditions.

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

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.

Example:

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

Body

application/json

Coupon record detail

name

string

required

Coupon name

Required string length: 3 - 120

Example:

"Christmas 2022 coupons"

startAt

string

required

The timestamp in UTC format indicating when the coupon becomes valid.

Example:

"2022-08-24T14:15:22.000Z"

endAt

string

required

The timestamp in UTC format indicating when the coupon becomes invalid.

Example:

"2019-08-25T14:15:22.000Z"

type

enum<string>

required

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

• PRODUCT: A SKU coupon promotion. Applies a discount to SKUs based on the value specified in the discount object of the request body.
• CART: A cart coupon 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 coupon promotion. Provides discounts on items based on the quantity requirement set in the promotion.
• SHIPPING: A shipping coupon promotion. Provides discounts on the shipping cost.
• BUYGET: A BuyGet coupon promotion. Specifies the Buy conditions and corresponding Get discounts.
• SPEND_GET: A SpendGet coupon 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

Example:

"PRODUCT"

couponCodes

string[]

required

An array containing coupon codes.

The coupon code.

details

object[]

required

Coupon creation details.

Coupon creation detail.

Show child attributes

details.discounts

object[]

required

An array containing discount details.

Discount details

Show child attributes

details.discounts.unit

enum<string>

required

Discount type

Available options:

PERCENTAGE_OFF,

AMOUNT_OFF,

FIXED

Example:

"PERCENTAGE_OFF"

details.discounts.amount

number

required

Discount amount to be given

Example:

15

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

Example:

"SKU"

details.discounts.values

Should be null for SKU and CART

Example:

null

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.

Example:

2

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

Example:

"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

Example:

"AND"

details.discounts.discountId

string

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

Example:

"1"

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.

Example:

false

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.

Set ID

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.

The details of the target products.

Show child attributes

details.targetProducts.type

enum<string>

required

The target type for the promotion.

Available options:

SKU,

CATEGORY,

ATTRIBUTE,

PRICE_TYPE,

COLLECTION,

PREVIOUS_DISCOUNTS

Example:

"SKU"

details.targetProducts.values

required

The values corresponding to the selection type.

Example:

"*"

details.targetProducts.operator

enum<string>

required

Indicates whether a target product is included or excluded from discounts. The following options are available:

• IN: The target product, with the specified type and value, is included for the discount to be applied.
• NOT_IN: The target product, with the specified type and value, is excluded from being discounted.
• EQUAL: The target product will be eligible for the discount if the defined type and value match the product selection.

Available options:

IN,

NOT_IN,

EQUAL,

GREATER_THAN

Example:

"IN"

details.targetProducts.discountId

string

Discount ID to link discount and targetProduct; required for BUYGET promotion

Example:

"1"

details.conditions

object[]

required

Conditions list for the promotion to be applied

Conditions for the promotion to be applied

Show child attributes

details.conditions.operator

enum<string>

required

Operator for condition within each object of the conditions array

Available options:

AND,

OR

Example:

"AND"

details.conditions.conditions

object[]

required

Conditions for the promotion to apply on specific targets

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.

Show child attributes

details.conditions.conditions.type

enum<string>

required

Condition type

Available options:

SKU,

QUANTITY,

CATEGORY,

ATTRIBUTE,

PRICE_TYPE,

CHANEL,

ORDER_VALUE,

USER_SEGMENT,

USER_TYPE,

DATE,

SKU_QUANTITY,

COLLECTION,

PRICE,

ORDER_LINE_ITEMS,

REGION,

PREVIOUS_DISCOUNTS

Example:

"SKU"

details.conditions.conditions.values

required

Applied on all items. Asterisk (*) indicates all items

Example:

"*"

details.conditions.conditions.operator

enum<string>

required

Operator between type and values within each object of conditions array

Available options:

NOT_EQUAL,

EQUAL,

GREATER_THAN,

LESS_THAN,

GREATER_THAN_OR_EQUAL_TO,

LESS_THAN_OR_EQUAL_TO,

NOT_IN,

IN

Example:

"IN"

details.conditions.id

string | null

Promotion condition ID

Example:

"6380e7ecb419a30009865fad"

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

Example:

"OR"

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

Example:

"AND"

details.conditions.set

enum<string>

default:

A

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

Example:

"A"

buyOperator

enum<string>

default:

OR

Operator for conditions array. It's applied when the coupon type is BUYGET. It's used as an operator between different condition objects mentioned in the conditions array.

Available options:

AND,

OR

Example:

"OR"

isExclusive

boolean

default:

false

• true: Makes the coupon exclusive, meaning it can't be applied if another promotion is already applied.
• false: Allows the coupon to be applied with other promotions.

Example:

true

limits

object[]

Restrictions or conditions that apply to the use of a coupon.

Coupon limit detail. Limits for coupons can only be configured at cart level.

Show child attributes

limits.type

enum<string>

The types of coupons that limit their usage. ORDER is applicable to PRODUCT and BUYGET coupon types only.

Available options:

SITE_WIDE,

PER_USER,

ORDER

Example:

"SITE_WIDE"

limits.quantity

integer

The number of times a coupon can be applied. If not specified, PRODUCT and BUYGET type coupons can be applied as many times as possible.

Example:

30

termsAndConditions

object[]

Terms and conditions for the promotion

Promotion terms and conditions

Show child attributes

termsAndConditions.name

string

Terms and conditions name

Example:

"Terms Applied"

termsAndConditions.description

string

Terms and conditions description

Example:

"Items can't be exchanged"

promotionMessages

object[]

Message description for the promotion

Message description for the promotion

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

string[]

The types of web pages where the message is displayed.

Page type

Example:

["PDP", "Cart"]

promotionMessages.locales

string[]

The locales in which the promotion message is displayed. Locale is a set of language or country-based preferences for user interface.

Locale

Example:

["en-CA", "fr-CA"]

proximityMessages

object

Show child attributes

proximityMessages.threshold

integer

The proximity threshold value. You muse use a value greater than or equal to 0.

Required range: x >= 0

Example:

1

proximityMessages.localizedMessages

object[]

Show child attributes

proximityMessages.localizedMessages.locales

string[]

The intended language or target region for the message.

proximityMessages.localizedMessages.message

string

The localized message for the specified locales.

Example:

"Buy some more to get the discount!"

shipmentMethodIds

string[]

Required for Shipping type promotion to provide eligible shipment methods.

Shipping method ID. This ID is used to evaluate cart promotion.

eligiblePriceLists

integer[]

Price list IDs to be considered for this promotion.

The price list ID.

additionalAttributes

object[]

Merchant-specified attributes associated with the coupon.

Merchant-specified attributes associated with the coupon.

Show child attributes

additionalAttributes.name

string

required

Merchant-specified attribute name associated with the coupon.

Example:

"eventName"

additionalAttributes.values

required

Merchant-specified attribute value associated with the coupon.

Example:

"Store sale"

note

string

A brief note or description of the coupon.

Example:

"Independence day sale!"

level

integer

The order in which the coupons must be executed.

Required range: 0 <= x <= 5

Example:

3

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

isStackable

boolean

• true: Allows the coupon to be stacked so it can be applied with other coupons.
• false: Disables coupon stacking.

Example:

false

isAlwaysApplied

boolean

Set true to always apply the coupon, even on non-stackable promotions, or false to apply coupon based on configured conditions.

Example:

false

singleMultiUse

enum<string>

Determines whether the coupon is valid for single use or for multiple uses. The options are:

• SINGLE_USE: The coupon can be used only once.
• MULTI_USE: The coupon can be used multiple times.

Available options:

SINGLE_USE,

MULTI_USE

Example:

"MULTI_USE"

Response

201

application/json

Created

The coupon details.

id

string

required

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

Example:

"6380e7ecb419a30009865fad"

name

string

required

The name of the coupon.

Example:

"Christmas 2022 coupons"

status

enum<string>

required

The status of the coupon.

Available options:

ACTIVE,

SCHEDULED,

DISABLED,

EXPIRED

Example:

"SCHEDULED"

startAt

string

required

The timestamp in UTC format indicating when the coupon becomes valid.

Example:

"2022-08-24T14:15:22.000Z"

endAt

string

required

The timestamp in UTC format indicating when the coupon expires and is no longer valid.

Example:

"2019-08-25T14:15:22.000Z"

type

enum<string>

required

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

• PRODUCT: A SKU coupon promotion. Applies a discount to SKUs based on the value specified in the discount object of the request body.
• CART: A cart coupon 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 coupon promotion. Provides discounts on items based on the quantity requirement set in the promotion.
• SHIPPING: A shipping coupon promotion. Provides discounts on the shipping cost.
• BUYGET: A BuyGet coupon promotion. Specifies the Buy conditions and corresponding Get discounts.
• SPEND_GET: A SpendGet coupon 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

Example:

"PRODUCT"

createdAt

string

required

The timestamp in UTC format indicating when the coupon was created.

Example:

"2019-08-20T14:15:22.000Z"

updatedAt

string

required

The timestamp in UTC format indicating when the coupon was last updated.

Example:

"2019-08-20T14:15:22.000Z"

couponCodesCount

integer

The total number of coupon codes.

Example:

100

level

integer

Coupon execution order

Required range: 0 <= x <= 5

Example:

3

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

isStackable

boolean

• true: Allows the coupon to be stacked so it can be applied with other coupons.
• false: Disables coupon stacking.

Example:

false

isAlwaysApplied

boolean

Set true to always apply the promotion, even on non-stackable promotions, or false to apply promotion based on configured conditions.

Example:

false

singleMultiUse

enum<string>

Determines whether the coupon is valid for single use or for multiple uses. The options are:

• SINGLE_USE: The coupon can be used only once.
• MULTI_USE: The coupon can be used multiple times.

Available options:

MULTI_USE,

SINGLE_USE

Example:

"MULTI_USE"

couponCodes

string[]

An array containing available coupon codes.

Example:

["SUMMER1000001"]

promotionMessages

object[]

Message description for the promotion

Message description for the promotion

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

string[]

The types of web pages where the message is displayed.

Page type

Example:

["PDP", "Cart"]

promotionMessages.locales

string[]

The locales in which the promotion message is displayed. Locale is a set of language or country-based preferences for user interface.

Locale

Example:

["en-CA", "fr-CA"]

additionalAttributes

object[]

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

Details of additional attributes.

Show child attributes

additionalAttributes.name

string

required

The attribute name.

Example:

"type"

additionalAttributes.values

required

The attribute value or values corresponding to the name.

Example:

"Birthday"

additionalAttributes.attributeId

number

A unique identifier of the attribute, for external use.

Example:

100000