Skip to content

Queue a deployment's build

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

Checks that the source was uploaded and that its size matches the size declared when the deployment started, then queues the build. It answers 202 with the deployment, whose status follows the build. Calling it again for a deployment that is no longer waiting for its upload returns the deployment unchanged. Returns a 409 while the source is not uploaded. 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
status
required

Where the deployment is in its life. uploading: waiting for the source to be uploaded. queued and building: the build is waiting or running. built: built and ready to run. running: a preview or production runs it. stopped: built but not running. failed: the build failed; see error.

string
Allowed values: uploading queued building built running stopped failed
error
required

Why the build failed, or null.

string
nullable
created_at
required

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

string format: date-time
build_started_at
required

When the build started, as an ISO 8601 timestamp, or null.

string format: date-time
nullable
build_finished_at
required

When the build ended, as an ISO 8601 timestamp, or null while it has not ended.

string format: date-time
nullable
expires_at
required

When the deployment’s preview stops running, as an ISO 8601 timestamp, or null.

string format: date-time
nullable
preview_url
required

The address of the running preview, or null when none is running.

string
nullable
store_theme_id
required

ID of the theme the build is for, or null.

string
nullable
live

Whether the store’s storefront serves this deployment. Only in the list.

boolean
store_theme

The theme the build is for. Only in the list; null when the theme no longer exists.

object
id
required

Theme ID.

string
name
required

Theme name.

string
id
required

Deployment ID, such as d_.... Use it in the other deployment routes.

string
kind
required

The kind of deployment. Deployments created through the API are preview; promoting one makes the store serve it.

string

Example

{
"status": "uploading"
}

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