Skip to content

List promotions

GET
/stores/{storeRef}/promotions
curl --request GET \
--url 'https://apibase.ecomweb.app/api/v1/stores/example/promotions?status=DRAFT&mode=DISCOUNT_CODE&type=PRODUCT_DISCOUNT&code=SALE20&search=summer&start_at_from=2024-01-01T00%3A00%3A00Z&start_at_to=2024-12-31T23%3A59%3A59Z&end_at_from=2024-01-01T00%3A00%3A00Z&end_at_to=2024-12-31T23%3A59%3A59Z&limit=20&offset=0&sort_by=created_at&sort_order=asc&filters=%5B%7B%22field%22%3A%22status%22%2C%22operator%22%3A%22is_not%22%2C%22values%22%3A%5B%22EXPIRED%22%5D%7D%5D' \
--header 'x-api-key: <x-api-key>'

Returns the store’s promotions, newest first by default, in pages of up to 100. Filter by status, mode, type, code, a search term or start and end dates, or pass filters for several values per field. Deleted promotions are not returned.

Required scopes: read:promotions

storeRef
required
string

The store’s ref, as returned by GET /stores.

status
string
Allowed values: DRAFT ACTIVE EXPIRED DISABLED

Promotion status: DRAFT, ACTIVE, EXPIRED or DISABLED.

mode
string
Allowed values: DISCOUNT_CODE AUTOMATIC

Filter by mode.

type
string
Allowed values: PRODUCT_DISCOUNT CART_DISCOUNT FREE_SHIPPING FIXED_PRICE GIFT

What the promotion does: PRODUCT_DISCOUNT, CART_DISCOUNT, FREE_SHIPPING, FIXED_PRICE or GIFT.

code
string

Example

SALE20

Filter by exact discount code.

search
string

Example

summer

Search promotion names and descriptions.

start_at_from
string

Example

2024-01-01T00:00:00Z

Only promotions that start on or after this ISO 8601 timestamp.

start_at_to
string

Example

2024-12-31T23:59:59Z

Only promotions that start on or before this ISO 8601 timestamp.

end_at_from
string

Example

2024-01-01T00:00:00Z

Only promotions that end on or after this ISO 8601 timestamp. Promotions without an end date are always included.

end_at_to
string

Example

2024-12-31T23:59:59Z

Only promotions that end on or before this ISO 8601 timestamp. Promotions without an end date are always included.

limit
number
default: 20 >= 1 <= 100

Example

20

Maximum number of promotions to return.

offset
number
0

Example

0

Number of promotions to skip.

sort_by
string
default: created_at

Example

created_at

Field to sort by: id, name, status, type, start_at, end_at, created_at or updated_at.

sort_order
string
default: desc
Allowed values: asc desc

Example

desc

Sort direction.

filters
string

Example

[{"field":"status","operator":"is_not","values":["EXPIRED"]}]

Admin list-view filters, a JSON array of {field, operator, values}. At most 10 clauses, at most 50 values each.

Media typeapplication/json
object
data
required
Array<object>
object
mode
required

DISCOUNT_CODE when shoppers enter a code, AUTOMATIC when it applies on its own.

string
Allowed values: DISCOUNT_CODE AUTOMATIC
code

The discount code, stored upper-case. Null for an automatic promotion.

string
nullable
description

Description, or null.

string
nullable
end_at

When the promotion ends, as an ISO 8601 timestamp. Null when it has no end date.

string
nullable
status
required

DRAFT, ACTIVE, EXPIRED or DISABLED. A new promotion is ACTIVE.

string
Allowed values: DRAFT ACTIVE EXPIRED DISABLED
type
required

What the promotion does: PRODUCT_DISCOUNT, CART_DISCOUNT, FREE_SHIPPING, FIXED_PRICE or GIFT.

string
Allowed values: PRODUCT_DISCOUNT CART_DISCOUNT FREE_SHIPPING FIXED_PRICE GIFT
condition_type
required

What target_ids refers to: PRODUCT, VARIANT or NONE.

string
Allowed values: PRODUCT VARIANT NONE
target_ids
required

IDs of the products or variants the promotion applies to, as strings. Empty when condition_type is NONE.

Array<string>
min_amount

Minimum order amount the promotion needs. Null when there is none.

number
nullable
min_quantity

Minimum number of items the promotion needs. Null when there is none.

number
nullable
discount_method

PERCENTAGE or FIXED_AMOUNT. Null for promotions without a discount value.

string
nullable
Allowed values: PERCENTAGE FIXED_AMOUNT
discount_value

The discount: a percentage or an amount, depending on discount_method. Null when not set.

number
nullable
max_discount_amount

Cap on the discount for a percentage promotion. Null when there is none.

number
nullable
fixed_price

Fixed price for a FIXED_PRICE promotion. Null for other types.

number
nullable
gift_product_ids
required

IDs of the gift products, as strings. Empty unless the type is GIFT.

Array<string>
gift_quantity

Quantity of gift given. Null for other types.

number
nullable
usage_limit

Total number of times the promotion can be used. Null means unlimited.

number
nullable
usage_limit_per_user

Number of times one customer can use the promotion. Null means unlimited.

number
nullable
checkout_suggestion_enabled

Whether the promotion is suggested to shoppers at checkout.

boolean
nullable
deleted_at

When the promotion was deleted. Always null on promotions you can read.

string
nullable
created_by

ID of the user who created the promotion, or null.

string
nullable
updated_by

ID of the user who last updated the promotion, or null.

string
nullable
id
required

Promotion ID.

number
name
required

Promotion name.

string
start_at
required

When the promotion starts, as an ISO 8601 timestamp.

string
created_at
required

When the promotion was created, as an ISO 8601 timestamp.

string
updated_at
required

When the promotion was last updated, as an ISO 8601 timestamp.

string
meta
required
object
total
required

Total number of items matching the request.

number
limit
required

Maximum number of items in this page.

number
offset
required

Number of items skipped before this page.

number
page
required

Current page number, starting at 1.

number
totalPages
required

Total number of pages.

number
hasNext
required

Whether a next page exists.

boolean
hasPrev
required

Whether a previous page exists.

boolean

Example

{
"data": [
{
"mode": "DISCOUNT_CODE",
"status": "DRAFT",
"type": "PRODUCT_DISCOUNT",
"condition_type": "PRODUCT",
"discount_method": "PERCENTAGE"
}
]
}

The request is malformed or failed validation.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}