Search for promotions

Authentication v1

Identity APIs
User
Address
Auth

User Self Service APIs

Introduction
User Self Service APIs
Authentication APIs

Experiences v2 (XM v2)

XM
Pages
Global Components
Menu

Experiences v1 (XM v1)

XM
Pages
Global Components
Menu

Product Catalog

Product Catalog
Category
Product
Attributes
Bulk Import

Orders v2 (OMS v2)

Order Management System
Order
Order Attribute
Developer Guide
Order Return
Payment Status
Package Tracking
Cross Border
Order Cancellation
Appeasement
Allocation
Configuration
Fraud Configuration
Target Configuration
Location
Location Attribute
Inventory Network
Inventory
Inventory Counter
Inventory Bulk Operation
Inventory Attribute
Inventory Upload Log
Shipment
Shipping Method
Webhook
Notification
Export
Invoice
Fraud
Backorder Preorder Reservation
List

Orders v1 (OMS v1)

Order Management System
Cart
Bill To
Ship To
Wishlist
Cart Decoupled
Warehouse
Inventory
Attributes
List
Tax/Address Validate
Shipping
Payments
Order

Offers v2

Offers
Developer Guide
Promotion
Price Kind
Dynamic Pricing Engine
Segment
Coupon
Coupon Codes
Product
Price List
Attributes
Item
Price Guard
Global Exclusion
Upload Price CSV
Pricing
Redemption
Exports

Offers v1

Offers
Login API
Promotions
Pricing

Subscriptions (SMT API)

Subscriptions API
Cancellation Reasons
Subscription Discounts
Subscriptions
Subscribers
Orders

Loyalty (Member)

Member APIs
Inquire
Discounts
Redeem
Earn
Members

Dropship

Dropship API
Shipments
Products
Invoices
Connections
Inventory
Developer Guide
Returns
Orders

Cart API

Cart
Order Draft
Attribute
Adjustments
Shipping
Cart

Checkout API

Checkout
Checkout

Customer

Core Concepts
Customer Service
Organization
User Party
Organization Group Addresses
User Internal Party
Organization Contracts
Party
Party Contracts
Contracts
User
Search
User Trait
Organization Users
Address
User Address
Trait
Party Address
Party Trait
Organization Group Users
Internal Party
Contract Pricelist
Internal Parties Party
Account
Party Account
Organization Addresses
Organization Groups
Individual Addresses
Users Organization
Individual

POST

api-offers

promo

Authorizations

Authorization

string

headerrequired

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[]

Response

200 - application/json

The pagination data.

query

object

data

object[]

The promotion details.

data._id

string

A 24-character system-generated promotion ID.

A unique identifier of the promotion, for external use.

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.

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.

Was this page helpful?

Overview Stop a promotion