Skip to content

Start a deployment

POST
/stores/{storeRef}/hosting/deployments
curl --request POST \
--url https://apibase.ecomweb.app/api/v1/stores/example/hosting/deployments \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '{ "sha256": "example", "bytes": 1, "artifact": "source", "store_theme_id": "example", "settings_schema": [ {} ], "allow_live": true, "draft": true }'

Declares a new build of a theme’s code and returns a pre-signed upload_url. Upload the source archive (a gzipped tar file whose size and SHA-256 you declared here) to it with an HTTP PUT, then call the build route. Name the theme with store_theme_id, or leave it out to use the theme that runs code. Deploying to the live theme is refused with a 409 THEME_IS_LIVE unless you set allow_live to true or deploy to a draft with draft. Needs a plan that includes Hosting. A key with only the deploy:storefront scope can call this route.

Required scopes: deploy:storefront

storeRef
required
string

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

Media typeapplication/json
object
sha256
required

SHA-256 of the source archive, as 64 lower case hexadecimal characters.

string
/^[a-f0-9]{64}$/
bytes
required

Size of the archive in bytes. Source archives are limited to 50 MB and prebuilt output to 250 MB.

number
>= 1
artifact

source (default): EcomWeb builds the uploaded source. prebuilt: you upload the output of a Next.js standalone build.

string
Allowed values: source prebuilt
store_theme_id

ID of the theme this build is for. Leave it out to deploy to the theme that runs code.

string
/^\d{1,18}$/
settings_schema

The theme’s settings schema, exported from its code: a list of groups, each with a name and its settings. It replaces the schema of the theme’s form once the build is in use.

Array<object>
object
key
additional properties
any
allow_live

Only matters when the theme is the live one. true: the build goes live as soon as it is built. false: naming the live theme is refused with a 409 THEME_IS_LIVE, and leaving out store_theme_id deploys to a draft instead. Left out: the build is accepted but is kept in the theme’s versions without going live.

boolean
draft

Deploy to a draft copy of the live theme instead of the live theme. EcomWeb creates the draft the first time. Leave out store_theme_id: sending both is refused. The build is never live.

boolean
Media typeapplication/json
object
waits_for_link

Present and true when the theme uses a link to your own site: the build is kept in the theme’s versions and is not served until you use it.

number
id
required

Deployment ID.

string
upload_url
required

A pre-signed URL. Upload the source file to it with an HTTP PUT.

string
expires_in
required

How many seconds upload_url stays valid.

number

Example

{
"waits_for_link": true
}

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