Add a theme version
const url = 'https://apibase.ecomweb.app/api/v1/stores/example/themes/example/versions';const options = { method: 'POST', headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'}, body: '{"kind":"link","url":"example","allowed_origins":["example"],"version":"example"}'};
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/themes/example/versions \ --header 'Content-Type: application/json' \ --header 'x-api-key: <x-api-key>' \ --data '{ "kind": "link", "url": "example", "allowed_origins": [ "example" ], "version": "example" }'Adds a link to your own site (kind link, with url and optional allowed_origins) or a release of the theme’s catalog theme (kind release, with an optional version, the latest by default), and makes the theme use it. Builds are not added here: they come from deployments. A release must be on the same major version as the theme. Needs the write:settings scope.
Required scopes: write:settings
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The theme ID.
The store’s ref, as returned by GET /stores.
Request Bodyrequired
Section titled “Request Bodyrequired”object
link adds a link to your own site. release adds a release of the theme’s catalog theme.
The address of your site. Required for a link.
Extra origins the linked site is served from, for a link. The storefront accepts
requests from them while the link is in use. Each is checked and normalised, and at most
20 are allowed.
The release version to add, for a release, such as 1.2.0. Defaults to the latest.
Responses
Section titled “Responses”object
The theme, now using the new version.
object
The saved setting values, by setting ID.
object
The settings the version in use declares, as a list of groups. Each group has a name and
settings, a list of setting definitions (id, type, label, default and so on).
object
theme: a catalog release. custom: your code, built by EcomWeb. headless: a link to your own site.
The version the theme uses.
object
release: a catalog release. build: a deployment of your code. link: your own site.
When the version was added, as an ISO 8601 timestamp.
The deployment ID. Only for a build.
The site address. Only for a link.
The catalog release version. Only for a release.
Version ID.
A short name for the version, such as the release number.
The newest catalog release on a newer major version than the theme’s, or null when there is none.
object
The release’s version.
The preview of the build in use, or null when the theme does not use a build or is live.
object
off: not asked for in the last 24 hours. starting: asked for, not up yet. running: up.
When the preview stops, as an ISO 8601 timestamp, or null when it is not running.
The preview’s address.
The address of the theme’s screenshot, or null until one is taken.
When the theme was created, as an ISO 8601 timestamp.
When the theme was last updated, as an ISO 8601 timestamp.
Deprecated: use mode and current_version. hosted is a release, custom a build and external a link.
Deprecated: use mode. Whether a build is in use.
Deprecated: use current_version. The build in use, or null.
object
When the deployment was created, as an ISO 8601 timestamp.
When the build ended, as an ISO 8601 timestamp, or null.
The theme the build was deployed to, which differs from this theme for a copy.
Deployment ID.
Deprecated: use current_version. The catalog release version the theme comes from.
Deprecated: use preview. The preview’s address, or null.
Theme ID.
Theme name.
Whether this is the live theme, the one shoppers see.
ID of the catalog theme this theme comes from, such as default.
Whether the version in use has settings to edit.
How many versions the theme has.
The version that was added.
object
release: a catalog release. build: a deployment of your code. link: your own site.
When the version was added, as an ISO 8601 timestamp.
ID of the user who added it, or null.
Why the version cannot be used. Only when usable is false.
The catalog release. Only for a release.
object
The catalog theme ID.
The release version.
The build. Only for a build.
object
Why the build failed, or null.
When the build ended, as an ISO 8601 timestamp, or null.
How long the build took, in seconds, or null.
Deployment ID.
The deployment’s status.
source or prebuilt: what was uploaded.
The linked site. Only for a link.
object
Extra origins the site is served from.
The site address.
Deprecated: use build.status. Only for a build.
Deprecated: use build.error. Only for a build.
Deprecated: use usable. Only for a build.
Version ID.
A short name for the version.
Whether the theme uses this version.
Whether the store’s storefront serves this version now.
Whether the version can be used now. See unusable_reason when it cannot.
Example
{ "theme": { "mode": "theme", "current_version": { "kind": "release" }, "preview": { "state": "off" }, "kind": "hosted" }, "version": { "kind": "release", "unusable_reason": "build_failed" }}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"}