Get a specific promotion

Retrieves a specific promotion using the corresponding promotionId.

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.

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.

Path Parameters

promotionId

string

required

The promotion ID generated when using the create promotion endpoint.

Response

200 - application/json

Promotion record detail

details

object[]

required

Promotion setup details

Show child attributes

details.conditions

object[]

Conditions list for the promotion to be applied

Show child attributes

details.conditions.conditions

object[]

required

Conditions for the promotion to apply on specific targets

Show child attributes

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

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

details.conditions.conditions.values

required

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

details.conditions.operator

enum<string>

required

Operator for condition within each object of the conditions array

Available options:

AND,

OR

details.conditions.excludeOperator

enum<string>

default:

AND

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

string | null

Promotion condition ID

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

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

details.discounts

object[]

An array containing discount details.

Show child attributes

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

enum<string>

required

Discount type

Available options:

PERCENTAGE_OFF,

AMOUNT_OFF,

FIXED

details.discounts.discountId

string

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

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

Should be null for SKU and CART

details.targetProducts

object[]

A list of target products for applying the discount.

Show child attributes

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

details.targetProducts.type

enum<string>

required

The target type for the promotion.

Available options:

SKU,

CATEGORY,

ATTRIBUTE,

PRICE_TYPE,

COLLECTION,

PREVIOUS_DISCOUNTS

details.targetProducts.values

required

The values corresponding to the selection type.

details.targetProducts.discountId

string

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

endAt

string

required

Promotion end time

id

string

required

The promotion ID generated when using the create promotion endpoint.

name

string

required

The name of the promotion.

startAt

string

required

Promotion start time

status

enum<string>

default:

SCHEDULED

required

Promotion status

Available options:

ACTIVE,

SCHEDULED,

DISABLED,

EXPIRED

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

additionalAttributes

object[]

Merchant-specified attributes associated with the promotion.

Show child attributes

additionalAttributes.name

string

required

Merchant-specified attribute name associated with the promotion.

additionalAttributes.values

required

Merchant-specified attribute value associated with the promotion.

buyOperator

enum<string>

default:

OR

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

Available options:

AND,

OR

createdAt

string

Record's creation time

eligiblePriceLists

integer[]

Price list IDs to be considered for this promotion.

isAlwaysApplied

boolean

A flag indicating whether the promotion is always applied. Set to true if the promotion is always applied, even in non-stackable scenarios, and false if the promotion is applied based on configured conditions.

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.

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

limits

object[]

Restrictions or conditions that apply to the use of a promotion

Show child attributes

limits.quantity

integer

Number of times a promotion can be applied in the same cart.

limits.type

enum<string>

Promotion limit type

Available options:

ORDER

note

string

Promotion note or description

promotionMessages

object[]

Message description for the promotion

Show child attributes

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.

promotionMessages.message

string

Message description

promotionMessages.pages

string[]

The types of web pages where the message is displayed.

promotionMessages.title

string

Message name

proximityMessages

object

Show child attributes

proximityMessages.localizedMessages

object[]

Show child attributes

proximityMessages.localizedMessages.locales

string[]

proximityMessages.localizedMessages.message

string

The localized message for the specified locales.

proximityMessages.threshold

integer

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

Required range: x > 0

shipmentMethodIds

string[]

Required for Shipping type promotion to provide eligible shipment methods.

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

termsAndConditions

object[]

Terms and conditions for the promotion

Show child attributes

termsAndConditions.description

string

Terms and conditions description

termsAndConditions.name

string

Terms and conditions name

updatedAt

string

Record's last updated time