Pages and navigation

The 18 tools of the Pages and navigation toolset in the Storefront area, with their permissions, approval rules and inputs.

Toolset storefront_pages, 18 tools.

Actions

`theme_menu_add_item`

Add a link, or a dropdown with links, to a storefront menu.

Add a navbar link (menu defaults to primary); page_handle links /pages/<handle>. children make it a dropdown (a store category needs only its label); parent adds to a dropdown.

Action key: theme_menu.add_item
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.

Field	Type	Required	Description
`theme_id`	string		Theme ID. Omit to use the store active theme, or the only theme if none is marked active.
`menu`	string		Menu name; defaults to 'primary' (the navbar)
`label`	string		Visible link label
`href`	string		Link target path or URL; a category's page is /<category handle>
`page_handle`	string		Customizer page handle to link instead of a raw href
`position`	integer		Insert position; defaults to the end. at least 0
`parent`	string		Label of the top-level link to put this link under, in its dropdown
`children`	list of object		Links shown in the dropdown of the new link
`children[].label`	string	yes	at least 1 characters
`children[].href`	string		Path or URL; leave out to link the store category named by the label. at least 1 characters

Example input:

{
  "label": "Sale",
  "href": "/sale"
}

`theme_menu_get`

The storefront's navigation menus and their links; primary is the header navbar.

List the storefront navigation menus and their links. Menu 'primary' is the header navbar.

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

Field	Type	Required	Description
`theme_id`	string		Theme ID. Omit to use the store active theme, or the only theme if none is marked active.

Example input:

{}

`theme_menu_remove_item`

Remove a link from a storefront menu by its label or address.

Remove a link from a storefront navigation menu by label or href.

Action key: theme_menu.remove_item
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.

Field	Type	Required	Description
`theme_id`	string		Theme ID. Omit to use the store active theme, or the only theme if none is marked active.
`menu`	string		Menu name; defaults to 'primary' (the navbar)
`link`	string	yes	Label or href of the link to remove

Example input:

{
  "link": "Sale"
}

`theme_page_add`

Add a page to the theme at /pages/<handle>.

Add a theme page at /pages/<handle> (and /<handle> if free); link it separately. Never use it to stand in for a site page from overview site_pages.

Action key: theme_page.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.

Field	Type	Required	Description
`theme_id`	string		Theme ID. Omit to use the store active theme, or the only theme if none is marked active.
`handle`	string	yes	Page handle
`title`	string		Optional page title

Example input:

{
  "handle": "about",
  "title": "About us"
}

`theme_page_layout_fork`

Give a site page its own layout, copied from the shared page template.

Give a site page (theme_customizer_get site_pages) its own layout: copies the shared page template's sections onto page:<site page id> and answers that template_id.

Action key: theme_page_layout.fork
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.

Field	Type	Required	Description
`theme_id`	string		Theme ID. Omit to use the store active theme, or the only theme if none is marked active.
`page_id`	string	yes	Site page: its id from theme_customizer_get site_pages, or its slug, path or title. at least 1 characters

Example input:

{
  "page_id": "about-us"
}

`theme_page_layout_reset`

Drop a site page's own layout so it uses the shared page template again.

Delete the forked page layout so the page uses the shared page template again; every section of the fork is discarded.

Action key: theme_page_layout.reset
Permission: theme.write
Approval: Always waits for a person to approve it.
Effect: Changes a draft; nothing goes live until it is published.
Destructive: in compact mode it runs with run_destructive_action.
Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Field	Type	Required	Description
`theme_id`	string		Theme ID. Omit to use the store active theme, or the only theme if none is marked active.
`page_id`	string	yes	Site page: its id from theme_customizer_get site_pages, or its slug, path or title. at least 1 characters

Example input:

{
  "page_id": "about-us"
}

`theme_page_remove`

Remove a page the theme added, with its layout.

Remove a page added with theme_page_add, with its page template file. Links to it in menus stay until removed.

Action key: theme_page.remove
Permission: theme.write
Approval: Always waits for a person to approve it.
Effect: Changes a draft; nothing goes live until it is published.
Destructive: in compact mode it runs with run_destructive_action.
Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Field	Type	Required	Description
`theme_id`	string		Theme ID. Omit to use the store active theme, or the only theme if none is marked active.
`handle`	string	yes	Page handle

Example input:

{
  "handle": "about"
}

`theme_saved_element_delete`

Delete a saved element; what was placed from it stays.

Delete one saved section or element from the library; copies already on pages stay.

Action key: theme_saved_element.delete
Permission: theme.write
Approval: Always waits for a person to approve it.
Effect: Changes a draft; nothing goes live until it is published.
Destructive: in compact mode it runs with run_destructive_action.
Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Field	Type	Required	Description
`theme_id`	string		Theme ID. Omit to use the store active theme, or the only theme if none is marked active.
`item_id`	string	yes	Saved item id from theme_saved_element_list. at least 1 characters

Example input:

{
  "item_id": "019bb6da-2596-7755-a3e9-44f17ed76f3b"
}

`theme_saved_element_get`

One saved section or element with its full tree.

Get one saved section or element with its full tree (type, settings, translations, style, conditions, blocks), the shape theme_saved_element_update takes.

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

Field	Type	Required	Description
`theme_id`	string		Theme ID. Omit to use the store active theme, or the only theme if none is marked active.
`item_id`	string	yes	Saved item id from theme_saved_element_list. at least 1 characters

Example input:

{
  "item_id": "019bb6da-2596-7755-a3e9-44f17ed76f3b"
}

`theme_saved_element_insert`

Place a saved section or element into a template.

Insert a copy of a saved item with fresh ids, translations, style and conditions kept: a saved section into a template, a saved element into section_id (optionally under parent_block_id and in slot). Accept lists and slots are validated.

Action key: theme_saved_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.

Field	Type	Required	Description
`theme_id`	string		Theme ID. Omit to use the store active theme, or the only theme if none is marked active.
`template_id`	string	yes	Template ID: a fixed template ("home", "products", "collection" (a category or collection page), "product", "cart", "checkout", "order-confirmed" (the thank-you page), "order-status", "login", "register", "account", "page"; content pages "contact", "blog" (blog index and categories), "article" (a blog post), "guides" (guide index and categories), "guide" (a guide article), "faq", "legal", "not-found"), a platform pop-up's own template (theme_customizer_get overlays), an alternate such as "product--<key>" (overview alternate_templates), "page:<page id>" (a site page's own layout), or "layout.header" or "layout.footer" (the store header or footer)
`item_id`	string	yes	Saved item id from theme_saved_element_list. at least 1 characters
`after_section_id`	string		Place it right after this section; below the hero means after the hero id
`before_section_id`	string		Place it right before this section. Omit both to add it at the end of the page
`section_id`	string		Saved elements: the receiving section
`parent_block_id`	string		Saved elements: nest under this block
`slot`	string		Saved elements: named slot of the parent
`after_block_id`	string		Place it right after this element of the same parent and slot
`before_block_id`	string		Place it right before this element of the same parent and slot. Omit both to add it last

Example input:

{
  "template_id": "home",
  "item_id": "019bb6da-2596-7755-a3e9-44f17ed76f3b"
}

`theme_saved_element_list`

The sections and elements the merchant saved for reuse.

List the sections and elements saved for reuse in this theme (id, name, kind, root type, element count).

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

Field	Type	Required	Description
`theme_id`	string		Theme ID. Omit to use the store active theme, or the only theme if none is marked active.

Example input:

{}

`theme_saved_element_save`

Save a section or element of a template to the saved elements.

Save a section (or, with block_id, one element and its children) with its translations, style and conditions to the theme library, reusable from Saved in the picker. Library data, never theme code.

Action key: theme_saved_element.save
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.

Field	Type	Required	Description
`theme_id`	string		Theme ID. Omit to use the store active theme, or the only theme if none is marked active.
`template_id`	string	yes	Template ID: a fixed template ("home", "products", "collection" (a category or collection page), "product", "cart", "checkout", "order-confirmed" (the thank-you page), "order-status", "login", "register", "account", "page"; content pages "contact", "blog" (blog index and categories), "article" (a blog post), "guides" (guide index and categories), "guide" (a guide article), "faq", "legal", "not-found"), a platform pop-up's own template (theme_customizer_get overlays), an alternate such as "product--<key>" (overview alternate_templates), "page:<page id>" (a site page's own layout), or "layout.header" or "layout.footer" (the store header or footer)
`section_id`	string	yes	Section to save, or the section holding block_id
`block_id`	string		Save this element subtree instead
`name`	string	yes	Name shown under Saved in the picker. 1 to 80 characters

Example input:

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

`theme_saved_element_update`

Rename a saved element or replace what it holds.

Rename a saved section or element, or replace its contents with tree (ids are replaced, a root slot is dropped; at most 120 elements, 6 levels deep). Pages it was inserted into keep their copies.

Action key: theme_saved_element.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.

Field	Type	Required	Description
`theme_id`	string		Theme ID. Omit to use the store active theme, or the only theme if none is marked active.
`item_id`	string	yes	Saved item id from theme_saved_element_list. at least 1 characters
`name`	string		Name shown under Saved in the picker. 1 to 80 characters
`tree`	map of any value		New contents in the theme_saved_element_get tree shape; a saved section keeps a section root

Example input:

{
  "item_id": "019bb6da-2596-7755-a3e9-44f17ed76f3b",
  "name": "Spring hero"
}

`theme_template_assign`

Make a product, category or collection render with an alternate template.

Show one product, category or collection with an alternate template, or with the standard one again. Works on the store's live theme, whose alternates the overview lists.

Action key: theme_template.assign
Permission: theme.write
Approval: Waits for approval when the store requires it for this action.
Effect: Changes the live store.
Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Field	Type	Required	Description
`kind`	string	yes	What to put on the template. one of "product", "category", "collection"
`handle`	string	yes	Its handle, from the catalogue tools or its URL. at least 1 characters
`template_id`	string	yes	An alternate from overview alternate_templates, or its base template for the standard one

Example input:

{
  "kind": "product",
  "handle": "gift-card",
  "template_id": "product--gift-cards"
}

`theme_template_create_alternate`

Save a product, category or collection template as a named alternate.

Save a copy of the product page or the category / collection page template as a named alternate (a Christmas product page, a landing-style category). It starts as the copied layout; then edit it with the template tools on the returned template_id, and put products, categories or collections on it with theme_template_assign.

Action key: theme_template.create_alternate
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.

Field	Type	Required	Description
`theme_id`	string		Theme ID. Omit to use the store active theme, or the only theme if none is marked active.
`name`	string	yes	The name the merchant sees in the Template picker. at least 1 characters
`from_template_id`	string	yes	The template to copy: "product", "collection" or one of their alternates

Example input:

{
  "name": "Gift cards",
  "from_template_id": "product"
}

`theme_template_delete_alternate`

Delete an alternate template; on the live theme its products, categories or collections move to another alternate or the standard template first.

Action key: theme_template.delete_alternate
Permission: theme.write
Approval: Always waits for a person to approve it.
Effect: Changes a draft; nothing goes live until it is published.
Destructive: in compact mode it runs with run_destructive_action.
Retries: runs at most once; a repeat with the same idempotency key returns the first result.

Field	Type	Required	Description
`theme_id`	string		Theme ID. Omit to use the store active theme, or the only theme if none is marked active.
`template_id`	string	yes	An alternate from overview alternate_templates. at least 1 characters
`move_to`	string or null		The alternate key its pages move to; omit or null for the standard template. at least 1 characters

Example input:

{
  "template_id": "product--gift-cards"
}

`theme_template_get_assignment`

The templates one product, category or collection can render with, and the alternate it is on now.

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

Field	Type	Required	Description
`kind`	string	yes	What to look up. one of "product", "category", "collection"
`handle`	string	yes	Its handle, from the catalogue tools or its URL. at least 1 characters

Example input:

{
  "kind": "product",
  "handle": "gift-card"
}

`theme_template_rename_alternate`

Give an alternate template a new name; the pages on it stay on it.

Action key: theme_template.rename_alternate
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.

Field	Type	Required	Description
`theme_id`	string		Theme ID. Omit to use the store active theme, or the only theme if none is marked active.
`template_id`	string	yes	An alternate from overview alternate_templates. at least 1 characters
`name`	string	yes	The new name. 1 to 80 characters

Example input:

{
  "template_id": "product--gift-cards",
  "name": "Gift cards"
}

Pages and navigation

ActionsCopy Anchor Link

theme_menu_add_itemCopy Anchor Link

theme_menu_getCopy Anchor Link

theme_menu_remove_itemCopy Anchor Link

theme_page_addCopy Anchor Link

theme_page_layout_forkCopy Anchor Link

theme_page_layout_resetCopy Anchor Link

theme_page_removeCopy Anchor Link

theme_saved_element_deleteCopy Anchor Link

theme_saved_element_getCopy Anchor Link

theme_saved_element_insertCopy Anchor Link

theme_saved_element_listCopy Anchor Link

theme_saved_element_saveCopy Anchor Link

theme_saved_element_updateCopy Anchor Link

theme_template_assignCopy Anchor Link

theme_template_create_alternateCopy Anchor Link

theme_template_delete_alternateCopy Anchor Link

theme_template_get_assignmentCopy Anchor Link

theme_template_rename_alternateCopy Anchor Link

Actions

`theme_menu_add_item`

`theme_menu_get`

`theme_menu_remove_item`

`theme_page_add`

`theme_page_layout_fork`

`theme_page_layout_reset`

`theme_page_remove`

`theme_saved_element_delete`

`theme_saved_element_get`

`theme_saved_element_insert`

`theme_saved_element_list`

`theme_saved_element_save`

`theme_saved_element_update`

`theme_template_assign`

`theme_template_create_alternate`

`theme_template_delete_alternate`

`theme_template_get_assignment`

`theme_template_rename_alternate`