Skip to content

Get a promotion by code

GET
/stores/{storeRef}/promotions/code/{code}
curl --request GET \
--url 'https://apibase.ecomweb.app/api/v1/stores/example/promotions/code/example?status=DRAFT&mode=DISCOUNT_CODE&type=PRODUCT_DISCOUNT&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' \
--header 'x-api-key: <x-api-key>'

Returns the promotion with this exact discount code. Codes are stored upper-case, so send the code in upper-case. The optional status, mode and type query parameters must also match, otherwise the promotion counts as not found.

Required scopes: read:promotions

code
required
string

The discount code, in upper-case.

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.

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.

Media typeapplication/json
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

Example

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

The resource does not exist in this store.

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