Skip to content

Add a theme version

POST
/stores/{storeRef}/themes/{id}/versions
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

id
required
string

The theme ID.

storeRef
required
string

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

Media typeapplication/json
object
kind
required

link adds a link to your own site. release adds a release of the theme’s catalog theme.

string
Allowed values: link release
url

The address of your site. Required for a link.

string
<= 2000 characters
allowed_origins

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.

Array<string>
version

The release version to add, for a release, such as 1.2.0. Defaults to the latest.

string
<= 30 characters
Media typeapplication/json
object
theme
required

The theme, now using the new version.

object
settings_values
required

The saved setting values, by setting ID.

object
key
additional properties
any
settings_schema
required

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).

Array<object>
object
key
additional properties
any
mode
required

theme: a catalog release. custom: your code, built by EcomWeb. headless: a link to your own site.

string
Allowed values: theme custom headless
current_version
required

The version the theme uses.

object
kind
required

release: a catalog release. build: a deployment of your code. link: your own site.

string
Allowed values: release build link
created_at
required

When the version was added, as an ISO 8601 timestamp.

string format: date-time
deployment_id

The deployment ID. Only for a build.

string
url

The site address. Only for a link.

string
release_version

The catalog release version. Only for a release.

string
id
required

Version ID.

string
label
required

A short name for the version, such as the release number.

string
latest_release
required

The newest catalog release on a newer major version than the theme’s, or null when there is none.

object
version
required

The release’s version.

string
preview
required

The preview of the build in use, or null when the theme does not use a build or is live.

object
state
required

off: not asked for in the last 24 hours. starting: asked for, not up yet. running: up.

string
Allowed values: off starting running
until
required

When the preview stops, as an ISO 8601 timestamp, or null when it is not running.

string format: date-time
nullable
url
required

The preview’s address.

string
thumbnail_url
required

The address of the theme’s screenshot, or null until one is taken.

string
nullable
created_at
required

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

string format: date-time
updated_at
required

When the theme was last updated, as an ISO 8601 timestamp.

string format: date-time
kind
required

Deprecated: use mode and current_version. hosted is a release, custom a build and external a link.

string
Allowed values: hosted custom external
deployed
required

Deprecated: use mode. Whether a build is in use.

boolean
current_deployment
required

Deprecated: use current_version. The build in use, or null.

object
created_at
required

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

string format: date-time
build_finished_at
required

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

string format: date-time
nullable
store_theme_id
required

The theme the build was deployed to, which differs from this theme for a copy.

string
nullable
id
required

Deployment ID.

string
source_version
required

Deprecated: use current_version. The catalog release version the theme comes from.

string
preview_url
required

Deprecated: use preview. The preview’s address, or null.

string
nullable
id
required

Theme ID.

string
name
required

Theme name.

string
is_published
required

Whether this is the live theme, the one shoppers see.

boolean
source_theme_id
required

ID of the catalog theme this theme comes from, such as default.

string
has_settings
required

Whether the version in use has settings to edit.

boolean
versions_count
required

How many versions the theme has.

number
version
required

The version that was added.

object
kind
required

release: a catalog release. build: a deployment of your code. link: your own site.

string
Allowed values: release build link
created_at
required

When the version was added, as an ISO 8601 timestamp.

string format: date-time
created_by
required

ID of the user who added it, or null.

string
nullable
unusable_reason

Why the version cannot be used. Only when usable is false.

string
Allowed values: build_failed build_in_progress build_pruned release_withdrawn hosting_not_in_plan
release

The catalog release. Only for a release.

object
theme_id
required

The catalog theme ID.

string
version
required

The release version.

string
build

The build. Only for a build.

object
error
required

Why the build failed, or null.

string
nullable
build_finished_at
required

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

string format: date-time
nullable
build_seconds
required

How long the build took, in seconds, or null.

number
nullable
deployment_id
required

Deployment ID.

string
status
required

The deployment’s status.

string
artifact
required

source or prebuilt: what was uploaded.

string
link

The linked site. Only for a link.

object
allowed_origins
required

Extra origins the site is served from.

Array<string>
url
required

The site address.

string
status

Deprecated: use build.status. Only for a build.

string
error

Deprecated: use build.error. Only for a build.

string
nullable
restorable

Deprecated: use usable. Only for a build.

boolean
id
required

Version ID.

string
label
required

A short name for the version.

string
current
required

Whether the theme uses this version.

boolean
serving
required

Whether the store’s storefront serves this version now.

boolean
usable
required

Whether the version can be used now. See unusable_reason when it cannot.

boolean

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.

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