Skip to content

Promote a deployment

POST
/stores/{storeRef}/hosting/deployments/{id}/promote
curl --request POST \
--url https://apibase.ecomweb.app/api/v1/stores/example/hosting/deployments/example/promote \
--header 'x-api-key: <x-api-key>'

Makes the store’s storefront serve this deployment, and publishes the deployment’s theme with this build as its version in use. Promoting an earlier deployment is how you roll back. It answers 202 while the rollout starts; the previous deployment keeps serving until the new one is ready. Only a deployment that has finished building can be promoted. Needs a plan that includes Hosting.

Required scopes: deploy:storefront

id
required
string

The deployment ID.

storeRef
required
string

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

Media typeapplication/json
object
deployment_id
required

The deployment the store’s storefront serves, or null when the shared storefront does.

string
nullable
state
required

none: the shared storefront serves the store. rolling_out: a deployment is being put live and the previous one keeps serving. running: it is serving. degraded: it has a problem.

string
Allowed values: none rolling_out running degraded
rollout_error
required

Why the last rollout failed, or null. The store keeps serving what it served before.

string
nullable
urls
required

The addresses the storefront answers on.

Array<string>

Example

{
"state": "none"
}

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