Partners

Themes

List a storefront's themes and change a theme's setting values, sections and blocks, app blocks included, and translate theme text through the Store API; changes to the live theme wait for the merchant's review, translations apply straight away.

These endpoints let an app or a Store Admin API token work on a storefront's themes the way the theme editor does: list the themes, read and change a theme's global setting values, read its section types and its pages' sections and blocks, add, change, move and remove sections and blocks, place an installed app's block, and read and undo the theme's history. Reads require read_storefront; changes require write_storefront. Every change is checked exactly as Store Admin checks a theme editor save of the page (sections allowed on the page, setting values, block types and limits, app block pages), then like a code save (the theme rules and a render of the page), and is one change in the theme's history with a change_id that Revert a theme change undoes. Errors name what to fix and the file in error.details.

No app or token changes the live theme directly. A write to the storefront's live theme is saved to the caller's own pending copy of it: made on the caller's first write from the live theme as shoppers see it, reused by every later write, and named in the response's review (id, theme_id of the copy, live_theme_id, tool_name, status awaiting_review). The caller is identified by its app for an app token (all of the app's tokens share one copy) and by the token for a Store Admin API token. Keep using the live theme's ID: once the copy exists, the same caller's reads of the live theme (settings, section types, templates, history) come from it, so every base_hash you read matches what your next write is checked against. The merchant is notified and reviews the changes in Store Admin or the mobile app (Online Store > Themes, Theme changes to review): each page before and after, the changed files and the changed setting values. Publishing applies them to the live theme at once as one change in its history, recorded under the app's or token's name, which the merchant can undo; discarding deletes the copy. A storefront has at most 3 pending copies at once (one per app, token or connected tool), so a first write beyond that is refused with THEME_REVIEW_LIMIT. Files and setting values that also changed on the live theme meanwhile are merged at publish; changes that cannot be merged refuse the publish (THEME_REVIEW_CONFLICT) and the merchant discards them or asks you to make them again. Writes to a theme that is not live are saved on it directly. The default theme cannot be changed, and an app or token cannot update the live theme from the Theme Store.

Every write takes the base_hash you read and refuses a stale one instead of overwriting: a template changed since you read it is THEME_CODE_FILE_CHANGED, settings changed since are THEME_SETTINGS_CHANGED. Read again, redo the change and send the new hash; each successful write returns the next base_hash. Section and block IDs come from Get a theme template; a new section's or block's ID is in the write's response.

Theme text is the merchant's own words in a theme (the text, textarea and richtext settings of sections and blocks on every page and global part, and of the theme's global settings such as announcement bars and footer text), translated per store language. List theme text requires read_storefront and read_translations; Set theme text translations requires write_storefront and write_translations. List theme text returns each field's key, source, translation and status (translated, outdated when the source changed since it was translated, or missing); Set theme text translations saves up to 100 rows {key, locale, value} and reports each row on its own. Keys follow sections and blocks when they move, go when they are removed, and follow setting renames by theme schema migrations. Texts that use the theme's own strings (@t: keys) are translated with the theme's locale files and are not listed; the password, coming soon and maintenance pages keep their own translation types. Translations are content, not theme files, so these two endpoints are not subject to the pending-copy rule: a translation applies to the theme named straight away, the live theme included, needs no review and is not a change in the theme's history. Shoppers see the translation in that language and the source text where there is none.

Endpoints#

List storefront themes

GET read_storefront

List a storefront's themes.

Returns the storefront's themes, most recently updated first: is_active marks the live theme, source is first_party (the default theme), marketplace (from the Theme Store) or uploaded. Pending copies waiting for the merchant's review are not listed. max_count is how many themes the storefront may hold.

Path parameters

Name Type Description
storefront_id required string

Storefront ID.

Example: 1b2f6a43-0c8e-4d2b-9a7e-3f5d8c1e6b20

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 INVALID_INPUT

    storefront_id is not a UUID.

Get theme settings

GET read_storefront

Read a theme's global settings and their values.

Returns each setting of the theme's config/settings_schema.json: id, type, label, group, default, options or range (min, max, step, unit), visible_if, and its current value (null: the default applies). Send base_hash back with Update theme settings.

Path parameters

Name Type Description
storefront_id required string

Storefront ID.

Example: 1b2f6a43-0c8e-4d2b-9a7e-3f5d8c1e6b20
theme_id required string

Theme ID from List storefront themes. For the live theme, keep using its ID after your first write: your reads and writes go to your pending copy.

Example: 5c0e9d1a-7b42-4f6e-9a38-2d7c1b9e4f60

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 INVALID_INPUT

    An ID in the path is not a UUID.
  • 404 THEME_SECTION_NOT_FOUND

    The theme is not one of this storefront's themes.
  • 403 THEME_REVIEW_OTHER_TOOL

    The theme is another app's or token's pending copy.
  • 400 THEME_SETTINGS_NO_SCHEMA

    The theme has no settings.

Update theme settings

PUT write_storefront

Change some of a theme's global setting values.

The values are merged onto the current ones and checked exactly as Store Admin's theme editor checks them; settings you leave out keep their value. The change is one entry in the theme's history (config/settings_data.json), undone with Revert a theme change. saved is false when nothing changed. A write to the storefront's live theme never reaches shoppers directly: it is saved to the caller's own pending copy of the live theme (made on its first write, as shoppers see the live theme, then reused), and the response carries review (id, theme_id of the copy, live_theme_id, tool_name, status awaiting_review). The caller is the app for an app token and the token itself for a Store Admin API token. The merchant reviews the changes in Store Admin or the mobile app and publishes them, as one change in the live theme's history that can be undone, or discards them; a publish whose changes cannot be combined with later changes to the live theme is refused. A write to a theme that is not live is saved on it directly and has no review.

Path parameters

Name Type Description
storefront_id required string

Storefront ID.

Example: 1b2f6a43-0c8e-4d2b-9a7e-3f5d8c1e6b20
theme_id required string

Theme ID from List storefront themes. For the live theme, keep using its ID after your first write: your reads and writes go to your pending copy.

Example: 5c0e9d1a-7b42-4f6e-9a38-2d7c1b9e4f60

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
values required object

Setting id → new value (1 to 200), as Get theme settings lists them; null puts a setting back to its default.

Example: {"hide_zero_decimals":true,"button_radius":null}
base_hash required string

base_hash from Get theme settings.

Example: 6f3a9c1e7b2d5408a3e6c9f1b4d7a02e
message string

Up to 500 characters, kept with the change in the theme's history. Default: a summary of the change.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 INVALID_INPUT

    An ID in the path is not a UUID, or a body field is missing or invalid (error.field names it).
  • 404 THEME_SECTION_NOT_FOUND

    The theme is not one of this storefront's themes.
  • 409 THEME_CODE_DEFAULT_THEME

    The default theme cannot be edited. Duplicate it in Store Admin and work on the copy.
  • 409 THEME_REVIEW_LIMIT

    This is your first write to the live theme, and the storefront already has 3 pending copies of other apps and tokens waiting for review. The merchant publishes or discards one first.
  • 409 THEME_REVIEW_OTHER_THEME

    Your pending copy of an earlier live theme is still waiting for review. The merchant publishes or discards it first.
  • 403 THEME_REVIEW_OTHER_TOOL

    The theme is another app's or token's pending copy.
  • 404 THEME_REVIEW_NOT_FOUND

    The theme is a pending copy whose review was already published or discarded.
  • 422 THEME_CODE_RENDER_FAILED

    With the change, a page could not be shown; nothing was saved. The message names the page and the error.
  • 409 THEME_SETTINGS_CHANGED

    The settings changed since you read them (base_hash). Read them again and redo the change.
  • 400 THEME_SETTINGS_NO_SCHEMA

    The theme has no settings.
  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).
  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

List section types

GET read_storefront

List a theme's section types and theme blocks with their schemas.

Schemas only, no code. Each section type in sections has its settings (id, type, label, default, options, range, visible_if), its block slot blocks (types with their settings, max, default blocks, accept_theme_blocks and the theme_blocks it takes, accept_app_blocks), its presets and the pages it may be placed on. theme_blocks lists the theme's own blocks, placed as theme:<name>.

Path parameters

Name Type Description
storefront_id required string

Storefront ID.

Example: 1b2f6a43-0c8e-4d2b-9a7e-3f5d8c1e6b20
theme_id required string

Theme ID from List storefront themes. For the live theme, keep using its ID after your first write: your reads and writes go to your pending copy.

Example: 5c0e9d1a-7b42-4f6e-9a38-2d7c1b9e4f60

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 INVALID_INPUT

    An ID in the path is not a UUID.
  • 404 THEME_SECTION_NOT_FOUND

    The theme is not one of this storefront's themes.
  • 403 THEME_REVIEW_OTHER_TOOL

    The theme is another app's or token's pending copy.

List theme history

GET read_storefront

List a theme's changes, newest first.

Each change has its change_id, source, tool_name (the app or token that made it), message, created_at and the files it wrote. Pass next as before for the next page.

Path parameters

Name Type Description
storefront_id required string

Storefront ID.

Example: 1b2f6a43-0c8e-4d2b-9a7e-3f5d8c1e6b20
theme_id required string

Theme ID from List storefront themes. For the live theme, keep using its ID after your first write: your reads and writes go to your pending copy.

Example: 5c0e9d1a-7b42-4f6e-9a38-2d7c1b9e4f60

Query parameters

Name Type Description
before string

next from the previous page (RFC 3339 time): changes older than it.
limit integer

Changes per page, up to 200.

Default: 50

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 INVALID_INPUT

    An ID in the path is not a UUID.
  • 404 THEME_SECTION_NOT_FOUND

    The theme is not one of this storefront's themes.
  • 403 THEME_REVIEW_OTHER_TOOL

    The theme is another app's or token's pending copy.

Revert a theme change

POST write_storefront

Undo one change in a theme's history.

Every file the change wrote (code, a template, config/settings_data.json for setting values) goes back to what it was before. For the live theme this undoes a change in your pending copy. The undo is itself a change in the history. A write to the storefront's live theme never reaches shoppers directly: it is saved to the caller's own pending copy of the live theme (made on its first write, as shoppers see the live theme, then reused), and the response carries review (id, theme_id of the copy, live_theme_id, tool_name, status awaiting_review). The caller is the app for an app token and the token itself for a Store Admin API token. The merchant reviews the changes in Store Admin or the mobile app and publishes them, as one change in the live theme's history that can be undone, or discards them; a publish whose changes cannot be combined with later changes to the live theme is refused. A write to a theme that is not live is saved on it directly and has no review.

Path parameters

Name Type Description
storefront_id required string

Storefront ID.

Example: 1b2f6a43-0c8e-4d2b-9a7e-3f5d8c1e6b20
theme_id required string

Theme ID from List storefront themes. For the live theme, keep using its ID after your first write: your reads and writes go to your pending copy.

Example: 5c0e9d1a-7b42-4f6e-9a38-2d7c1b9e4f60
change_id required string

change_id from a write or List theme history.

Example: c7f2e1b4-9a3d-4e60-8b17-3d5a2c0f9e81

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 INVALID_INPUT

    An ID in the path is not a UUID, or a body field is missing or invalid (error.field names it).
  • 404 THEME_SECTION_NOT_FOUND

    The theme is not one of this storefront's themes.
  • 409 THEME_CODE_DEFAULT_THEME

    The default theme cannot be edited. Duplicate it in Store Admin and work on the copy.
  • 409 THEME_REVIEW_LIMIT

    This is your first write to the live theme, and the storefront already has 3 pending copies of other apps and tokens waiting for review. The merchant publishes or discards one first.
  • 409 THEME_REVIEW_OTHER_THEME

    Your pending copy of an earlier live theme is still waiting for review. The merchant publishes or discards it first.
  • 403 THEME_REVIEW_OTHER_TOOL

    The theme is another app's or token's pending copy.
  • 404 THEME_REVIEW_NOT_FOUND

    The theme is a pending copy whose review was already published or discarded.
  • 422 THEME_CODE_RENDER_FAILED

    With the change, a page could not be shown; nothing was saved. The message names the page and the error.
  • 404 THEME_CODE_CHANGE_NOT_FOUND

    The theme has no change change_id.
  • 409 THEME_CODE_CHANGED_SINCE

    A file the change wrote changed again since. Revert the later change first.

List theme templates

GET read_storefront

List a theme's resource templates and their handles.

Returns the default template and the alternate templates of each resource that has templates, in this order: product, collection, category, brand, vendor, page, blog (blog posts) and blog_category; resource_type narrows it to one. Each template has page_type (what Get a theme template and the section and block endpoints take, such as product or product__summer), handle (what the resource's template_handle takes when you create or update a product, collection, category, brand, vendor, page, blog post or blog category: default_<resource_type> for the default template, such as default_vendor, otherwise the alternate's handle, such as summer), name, resource_type and is_default. Merchants add alternate templates in Store Admin's theme editor. Pages that are not a resource's template (home, cart, global parts such as header) are not listed.

Path parameters

Name Type Description
storefront_id required string

Storefront ID.

Example: 1b2f6a43-0c8e-4d2b-9a7e-3f5d8c1e6b20
theme_id required string

Theme ID from List storefront themes. For the live theme, keep using its ID after your first write: your reads and writes go to your pending copy.

Example: 5c0e9d1a-7b42-4f6e-9a38-2d7c1b9e4f60

Query parameters

Name Type Description
resource_type string

Only this resource's templates: product, collection, category, brand, vendor, page, blog or blog_category.

Example: product

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 INVALID_INPUT

    An ID in the path is not a UUID, or resource_type is not one of the resource types listed (error.field names it).
  • 400 THEME_TEMPLATE_THEME_INVALID

    The theme is not one of this storefront's themes.

Get a theme template

GET read_storefront

Read one template's sections and blocks.

sections lists each section's id, type, name, disabled, settings and blocks (blocks inside theme blocks nested under their parent). Send base_hash with every section and block change of this template. exists is false for a page with no template yet; Add a section creates it with base_hash "". List theme templates lists the page_type of each resource's templates.

Path parameters

Name Type Description
storefront_id required string

Storefront ID.

Example: 1b2f6a43-0c8e-4d2b-9a7e-3f5d8c1e6b20
theme_id required string

Theme ID from List storefront themes. For the live theme, keep using its ID after your first write: your reads and writes go to your pending copy.

Example: 5c0e9d1a-7b42-4f6e-9a38-2d7c1b9e4f60
page_type required string

The template: a page type such as home, product or collection, an alternate such as product__summer, or a global part such as header, footer or global_body_start. List theme templates gives each resource template's page_type.

Example: product

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 INVALID_INPUT

    An ID in the path is not a UUID.
  • 404 THEME_SECTION_NOT_FOUND

    The theme is not one of this storefront's themes.
  • 403 THEME_REVIEW_OTHER_TOOL

    The theme is another app's or token's pending copy.
  • 400 THEME_CODE_TEMPLATE_PAGE_UNKNOWN

    page_type is not a page, alternate or global part the storefront has.

Add a section

POST write_storefront

Add a section to a template.

Adds a section of type, from one of its presets or with its defaults (and default blocks), then applies settings. Checked like a theme editor save of the page (sections allowed on the page, setting values), then with the theme checks and a render of the page. Returns the new section_id. A write to the storefront's live theme never reaches shoppers directly: it is saved to the caller's own pending copy of the live theme (made on its first write, as shoppers see the live theme, then reused), and the response carries review (id, theme_id of the copy, live_theme_id, tool_name, status awaiting_review). The caller is the app for an app token and the token itself for a Store Admin API token. The merchant reviews the changes in Store Admin or the mobile app and publishes them, as one change in the live theme's history that can be undone, or discards them; a publish whose changes cannot be combined with later changes to the live theme is refused. A write to a theme that is not live is saved on it directly and has no review.

Path parameters

Name Type Description
storefront_id required string

Storefront ID.

Example: 1b2f6a43-0c8e-4d2b-9a7e-3f5d8c1e6b20
theme_id required string

Theme ID from List storefront themes. For the live theme, keep using its ID after your first write: your reads and writes go to your pending copy.

Example: 5c0e9d1a-7b42-4f6e-9a38-2d7c1b9e4f60
page_type required string

The template: a page type such as home, product or collection, an alternate such as product__summer, or a global part such as header, footer or global_body_start. List theme templates gives each resource template's page_type.

Example: product

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
base_hash required string|null

The template's base_hash from Get a theme template (null or "" when the template does not exist yet). A template changed since is refused with THEME_CODE_FILE_CHANGED instead of overwritten.

Example: 4b1f0c9e2a7d6538e1c4b9a07f2d3e6c58a1b4d7e09f3c2a6b5d8e1f40a7c3b9
type required string

A section type from List section types.

Example: featured-collection
preset string

A preset name of that type.
position integer

0-based position in the list. Default: the end.
settings object

Setting id → value, as List section types lists the type's settings; null puts a setting back to its default. Only the settings you send change. Up to 200; blocks is not a setting (use the block endpoints).
disabled boolean

true adds it hidden.
message string

Up to 500 characters, kept with the change in the theme's history. Default: a summary of the change.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 INVALID_INPUT

    An ID in the path is not a UUID, or a body field is missing or invalid (error.field names it).
  • 404 THEME_SECTION_NOT_FOUND

    The theme is not one of this storefront's themes.
  • 409 THEME_CODE_DEFAULT_THEME

    The default theme cannot be edited. Duplicate it in Store Admin and work on the copy.
  • 409 THEME_REVIEW_LIMIT

    This is your first write to the live theme, and the storefront already has 3 pending copies of other apps and tokens waiting for review. The merchant publishes or discards one first.
  • 409 THEME_REVIEW_OTHER_THEME

    Your pending copy of an earlier live theme is still waiting for review. The merchant publishes or discards it first.
  • 403 THEME_REVIEW_OTHER_TOOL

    The theme is another app's or token's pending copy.
  • 404 THEME_REVIEW_NOT_FOUND

    The theme is a pending copy whose review was already published or discarded.
  • 422 THEME_CODE_RENDER_FAILED

    With the change, a page could not be shown; nothing was saved. The message names the page and the error.
  • 400 THEME_CODE_TEMPLATE_PAGE_UNKNOWN

    page_type is not a page, alternate or global part the storefront has.
  • 409 THEME_CODE_FILE_CHANGED

    The template changed since you read it (base_hash). Read it again and redo the change.
  • 400 THEME_SETTING_REMOVED

    A setting in settings is not a setting of the section or block.
  • 404 THEME_SECTION_TYPE_UNKNOWN

    The theme has no section type type.
  • 404 THEME_SECTION_PRESET_NOT_FOUND

    The section type has no preset preset.
  • 400 THEME_TEMPLATE_POSITION_INVALID

    position is out of range; the message gives the highest position.
  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).
  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Update a section

PATCH write_storefront

Change a section's settings, or hide or show it.

Only the settings you send change. Checked like a theme editor save of the page. A write to the storefront's live theme never reaches shoppers directly: it is saved to the caller's own pending copy of the live theme (made on its first write, as shoppers see the live theme, then reused), and the response carries review (id, theme_id of the copy, live_theme_id, tool_name, status awaiting_review). The caller is the app for an app token and the token itself for a Store Admin API token. The merchant reviews the changes in Store Admin or the mobile app and publishes them, as one change in the live theme's history that can be undone, or discards them; a publish whose changes cannot be combined with later changes to the live theme is refused. A write to a theme that is not live is saved on it directly and has no review.

Path parameters

Name Type Description
storefront_id required string

Storefront ID.

Example: 1b2f6a43-0c8e-4d2b-9a7e-3f5d8c1e6b20
theme_id required string

Theme ID from List storefront themes. For the live theme, keep using its ID after your first write: your reads and writes go to your pending copy.

Example: 5c0e9d1a-7b42-4f6e-9a38-2d7c1b9e4f60
page_type required string

The template: a page type such as home, product or collection, an alternate such as product__summer, or a global part such as header, footer or global_body_start. List theme templates gives each resource template's page_type.

Example: product
section_id required string

Section ID from Get a theme template.

Example: f3b81c2e-6d4a-4e19-a7c5-9b0e2d4f6a17

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
base_hash required string|null

The template's base_hash from Get a theme template (null or "" when the template does not exist yet). A template changed since is refused with THEME_CODE_FILE_CHANGED instead of overwritten.

Example: 4b1f0c9e2a7d6538e1c4b9a07f2d3e6c58a1b4d7e09f3c2a6b5d8e1f40a7c3b9
settings object

Setting id → value, as List section types lists the type's settings; null puts a setting back to its default. Only the settings you send change. Up to 200; blocks is not a setting (use the block endpoints).

Example: {"show_vendor":true}
disabled boolean

true hides it on the page, false shows it.
message string

Up to 500 characters, kept with the change in the theme's history. Default: a summary of the change.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 INVALID_INPUT

    An ID in the path is not a UUID, or a body field is missing or invalid (error.field names it).
  • 404 THEME_SECTION_NOT_FOUND

    The theme is not one of this storefront's themes.
  • 409 THEME_CODE_DEFAULT_THEME

    The default theme cannot be edited. Duplicate it in Store Admin and work on the copy.
  • 409 THEME_REVIEW_LIMIT

    This is your first write to the live theme, and the storefront already has 3 pending copies of other apps and tokens waiting for review. The merchant publishes or discards one first.
  • 409 THEME_REVIEW_OTHER_THEME

    Your pending copy of an earlier live theme is still waiting for review. The merchant publishes or discards it first.
  • 403 THEME_REVIEW_OTHER_TOOL

    The theme is another app's or token's pending copy.
  • 404 THEME_REVIEW_NOT_FOUND

    The theme is a pending copy whose review was already published or discarded.
  • 422 THEME_CODE_RENDER_FAILED

    With the change, a page could not be shown; nothing was saved. The message names the page and the error.
  • 400 THEME_CODE_TEMPLATE_PAGE_UNKNOWN

    page_type is not a page, alternate or global part the storefront has.
  • 409 THEME_CODE_FILE_CHANGED

    The template changed since you read it (base_hash). Read it again and redo the change.
  • 400 THEME_SETTING_REMOVED

    A setting in settings is not a setting of the section or block.
  • 404 THEME_TEMPLATE_SECTION_NOT_FOUND

    The template has no section section_id. Read the template again.
  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).
  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Remove a section

DELETE write_storefront

Remove a section from a template.

base_hash and message are query parameters. A section the page requires is refused. A write to the storefront's live theme never reaches shoppers directly: it is saved to the caller's own pending copy of the live theme (made on its first write, as shoppers see the live theme, then reused), and the response carries review (id, theme_id of the copy, live_theme_id, tool_name, status awaiting_review). The caller is the app for an app token and the token itself for a Store Admin API token. The merchant reviews the changes in Store Admin or the mobile app and publishes them, as one change in the live theme's history that can be undone, or discards them; a publish whose changes cannot be combined with later changes to the live theme is refused. A write to a theme that is not live is saved on it directly and has no review.

Path parameters

Name Type Description
storefront_id required string

Storefront ID.

Example: 1b2f6a43-0c8e-4d2b-9a7e-3f5d8c1e6b20
theme_id required string

Theme ID from List storefront themes. For the live theme, keep using its ID after your first write: your reads and writes go to your pending copy.

Example: 5c0e9d1a-7b42-4f6e-9a38-2d7c1b9e4f60
page_type required string

The template: a page type such as home, product or collection, an alternate such as product__summer, or a global part such as header, footer or global_body_start. List theme templates gives each resource template's page_type.

Example: product
section_id required string

Section ID from Get a theme template.

Example: f3b81c2e-6d4a-4e19-a7c5-9b0e2d4f6a17

Query parameters

Name Type Description
base_hash required string

The template's base_hash from Get a theme template (null or "" when the template does not exist yet). A template changed since is refused with THEME_CODE_FILE_CHANGED instead of overwritten.

Example: 4b1f0c9e2a7d6538e1c4b9a07f2d3e6c58a1b4d7e09f3c2a6b5d8e1f40a7c3b9
message string

Up to 500 characters, kept with the change in the theme's history. Default: a summary of the change.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 INVALID_INPUT

    An ID in the path is not a UUID, or a body field is missing or invalid (error.field names it).
  • 404 THEME_SECTION_NOT_FOUND

    The theme is not one of this storefront's themes.
  • 409 THEME_CODE_DEFAULT_THEME

    The default theme cannot be edited. Duplicate it in Store Admin and work on the copy.
  • 409 THEME_REVIEW_LIMIT

    This is your first write to the live theme, and the storefront already has 3 pending copies of other apps and tokens waiting for review. The merchant publishes or discards one first.
  • 409 THEME_REVIEW_OTHER_THEME

    Your pending copy of an earlier live theme is still waiting for review. The merchant publishes or discards it first.
  • 403 THEME_REVIEW_OTHER_TOOL

    The theme is another app's or token's pending copy.
  • 404 THEME_REVIEW_NOT_FOUND

    The theme is a pending copy whose review was already published or discarded.
  • 422 THEME_CODE_RENDER_FAILED

    With the change, a page could not be shown; nothing was saved. The message names the page and the error.
  • 400 THEME_CODE_TEMPLATE_PAGE_UNKNOWN

    page_type is not a page, alternate or global part the storefront has.
  • 409 THEME_CODE_FILE_CHANGED

    The template changed since you read it (base_hash). Read it again and redo the change.
  • 400 THEME_SETTING_REMOVED

    A setting in settings is not a setting of the section or block.
  • 404 THEME_TEMPLATE_SECTION_NOT_FOUND

    The template has no section section_id. Read the template again.

Move a section

POST write_storefront

Move a section to another position in its template.

A write to the storefront's live theme never reaches shoppers directly: it is saved to the caller's own pending copy of the live theme (made on its first write, as shoppers see the live theme, then reused), and the response carries review (id, theme_id of the copy, live_theme_id, tool_name, status awaiting_review). The caller is the app for an app token and the token itself for a Store Admin API token. The merchant reviews the changes in Store Admin or the mobile app and publishes them, as one change in the live theme's history that can be undone, or discards them; a publish whose changes cannot be combined with later changes to the live theme is refused. A write to a theme that is not live is saved on it directly and has no review.

Path parameters

Name Type Description
storefront_id required string

Storefront ID.

Example: 1b2f6a43-0c8e-4d2b-9a7e-3f5d8c1e6b20
theme_id required string

Theme ID from List storefront themes. For the live theme, keep using its ID after your first write: your reads and writes go to your pending copy.

Example: 5c0e9d1a-7b42-4f6e-9a38-2d7c1b9e4f60
page_type required string

The template: a page type such as home, product or collection, an alternate such as product__summer, or a global part such as header, footer or global_body_start. List theme templates gives each resource template's page_type.

Example: product
section_id required string

Section ID from Get a theme template.

Example: f3b81c2e-6d4a-4e19-a7c5-9b0e2d4f6a17

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
base_hash required string|null

The template's base_hash from Get a theme template (null or "" when the template does not exist yet). A template changed since is refused with THEME_CODE_FILE_CHANGED instead of overwritten.

Example: 4b1f0c9e2a7d6538e1c4b9a07f2d3e6c58a1b4d7e09f3c2a6b5d8e1f40a7c3b9
position required integer

0-based position to move it to.

Example: 0
message string

Up to 500 characters, kept with the change in the theme's history. Default: a summary of the change.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 INVALID_INPUT

    An ID in the path is not a UUID, or a body field is missing or invalid (error.field names it).
  • 404 THEME_SECTION_NOT_FOUND

    The theme is not one of this storefront's themes.
  • 409 THEME_CODE_DEFAULT_THEME

    The default theme cannot be edited. Duplicate it in Store Admin and work on the copy.
  • 409 THEME_REVIEW_LIMIT

    This is your first write to the live theme, and the storefront already has 3 pending copies of other apps and tokens waiting for review. The merchant publishes or discards one first.
  • 409 THEME_REVIEW_OTHER_THEME

    Your pending copy of an earlier live theme is still waiting for review. The merchant publishes or discards it first.
  • 403 THEME_REVIEW_OTHER_TOOL

    The theme is another app's or token's pending copy.
  • 404 THEME_REVIEW_NOT_FOUND

    The theme is a pending copy whose review was already published or discarded.
  • 422 THEME_CODE_RENDER_FAILED

    With the change, a page could not be shown; nothing was saved. The message names the page and the error.
  • 400 THEME_CODE_TEMPLATE_PAGE_UNKNOWN

    page_type is not a page, alternate or global part the storefront has.
  • 409 THEME_CODE_FILE_CHANGED

    The template changed since you read it (base_hash). Read it again and redo the change.
  • 400 THEME_SETTING_REMOVED

    A setting in settings is not a setting of the section or block.
  • 404 THEME_TEMPLATE_SECTION_NOT_FOUND

    The template has no section section_id. Read the template again.
  • 400 THEME_TEMPLATE_POSITION_INVALID

    position is out of range; the message gives the highest position.
  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).
  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Add a block

POST write_storefront

Add a block to a section.

type is one of the section's block types or a theme block (theme:<name>) from List section types; with parent_block_id the block goes inside one of the section's theme blocks. The block type, the slot's maximum and the settings are checked before saving. Returns the new block_id. App blocks are placed with Place an app block. A write to the storefront's live theme never reaches shoppers directly: it is saved to the caller's own pending copy of the live theme (made on its first write, as shoppers see the live theme, then reused), and the response carries review (id, theme_id of the copy, live_theme_id, tool_name, status awaiting_review). The caller is the app for an app token and the token itself for a Store Admin API token. The merchant reviews the changes in Store Admin or the mobile app and publishes them, as one change in the live theme's history that can be undone, or discards them; a publish whose changes cannot be combined with later changes to the live theme is refused. A write to a theme that is not live is saved on it directly and has no review.

Path parameters

Name Type Description
storefront_id required string

Storefront ID.

Example: 1b2f6a43-0c8e-4d2b-9a7e-3f5d8c1e6b20
theme_id required string

Theme ID from List storefront themes. For the live theme, keep using its ID after your first write: your reads and writes go to your pending copy.

Example: 5c0e9d1a-7b42-4f6e-9a38-2d7c1b9e4f60
page_type required string

The template: a page type such as home, product or collection, an alternate such as product__summer, or a global part such as header, footer or global_body_start. List theme templates gives each resource template's page_type.

Example: product
section_id required string

Section ID from Get a theme template.

Example: f3b81c2e-6d4a-4e19-a7c5-9b0e2d4f6a17

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
base_hash required string|null

The template's base_hash from Get a theme template (null or "" when the template does not exist yet). A template changed since is refused with THEME_CODE_FILE_CHANGED instead of overwritten.

Example: 4b1f0c9e2a7d6538e1c4b9a07f2d3e6c58a1b4d7e09f3c2a6b5d8e1f40a7c3b9
type required string

A block type of the section, or theme:<name>.

Example: price
parent_block_id string

A theme block of the section to add the block inside.
position integer

0-based position in the list. Default: the end.
settings object

Setting id → value, as List section types lists the type's settings; null puts a setting back to its default. Only the settings you send change. Up to 200; blocks is not a setting (use the block endpoints).
disabled boolean

true hides it on the page, false shows it.
message string

Up to 500 characters, kept with the change in the theme's history. Default: a summary of the change.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 INVALID_INPUT

    An ID in the path is not a UUID, or a body field is missing or invalid (error.field names it).
  • 404 THEME_SECTION_NOT_FOUND

    The theme is not one of this storefront's themes.
  • 409 THEME_CODE_DEFAULT_THEME

    The default theme cannot be edited. Duplicate it in Store Admin and work on the copy.
  • 409 THEME_REVIEW_LIMIT

    This is your first write to the live theme, and the storefront already has 3 pending copies of other apps and tokens waiting for review. The merchant publishes or discards one first.
  • 409 THEME_REVIEW_OTHER_THEME

    Your pending copy of an earlier live theme is still waiting for review. The merchant publishes or discards it first.
  • 403 THEME_REVIEW_OTHER_TOOL

    The theme is another app's or token's pending copy.
  • 404 THEME_REVIEW_NOT_FOUND

    The theme is a pending copy whose review was already published or discarded.
  • 422 THEME_CODE_RENDER_FAILED

    With the change, a page could not be shown; nothing was saved. The message names the page and the error.
  • 400 THEME_CODE_TEMPLATE_PAGE_UNKNOWN

    page_type is not a page, alternate or global part the storefront has.
  • 409 THEME_CODE_FILE_CHANGED

    The template changed since you read it (base_hash). Read it again and redo the change.
  • 400 THEME_SETTING_REMOVED

    A setting in settings is not a setting of the section or block.
  • 404 THEME_TEMPLATE_SECTION_NOT_FOUND

    The template has no section section_id. Read the template again.
  • 404 THEME_TEMPLATE_BLOCK_NOT_FOUND

    The section has no block block_id (or parent_block_id). Read the template again.
  • 400 THEME_TEMPLATE_POSITION_INVALID

    position is out of range; the message gives the highest position.
  • 400 THEME_BLOCK_NOT_ACCEPTED

    The section (or parent block) does not accept this block type.
  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).
  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Place an app block

POST write_storefront

Place an installed app's block in a section.

type is an app block type (app:<app_id>:<key>) from List app blocks. The section's block slot must accept app blocks (accept_app_blocks in List section types) and the template must be one of the block's pages (alternate templates count as their resource's page). An app can place any installed app's block, its own included. Returns the new block_id. A write to the storefront's live theme never reaches shoppers directly: it is saved to the caller's own pending copy of the live theme (made on its first write, as shoppers see the live theme, then reused), and the response carries review (id, theme_id of the copy, live_theme_id, tool_name, status awaiting_review). The caller is the app for an app token and the token itself for a Store Admin API token. The merchant reviews the changes in Store Admin or the mobile app and publishes them, as one change in the live theme's history that can be undone, or discards them; a publish whose changes cannot be combined with later changes to the live theme is refused. A write to a theme that is not live is saved on it directly and has no review.

Path parameters

Name Type Description
storefront_id required string

Storefront ID.

Example: 1b2f6a43-0c8e-4d2b-9a7e-3f5d8c1e6b20
theme_id required string

Theme ID from List storefront themes. For the live theme, keep using its ID after your first write: your reads and writes go to your pending copy.

Example: 5c0e9d1a-7b42-4f6e-9a38-2d7c1b9e4f60
page_type required string

The template: a page type such as home, product or collection, an alternate such as product__summer, or a global part such as header, footer or global_body_start. List theme templates gives each resource template's page_type.

Example: product
section_id required string

Section ID from Get a theme template.

Example: f3b81c2e-6d4a-4e19-a7c5-9b0e2d4f6a17

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
base_hash required string|null

The template's base_hash from Get a theme template (null or "" when the template does not exist yet). A template changed since is refused with THEME_CODE_FILE_CHANGED instead of overwritten.

Example: 4b1f0c9e2a7d6538e1c4b9a07f2d3e6c58a1b4d7e09f3c2a6b5d8e1f40a7c3b9
type required string

An app block type from List app blocks.

Example: app:d6a26466-7903-4e2f-8fd7-7c59f3c8cd9a:instalments
position integer

0-based position in the list. Default: the end.
settings object

Setting id → value, as List section types lists the type's settings; null puts a setting back to its default. Only the settings you send change. Up to 200; blocks is not a setting (use the block endpoints).

Example: {"payments":3}
message string

Up to 500 characters, kept with the change in the theme's history. Default: a summary of the change.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 INVALID_INPUT

    An ID in the path is not a UUID, or a body field is missing or invalid (error.field names it).
  • 404 THEME_SECTION_NOT_FOUND

    The theme is not one of this storefront's themes.
  • 409 THEME_CODE_DEFAULT_THEME

    The default theme cannot be edited. Duplicate it in Store Admin and work on the copy.
  • 409 THEME_REVIEW_LIMIT

    This is your first write to the live theme, and the storefront already has 3 pending copies of other apps and tokens waiting for review. The merchant publishes or discards one first.
  • 409 THEME_REVIEW_OTHER_THEME

    Your pending copy of an earlier live theme is still waiting for review. The merchant publishes or discards it first.
  • 403 THEME_REVIEW_OTHER_TOOL

    The theme is another app's or token's pending copy.
  • 404 THEME_REVIEW_NOT_FOUND

    The theme is a pending copy whose review was already published or discarded.
  • 422 THEME_CODE_RENDER_FAILED

    With the change, a page could not be shown; nothing was saved. The message names the page and the error.
  • 400 THEME_CODE_TEMPLATE_PAGE_UNKNOWN

    page_type is not a page, alternate or global part the storefront has.
  • 409 THEME_CODE_FILE_CHANGED

    The template changed since you read it (base_hash). Read it again and redo the change.
  • 400 THEME_SETTING_REMOVED

    A setting in settings is not a setting of the section or block.
  • 404 THEME_TEMPLATE_SECTION_NOT_FOUND

    The template has no section section_id. Read the template again.
  • 400 THEME_TEMPLATE_POSITION_INVALID

    position is out of range; the message gives the highest position.
  • 400 THEME_BLOCK_NOT_ACCEPTED

    The section (or parent block) does not accept this block type.
  • 400 APP_BLOCK_PAGE_UNSUPPORTED

    The block does not list this page.
  • 400 APP_BLOCK_APP_NOT_INSTALLED

    The block's app is not installed on the store.
  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).
  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Update a block

PATCH write_storefront

Change a block's settings, or hide or show it.

Only the settings you send change. Works for app blocks too. A write to the storefront's live theme never reaches shoppers directly: it is saved to the caller's own pending copy of the live theme (made on its first write, as shoppers see the live theme, then reused), and the response carries review (id, theme_id of the copy, live_theme_id, tool_name, status awaiting_review). The caller is the app for an app token and the token itself for a Store Admin API token. The merchant reviews the changes in Store Admin or the mobile app and publishes them, as one change in the live theme's history that can be undone, or discards them; a publish whose changes cannot be combined with later changes to the live theme is refused. A write to a theme that is not live is saved on it directly and has no review.

Path parameters

Name Type Description
storefront_id required string

Storefront ID.

Example: 1b2f6a43-0c8e-4d2b-9a7e-3f5d8c1e6b20
theme_id required string

Theme ID from List storefront themes. For the live theme, keep using its ID after your first write: your reads and writes go to your pending copy.

Example: 5c0e9d1a-7b42-4f6e-9a38-2d7c1b9e4f60
page_type required string

The template: a page type such as home, product or collection, an alternate such as product__summer, or a global part such as header, footer or global_body_start. List theme templates gives each resource template's page_type.

Example: product
section_id required string

Section ID from Get a theme template.

Example: f3b81c2e-6d4a-4e19-a7c5-9b0e2d4f6a17
block_id required string

Block ID from Get a theme template.

Example: 2d9e4a71-b3c8-4f05-8e6a-1c7b0f3d5e92

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
base_hash required string|null

The template's base_hash from Get a theme template (null or "" when the template does not exist yet). A template changed since is refused with THEME_CODE_FILE_CHANGED instead of overwritten.

Example: 4b1f0c9e2a7d6538e1c4b9a07f2d3e6c58a1b4d7e09f3c2a6b5d8e1f40a7c3b9
settings object

Setting id → value, as List section types lists the type's settings; null puts a setting back to its default. Only the settings you send change. Up to 200; blocks is not a setting (use the block endpoints).

Example: {"payments":4}
disabled boolean

true hides it on the page, false shows it.
message string

Up to 500 characters, kept with the change in the theme's history. Default: a summary of the change.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 INVALID_INPUT

    An ID in the path is not a UUID, or a body field is missing or invalid (error.field names it).
  • 404 THEME_SECTION_NOT_FOUND

    The theme is not one of this storefront's themes.
  • 409 THEME_CODE_DEFAULT_THEME

    The default theme cannot be edited. Duplicate it in Store Admin and work on the copy.
  • 409 THEME_REVIEW_LIMIT

    This is your first write to the live theme, and the storefront already has 3 pending copies of other apps and tokens waiting for review. The merchant publishes or discards one first.
  • 409 THEME_REVIEW_OTHER_THEME

    Your pending copy of an earlier live theme is still waiting for review. The merchant publishes or discards it first.
  • 403 THEME_REVIEW_OTHER_TOOL

    The theme is another app's or token's pending copy.
  • 404 THEME_REVIEW_NOT_FOUND

    The theme is a pending copy whose review was already published or discarded.
  • 422 THEME_CODE_RENDER_FAILED

    With the change, a page could not be shown; nothing was saved. The message names the page and the error.
  • 400 THEME_CODE_TEMPLATE_PAGE_UNKNOWN

    page_type is not a page, alternate or global part the storefront has.
  • 409 THEME_CODE_FILE_CHANGED

    The template changed since you read it (base_hash). Read it again and redo the change.
  • 400 THEME_SETTING_REMOVED

    A setting in settings is not a setting of the section or block.
  • 404 THEME_TEMPLATE_SECTION_NOT_FOUND

    The template has no section section_id. Read the template again.
  • 404 THEME_TEMPLATE_BLOCK_NOT_FOUND

    The section has no block block_id (or parent_block_id). Read the template again.
  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).
  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

Remove a block

DELETE write_storefront

Remove a block, and the blocks inside it, from a section.

base_hash and message are query parameters. A write to the storefront's live theme never reaches shoppers directly: it is saved to the caller's own pending copy of the live theme (made on its first write, as shoppers see the live theme, then reused), and the response carries review (id, theme_id of the copy, live_theme_id, tool_name, status awaiting_review). The caller is the app for an app token and the token itself for a Store Admin API token. The merchant reviews the changes in Store Admin or the mobile app and publishes them, as one change in the live theme's history that can be undone, or discards them; a publish whose changes cannot be combined with later changes to the live theme is refused. A write to a theme that is not live is saved on it directly and has no review.

Path parameters

Name Type Description
storefront_id required string

Storefront ID.

Example: 1b2f6a43-0c8e-4d2b-9a7e-3f5d8c1e6b20
theme_id required string

Theme ID from List storefront themes. For the live theme, keep using its ID after your first write: your reads and writes go to your pending copy.

Example: 5c0e9d1a-7b42-4f6e-9a38-2d7c1b9e4f60
page_type required string

The template: a page type such as home, product or collection, an alternate such as product__summer, or a global part such as header, footer or global_body_start. List theme templates gives each resource template's page_type.

Example: product
section_id required string

Section ID from Get a theme template.

Example: f3b81c2e-6d4a-4e19-a7c5-9b0e2d4f6a17
block_id required string

Block ID from Get a theme template.

Example: 2d9e4a71-b3c8-4f05-8e6a-1c7b0f3d5e92

Query parameters

Name Type Description
base_hash required string

The template's base_hash from Get a theme template (null or "" when the template does not exist yet). A template changed since is refused with THEME_CODE_FILE_CHANGED instead of overwritten.

Example: 4b1f0c9e2a7d6538e1c4b9a07f2d3e6c58a1b4d7e09f3c2a6b5d8e1f40a7c3b9
message string

Up to 500 characters, kept with the change in the theme's history. Default: a summary of the change.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 INVALID_INPUT

    An ID in the path is not a UUID, or a body field is missing or invalid (error.field names it).
  • 404 THEME_SECTION_NOT_FOUND

    The theme is not one of this storefront's themes.
  • 409 THEME_CODE_DEFAULT_THEME

    The default theme cannot be edited. Duplicate it in Store Admin and work on the copy.
  • 409 THEME_REVIEW_LIMIT

    This is your first write to the live theme, and the storefront already has 3 pending copies of other apps and tokens waiting for review. The merchant publishes or discards one first.
  • 409 THEME_REVIEW_OTHER_THEME

    Your pending copy of an earlier live theme is still waiting for review. The merchant publishes or discards it first.
  • 403 THEME_REVIEW_OTHER_TOOL

    The theme is another app's or token's pending copy.
  • 404 THEME_REVIEW_NOT_FOUND

    The theme is a pending copy whose review was already published or discarded.
  • 422 THEME_CODE_RENDER_FAILED

    With the change, a page could not be shown; nothing was saved. The message names the page and the error.
  • 400 THEME_CODE_TEMPLATE_PAGE_UNKNOWN

    page_type is not a page, alternate or global part the storefront has.
  • 409 THEME_CODE_FILE_CHANGED

    The template changed since you read it (base_hash). Read it again and redo the change.
  • 400 THEME_SETTING_REMOVED

    A setting in settings is not a setting of the section or block.
  • 404 THEME_TEMPLATE_SECTION_NOT_FOUND

    The template has no section section_id. Read the template again.
  • 404 THEME_TEMPLATE_BLOCK_NOT_FOUND

    The section has no block block_id (or parent_block_id). Read the template again.

Move a block

POST write_storefront

Move a block to another position in the list it is in.

A write to the storefront's live theme never reaches shoppers directly: it is saved to the caller's own pending copy of the live theme (made on its first write, as shoppers see the live theme, then reused), and the response carries review (id, theme_id of the copy, live_theme_id, tool_name, status awaiting_review). The caller is the app for an app token and the token itself for a Store Admin API token. The merchant reviews the changes in Store Admin or the mobile app and publishes them, as one change in the live theme's history that can be undone, or discards them; a publish whose changes cannot be combined with later changes to the live theme is refused. A write to a theme that is not live is saved on it directly and has no review.

Path parameters

Name Type Description
storefront_id required string

Storefront ID.

Example: 1b2f6a43-0c8e-4d2b-9a7e-3f5d8c1e6b20
theme_id required string

Theme ID from List storefront themes. For the live theme, keep using its ID after your first write: your reads and writes go to your pending copy.

Example: 5c0e9d1a-7b42-4f6e-9a38-2d7c1b9e4f60
page_type required string

The template: a page type such as home, product or collection, an alternate such as product__summer, or a global part such as header, footer or global_body_start. List theme templates gives each resource template's page_type.

Example: product
section_id required string

Section ID from Get a theme template.

Example: f3b81c2e-6d4a-4e19-a7c5-9b0e2d4f6a17
block_id required string

Block ID from Get a theme template.

Example: 2d9e4a71-b3c8-4f05-8e6a-1c7b0f3d5e92

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Body parameters

Name Type Description
base_hash required string|null

The template's base_hash from Get a theme template (null or "" when the template does not exist yet). A template changed since is refused with THEME_CODE_FILE_CHANGED instead of overwritten.

Example: 4b1f0c9e2a7d6538e1c4b9a07f2d3e6c58a1b4d7e09f3c2a6b5d8e1f40a7c3b9
position required integer

0-based position to move it to.

Example: 0
message string

Up to 500 characters, kept with the change in the theme's history. Default: a summary of the change.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 INVALID_INPUT

    An ID in the path is not a UUID, or a body field is missing or invalid (error.field names it).
  • 404 THEME_SECTION_NOT_FOUND

    The theme is not one of this storefront's themes.
  • 409 THEME_CODE_DEFAULT_THEME

    The default theme cannot be edited. Duplicate it in Store Admin and work on the copy.
  • 409 THEME_REVIEW_LIMIT

    This is your first write to the live theme, and the storefront already has 3 pending copies of other apps and tokens waiting for review. The merchant publishes or discards one first.
  • 409 THEME_REVIEW_OTHER_THEME

    Your pending copy of an earlier live theme is still waiting for review. The merchant publishes or discards it first.
  • 403 THEME_REVIEW_OTHER_TOOL

    The theme is another app's or token's pending copy.
  • 404 THEME_REVIEW_NOT_FOUND

    The theme is a pending copy whose review was already published or discarded.
  • 422 THEME_CODE_RENDER_FAILED

    With the change, a page could not be shown; nothing was saved. The message names the page and the error.
  • 400 THEME_CODE_TEMPLATE_PAGE_UNKNOWN

    page_type is not a page, alternate or global part the storefront has.
  • 409 THEME_CODE_FILE_CHANGED

    The template changed since you read it (base_hash). Read it again and redo the change.
  • 400 THEME_SETTING_REMOVED

    A setting in settings is not a setting of the section or block.
  • 404 THEME_TEMPLATE_SECTION_NOT_FOUND

    The template has no section section_id. Read the template again.
  • 404 THEME_TEMPLATE_BLOCK_NOT_FOUND

    The section has no block block_id (or parent_block_id). Read the template again.
  • 400 THEME_TEMPLATE_POSITION_INVALID

    position is out of range; the message gives the highest position.
  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).
  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

List theme text

GET read_storefront + read_translations

List a theme's translatable text in one language, with each translation and its status.

Theme text is the merchant's own words in a theme: the text, textarea and richtext settings of the sections and blocks on every page and global part (header, footer, templates), and of the theme's global settings (announcement bars, footer text). Each field has a key (<page>/<section_id>/<setting_id>, <page>/<section_id>/<block_id>/<setting_id> for a block at any depth, or theme_settings/<setting_id>), where it is (page, page_label_key, template_name, section_name, block_name, setting_label), its type (richtext is HTML), the source shoppers see in the default language, the translation value (empty when missing) and its status: translated, outdated (the source text changed since it was translated) or missing. Keys follow sections and blocks when they move and go when they are removed. Texts that use the theme's own strings (@t: keys) are translated with the theme's locale files and are not listed; the password, coming soon and maintenance pages have their own translation types. counts covers the whole theme (or page) before the status filter; page through with cursor. max_rows is how many rows Set theme text translations takes. The live theme's text is read as shoppers see it, never from a pending copy.

Path parameters

Name Type Description
storefront_id required string

Storefront ID.

Example: 1b2f6a43-0c8e-4d2b-9a7e-3f5d8c1e6b20
theme_id required string

Theme ID from List storefront themes. For the live theme, keep using its ID after your first write: your reads and writes go to your pending copy.

Example: 5c0e9d1a-7b42-4f6e-9a38-2d7c1b9e4f60

Query parameters

Name Type Description
locale required string

A store language other than the default language.

Example: de
page string

Only this page (a field's page, such as product, header or theme_settings).
status string

Only missing, outdated or translated fields, or untranslated (missing and outdated).
cursor string

next_cursor from the previous page.
limit integer

Fields per page, 1 to 250. Default 100.

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 INVALID_INPUT

    An ID in the path is not a UUID.
  • 404 THEME_SECTION_NOT_FOUND

    The theme is not one of this storefront's themes.
  • 403 THEME_REVIEW_OTHER_TOOL

    The theme is another app's or token's pending copy.
  • 400 TRANSLATION_LOCALE_REQUIRED

    locale is missing.
  • 400 TRANSLATION_LOCALE_NOT_ENABLED

    locale is not a language of this store.
  • 400 TRANSLATION_DEFAULT_LOCALE_FORBIDDEN

    locale is the store's default language: its text is the source.

Set theme text translations

PUT write_storefront + write_translations

Save translations of a theme's text, up to 100 rows in one call.

Each row is {key, locale, value} with a key from List theme text and any store language but the default; an empty value removes the translation (shoppers see the source again). Values are checked as the theme editor checks the setting (length; richtext is HTML). Translations are content, not theme files: they reach shoppers on the theme named straight away, the live theme included. They are not saved to a pending copy, need no review, and are not changes in the theme's history. Each row is saved or fails on its own: results lists the rows in order with status saved (and the field's new translation status) or failed with its error; totals counts them. A key or locale may appear once per call. A top-level code and message give the outcome: TRANSLATIONS_SAVED (200, every row saved), TRANSLATIONS_PARTIALLY_SAVED (200, success: true; the message counts saved and failed rows and names the failure reasons, e.g. "2 saved, 1 failed. No source text found for the requested fields (description).") TRANSLATIONS_NOT_SAVED_RETRY (503 with a Retry-After header, success: false; no row saved because every row failed only with TRANSLATION_WRITE_BUSY, so the same call can be sent again after error.details.retry_after_seconds) or TRANSLATIONS_NOT_SAVED (422, success: false; no row saved and at least one row failed for another reason). Both carry the same totals and results in error.details.

Path parameters

Name Type Description
storefront_id required string

Storefront ID.

Example: 1b2f6a43-0c8e-4d2b-9a7e-3f5d8c1e6b20
theme_id required string

Theme ID from List storefront themes. For the live theme, keep using its ID after your first write: your reads and writes go to your pending copy.

Example: 5c0e9d1a-7b42-4f6e-9a38-2d7c1b9e4f60

Headers

Name Type Description
Authorization required string

Bearer Store API token.
Idempotency-Key string

Optional key for this translation write. Reuse it only with the same payload when repeating the request.

Body parameters

Name Type Description
translations required array

Rows {key, locale, value} (1 to 100).

Example: [{"key":"product/f3b81c2e-6d4a-4e19-a7c5-9b0e2d4f6a17/2d9e4a71-b3c8-4f05-8e6a-1c7b0f3d5e92/heading","locale":"de","value":"Pflege"}]

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 INVALID_INPUT

    An ID in the path is not a UUID.
  • 404 THEME_SECTION_NOT_FOUND

    The theme is not one of this storefront's themes.
  • 403 THEME_REVIEW_OTHER_TOOL

    The theme is another app's or token's pending copy.
  • 400 TRANSLATION_NO_WRITES_PROVIDED

    translations is empty.
  • 400 TRANSLATION_TOO_MANY_ROWS

    More than 100 rows.
  • 400 TRANSLATION_ROW_DUPLICATE

    The same key and locale appear twice.
  • 422 TRANSLATIONS_NOT_SAVED

    No row saved; error.details has theme_id, totals and results.
  • 400 STORE_API_BODY_PROPERTY_UNKNOWN

    The body has a property this request does not accept. The message and error.details.properties list the allowed and required properties (nested for each object or list of objects).
  • 400 STORE_API_BODY_PROPERTY_INVALID

    A body property has the wrong type (error.details.expected_type). The message and error.details.properties list the allowed and required properties.

List app blocks

GET read_storefront

List the app blocks the store's installed apps offer for a storefront.

Each block comes from its app's installed release. type is the block instance type a theme template uses (app:<app_id>:<key>), placed in the blocks list of a section whose blocks slot sets accept_app_blocks, in a template of one of the block's pages. mode is template (rendered into the page and cached with it) or hosted_surface (renders its markup, then opens the app's hosted page in a frame). settings is the block's settings schema. A save that places a block on a page it does not list is refused.

Path parameters

Name Type Description
storefront_id required string

Storefront ID.

Example: 1b2f6a43-0c8e-4d2b-9a7e-3f5d8c1e6b20

Query parameters

Name Type Description
page string

Keep only blocks that may be placed on this page type.

Allowed values
productcollectioncartpageaccountbloghome
Example: product

Headers

Name Type Description
Authorization required string

Bearer Store API token.

Errors

  • 401 UNAUTHORIZED

    Authorization header missing, malformed, or token invalid/expired.
  • 402 SUBSCRIPTION_REQUIRED

    The store does not have an active or trialing subscription.
  • 403 STORE_API_SCOPE_REQUIRED

    Token is valid but lacks the required scope for this call.
  • 429 RATE_LIMITED

    The token's request allowance is exhausted. Retry after the Retry-After header.
  • 400 INVALID_INPUT

    storefront_id is not a UUID, or page is not one of the page types.
  • 404 NOT_FOUND

    The storefront does not belong to this store.

Last updated Nov 1, 2026