Start a deployment
const url = 'https://apibase.ecomweb.app/api/v1/stores/example/hosting/deployments';const options = { method: 'POST', headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'}, body: '{"sha256":"example","bytes":1,"artifact":"source","store_theme_id":"example","settings_schema":[{}],"allow_live":true,"draft":true}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}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
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The store’s ref, as returned by GET /stores.
Request Bodyrequired
Section titled “Request Bodyrequired”object
SHA-256 of the source archive, as 64 lower case hexadecimal characters.
Size of the archive in bytes. Source archives are limited to 50 MB and prebuilt output to 250 MB.
source (default): EcomWeb builds the uploaded source. prebuilt: you upload the output of a Next.js standalone build.
ID of the theme this build is for. Leave it out to deploy to the theme that runs code.
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.
object
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.
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.
Responses
Section titled “Responses”object
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.
Deployment ID.
A pre-signed URL. Upload the source file to it with an HTTP PUT.
How many seconds upload_url stays valid.
Example
{ "waits_for_link": true}The request is malformed or failed validation.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}The key is missing, invalid, revoked or expired.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
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.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}The resource does not exist in this store.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}The request conflicts with the resource’s current state.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}