Search for promotions

Use this endpont to search for promotions using filter conditions.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-site-context

string

required

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.

Body

application/json

A sample request to search for promotions or coupons.

offset

number

The number of records to skip before returning records. For example, when offset is 20 and limit is 10, this endpoint returns records from 21 to 30.

Required range: x > 0

limit

number

default:

10

The maximum number of records per page.

Required range: 1 < x < 100

sort

enum<string>

The criteria to sort the results. Use the format {sort order}{field name}, where - refers to a descending order and + refers to an ascending order.

Available options:

+updatedAt,

+title,

+startDate,

+endDate,

+level,

-updatedAt,

-title,

-startDate,

-endDate,

-level

filters

object[]

Show child attributes

filters.field

string

required

Represents the field name or title. If you're searching for Black Friday promotions, this is the title of the promotion.

Required string length: 3 - 120

filters.value

required

Represents the value or values corresponding to the field. Use Black Friday as value to search for Black Friday promotions.

Required string length: 1 - 120

filters.operator

enum<string>

required

The type of search operation. You can use multiple values separated by commas for the IN operation. However, you can use only a single value for the EQUALS, GREATER_THAN_OR_EQUAL_TO, and LESS_THAN operations.

Available options:

EQUAL,

GREATER_THAN_OR_EQUAL_TO,

LESS_THAN,

IN

Response

200

application/json

OK

The pagination data.

query

object

Show child attributes

query.limit

number

default:

10

The maximum number of records per page.

query.offset

number

default:

0

The number of records to skip before returning records. For example, when offset is 20 and limit is 10, this endpoint returns records from 21 to 30.

query.count

number

The total number of records.

data

object[]

The promotion details.

Show child attributes

data._id

string

A 24-character system-generated promotion ID.

data.promoId

number

A unique identifier of the promotion, for external use.

data.promoCodes

string[]

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.

data.promoCount

number

The number of coupon codes associated with a coupon. This value is always 0 for promotions.

data.state

enum<string>

The status of the promotion. <br />1. ACTIVE indicates the promotion is live and available. <br />2. SCHEDULED indicates the promotion is set up and is scheduled to be active in a future date. <br />3. DISABLED indicates the promotion is turned off and can be re-enabled at a later time if required. <br />4. EXPIRED indicates the promotion is no longer valid.

Available options:

ACTIVE,

SCHEDULED,

DISABLED,

EXPIRED

data.isImplicit

boolean

A flag indicating whether an offer is applied automatically. Set it to true for promotions, which should be applied automatically and false for coupons, which must be applied explicitly.

data.title

string

The name of the promotion.

data.startDate

string

The start time of the promotion, in UTC format.

data.endDate

string

The end time of the promotion, in UTC format.

data.isExclusive

boolean

A flag indicating whether a coupon can be stacked with an existing promotion. Set it to true to prevent the coupon from being applied to items that already have promotions and false to allow coupon to be applied with existing promotions.

data.eligiblePriceList

number[]

The price lists to be considered for the given promotion.

data.level

integer

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.

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

Available options:

STACKABLE,

EXCLUSIVE,

TYPE_EXCLUSIVE,

UNIVERSAL

data.updatedAt

string

The time when the promotion was last updated, in UTC format.