Skip to content

Create a promotion

POST
/stores/{storeRef}/promotions
curl --request POST \
--url https://apibase.ecomweb.app/api/v1/stores/example/promotions \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '{ "name": "20% off t-shirts", "mode": "DISCOUNT_CODE", "code": "SALE20", "description": "20% off every t-shirt", "start_at": "2024-01-01T00:00:00Z", "end_at": "2024-12-31T23:59:59Z", "type": "PRODUCT_DISCOUNT", "condition_type": "PRODUCT", "target_ids": [ "1", "2", "3" ], "min_amount": 100000, "min_quantity": 2, "discount_method": "PERCENTAGE", "discount_value": 20, "max_discount_amount": 100000, "fixed_price": 50000, "gift_product_ids": [ "10", "11" ], "gift_quantity": 1, "usage_limit": 100, "usage_limit_per_user": 1, "checkout_suggestion_enabled": false }'

Creates a discount code or an automatic promotion. The promotion is ACTIVE as soon as it is created, whatever the dates, and its terms cannot be changed afterwards; to change them, disable it and create a new one. A discount code must not already belong to another active promotion, otherwise the call fails with 409 PROMOTION_CODE_EXISTS. When condition_type is PRODUCT, every ID in target_ids must be a product of the store.

Required scopes: write:promotions

storeRef
required
string

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

Media typeapplication/json
object
name
required

Promotion name.

string

Example

20% off t-shirts
mode
required

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

string
Allowed values: DISCOUNT_CODE AUTOMATIC

Example

DISCOUNT_CODE
code

Discount code. Set it when mode is DISCOUNT_CODE; shoppers cannot redeem the promotion without one. It is stored upper-case and matched without regard to case, and must not already belong to an active promotion.

string

Example

SALE20
description

Description.

string

Example

20% off every t-shirt
start_at
required

When the promotion starts, as an ISO 8601 timestamp.

string

Example

2024-01-01T00:00:00Z
end_at

When the promotion ends, as an ISO 8601 timestamp. Omit for no end date.

string

Example

2024-12-31T23:59:59Z
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

Example

PRODUCT_DISCOUNT
condition_type
required

What target_ids refers to: PRODUCT, VARIANT or NONE.

string
Allowed values: PRODUCT VARIANT NONE

Example

PRODUCT
target_ids
required

IDs of the products or variants the promotion applies to, as strings. Required, with at least one ID, unless condition_type is NONE.

Array<string>

Example

[
"1",
"2",
"3"
]
min_amount

Minimum order amount the promotion needs.

number

Example

100000
min_quantity

Minimum number of items the promotion needs.

number
>= 1

Example

2
discount_method

PERCENTAGE or FIXED_AMOUNT.

string
Allowed values: PERCENTAGE FIXED_AMOUNT

Example

PERCENTAGE
discount_value

The discount: a percentage or an amount, depending on discount_method.

number

Example

20
max_discount_amount

Cap on the discount for a percentage promotion.

number

Example

100000
fixed_price

Fixed price for a FIXED_PRICE promotion.

number

Example

50000
gift_product_ids

IDs of the gift products, as strings. Used by GIFT promotions.

Array<string>

Example

[
"10",
"11"
]
gift_quantity

Quantity of gift given.

number
>= 1

Example

1
usage_limit

Total number of times the promotion can be used. Omit for unlimited.

number
>= 1

Example

100
usage_limit_per_user

Number of times one customer can use the promotion. Omit for unlimited.

number
>= 1

Example

1
checkout_suggestion_enabled

Bật/tắt hiển thị khuyến mãi trong danh sách gợi ý ở trang checkout

boolean

Example

false
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 request conflicts with the resource’s current state.

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