Storefront layout

Toolset storefront_layout, 18 tools.

ActionsHivatkozás másolása

theme_block_addHivatkozás másolása

Add one block to a section or under another block.

Add one block (settings, token style, conditions) to a section or under parent_block_id; depth <= 5. For element trees use theme_element_insert.

• Action key: theme_block.add
• Permission: theme.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "template_id": "home",
  "section_id": "hero-1",
  "type": "button",
  "settings": {
    "label": "Shop now"
  }
}

theme_block_moveHivatkozás másolása

Move a block to another section or place, with its settings.

Move a block between sections. Settings and settings_i18n stay on the block. A fixed element (pinned in place by the theme) cannot be moved.

• Action key: theme_block.move
• Permission: theme.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "template_id": "home",
  "block_id": "button-1",
  "from_section_id": "hero-1",
  "to_section_id": "banner-1"
}

theme_block_removeHivatkozás másolása

Remove a block from a section; a fixed element stays.

Remove a block from a section, searching nested blocks by id. A fixed element (pinned in place by the theme) cannot be removed.

• Action key: theme_block.remove
• Permission: theme.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "template_id": "home",
  "section_id": "hero-1",
  "block_id": "button-1"
}

theme_block_updateHivatkozás másolása

Merge settings, translations and style into one block, or replace its conditions.

Merge settings (settings_i18n[locale] with locale) and token style into a block found by id; style merges key by key into the stored style, and conditions replace the stored ones. Style nests by group, for example style {"spacing":{"padding":{"top":"2xl","bottom":"2xl"}},"typography":{"size":"h2"}}; never dotted keys such as "padding.top". own_in_locale gives one language its own image, video, URL or link; share_in_locale shares the base one again.

• Action key: theme_block.update
• Permission: theme.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "template_id": "home",
  "section_id": "hero-1",
  "block_id": "button-1",
  "settings": {
    "label": "Shop now"
  }
}

theme_customizer_getHivatkozás másolása

The theme's templates, pages, pop-ups, colour schemes, banners, languages and file problems; read it first.

Compact theme customizer overview: templates, theme pages, site_pages (content pages at their own URLs; own_layout means template page:<id> exists, otherwise they share the page template), overlays (the platform pop-ups this theme draws, by their merchant names, where each is edited and the locked parts it always keeps), color_schemes (the named schemes a section or block's color_scheme setting picks), alternate_templates (saved variants of the product or category page), banners (the storefront announcement bars and promo, discount and newsletter pop-ups with their schedules), locales (base_locale is the language settings are written in; other languages are overlays), unpublished state, and schema_errors , theme file problems the merchant sees as a customizer banner; fix any before other work.

• Action key: theme_customizer.get
• Permission: theme.read
• Approval: Runs without approval.
• Effect: Reads only.
• Retries: safe to repeat with the same input.

Example input:

{}

theme_element_catalog_getHivatkozás másolása

The elements and section types that can be inserted, by picker category.

List insertable elements (platform, plugin, app and theme) with label, icon, category and source (the provider kind); with template_id only those offered there, plus the addable section types.

• Action key: theme_element_catalog.get
• Permission: theme.read
• Approval: Runs without approval.
• Effect: Reads only.
• Retries: safe to repeat with the same input.

Example input:

{
  "template_id": "home"
}

theme_element_duplicateHivatkozás másolása

Copy an element right after itself in the same parent and slot.

Duplicate an element (block) right after itself in the same parent and slot, with its children, translations, style and conditions; copies get fresh ids and drop an anchor the page already uses.

• Action key: theme_element.duplicate
• Permission: theme.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "template_id": "home",
  "section_id": "hero-1",
  "block_id": "button-1"
}

theme_element_insertHivatkozás másolása

Insert an element tree into a section or under a block in one write.

Insert an element tree (type, settings, style, children) into a section or under a block in one call; ids are minted, field defaults seeded, accept lists, slots, setting keys and depth <= 5 validated. Max 50 nodes.

• Action key: theme_element.insert
• Permission: theme.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "template_id": "home",
  "section_id": "hero-1",
  "element": {
    "type": "text",
    "settings": {
      "text": "Free shipping"
    }
  }
}

theme_media_searchHivatkozás másolása

Find the store's product, collection, category and media library photos to place in the theme.

Find store photos for any image the customizer places: published products (cover first), collections and categories (their artwork, else photos of their products), and the media library, the photos the store uploaded (the shop, its people, its place; a library row's title is its alt text). Use only items whose images is non-empty: a product's bind value goes in the image setting so the photo follows the product; otherwise set one of its images, a media library ref (media://<id>), exactly as given. An image setting takes only such a ref or a bind, never a web address. For a section about people, a place or the store's story, prefer library photos over product shots. Up to 20 rows per kind, 5 images each.

• Action key: theme_media.search
• Permission: theme.read
• Approval: Runs without approval.
• Effect: Reads only.
• Retries: safe to repeat with the same input.

Example input:

{
  "query": "summer",
  "kind": "product"
}

theme_section_addHivatkozás másolása

Add a section to a template, optionally from a preset, with settings, style and conditions.

Add a section to a template with optional settings, token style and conditions (audience, schedule). Mints a unique section id from the type. preset adds it as the customizer's Add section adds that starting layout, with its settings, style and elements (a design from theme_section_library_search is added by its type and one of its presets); settings and style then change it.

• Action key: theme_section.add
• Permission: theme.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "template_id": "home",
  "type": "hero",
  "settings": {
    "heading": "Summer sale"
  }
}

theme_section_duplicateHivatkozás másolása

Copy a section right after itself, with fresh ids.

Duplicate a section right after itself with its settings, translations, style, conditions and elements; every copy gets a fresh id and drops an anchor the page already uses.

• Action key: theme_section.duplicate
• Permission: theme.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "template_id": "home",
  "section_id": "hero-1"
}

theme_section_library_searchHivatkozás másolása

Search the designed sections the store can add, with their presets and previews.

Search the designed sections the store can add (the Designs group of Add section, and a theme's own sections that declare what they are for): each with the part of the page it plays (kinds), its mood, the photos and products it needs, height, its presets and a preview image per preset in this store's theme. Add one with theme_section_add using its type and a preset id, then fill its texts and photos with theme_section_update_many; no code is needed. Filter by kinds and moods, words in any language, or the photos the store has.

• Action key: theme_section_library.search
• Permission: theme.read
• Approval: Runs without approval.
• Effect: Reads only.
• Retries: safe to repeat with the same input.

Example input:

{
  "kinds": [
    "hero"
  ],
  "limit": 5
}

theme_section_removeHivatkozás másolása

Remove a section from a template; a template's main section stays.

Remove a section from a template. A template's main section (template_get lists its type under required_section_types) shows the page's own data and cannot be removed.

• Action key: theme_section.remove
• Permission: theme.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "template_id": "home",
  "section_id": "hero-1"
}

theme_section_reorderHivatkozás másolása

Put a template's sections in a new order.

Reorder a template's sections. section_ids must be a permutation of the current ids.

• Action key: theme_section.reorder
• Permission: theme.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "template_id": "home",
  "section_ids": [
    "hero-1",
    "featured-1"
  ]
}

theme_section_type_getHivatkozás másolása

A section or element type's fields, style capabilities, slots and accepted children.

Get a section or element type: fields, style capabilities with their token vocabulary, slots, accepted child types, max_blocks, nested block types, and the conditions and anchor rules.

• Action key: theme_section_type.get
• Permission: theme.read
• Approval: Runs without approval.
• Effect: Reads only.
• Retries: safe to repeat with the same input.

Example input:

{
  "type": "hero"
}

theme_section_updateHivatkozás másolása

Merge settings, translations and style into one section, or replace its conditions.

Merge settings (settings_i18n[locale] with locale) and token style into a section; style merges key by key into the stored style, and conditions replace the stored ones. Style nests by group, for example style {"spacing":{"padding":{"top":"2xl","bottom":"2xl"}},"typography":{"size":"h2"}}; never dotted keys such as "padding.top". own_in_locale gives one language its own image, video, URL or link; share_in_locale shares the base one again.

• Action key: theme_section.update
• Permission: theme.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "template_id": "home",
  "section_id": "hero-1",
  "settings": {
    "heading": "Summer sale"
  }
}

theme_section_update_manyHivatkozás másolása

Change one section's settings and many of its elements in one write.

Merge settings into a section and any of its blocks in one draft write (one save, one undo step); text goes to settings_i18n[locale] with locale. Use it to rewrite the text of a section and its blocks together.

• Action key: theme_section.update_many
• Permission: theme.write
• Approval: Waits for approval when the store requires it for this action.
• Effect: Changes a draft; nothing goes live until it is published.
• Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Example input:

{
  "template_id": "home",
  "section_id": "hero-1",
  "settings": {
    "heading": "Summer sale"
  }
}

theme_template_getHivatkozás másolása

One template's section tree, with the section types it can add and the ones it requires.

Get one template's section tree (ids, types, enabled, settings, style, conditions, blocks), addable type names, required_section_types and base_locale: settings hold base_locale text; write any other language with locale. A required type is the page's main section, such as product-information or blog-main: it renders the page's own data (the product, the posts, the questions), can be moved and styled, and is never removed or duplicated.

• Action key: theme_template.get
• Permission: theme.read
• Approval: Runs without approval.
• Effect: Reads only.
• Retries: safe to repeat with the same input.

Example input:

{
  "template_id": "home"
}