Skip to content

Update a promotion's status

PUT
/stores/{storeRef}/promotions/{id}
curl --request PUT \
--url https://apibase.ecomweb.app/api/v1/stores/example/promotions/1 \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '{ "status": "DRAFT" }'

Pauses or resumes a promotion by setting status. A promotion’s terms are fixed once it is created, so sending any other field fails with 409 PROMOTION_LOCKED; create a new promotion instead. Resuming a promotion whose code now belongs to another active promotion fails with 409 PROMOTION_CODE_EXISTS.

Required scopes: write:promotions

id
required
integer

The promotion ID.

storeRef
required
string

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

Media typeapplication/json
object
status
required

The new status. Use DISABLED to pause a promotion and ACTIVE to resume it.

string
Allowed values: DRAFT ACTIVE EXPIRED DISABLED
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"
}

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