Design tools

​

apply_starter

Overwrites the store’s DRAFT templates with a starter, replacing any draft of the same name. Shoppers keep seeing the published version until publish_template runs. This is the intended way to begin: apply, then edit, rather than authoring from nothing. Scope: write_storefront

​

get_section_fields

Lists the settings one section accepts, with their types and allowed values, AND what each one currently says in the draft, plus the repeated content that has to be edited elsewhere. Call this before update_section: it is the only way to read a section’s current values, which is what lets you quote a heading back to the merchant, derive a new value from the old one, or confirm a write landed. Scope: read_storefront

​

get_store_layout

Reports the store’s Online Store builder layout: every section, whether it is switched on, the order they render in, and the header navigation. Also reports which pages are served by an authored template instead, because a section cannot render on those. Call this before answering anything about sections, banners, or navigation. Scope: read_storefront Takes no arguments.

​

get_theme_settings

Read the storefront’s design tokens (colors, font, layout variants) and the full list of tokens that can be set. Call this before update_theme_settings. Scope: read_storefront Takes no arguments.

​

list_layout_revisions

Lists past publishes of the Online Store layout, newest first, so a merchant can go back to one. Call this before restore_layout_revision to get an id. READ THE ORDERING NOTE IN THE RESULT: a layout revision records the state that publish PUT LIVE, so the newest entry is what shoppers see now and restoring it changes nothing. Undoing the last publish means restoring the SECOND entry. This is the opposite of list_template_revisions, where each entry is what the page looked like BEFORE that publish and the newest one is the undo. Scope: read_storefront

​

list_starters

Lists the starter page sets a store can begin from, and what each one suits. Each starter carries one page per template kind, so applying it gives the store a whole storefront rather than a single page. Call this before authoring any template: applying the closest starter and editing it produces a far better storefront than writing one from a blank page. Scope: read_storefront Takes no arguments.

​

publish_store_layout

Makes the DRAFT builder layout live for shoppers. Everything the other layout tools write is a draft until this runs, so a merchant can review before anything changes. Scope: write_storefront Takes no arguments.

​

reorder_sections

Sets the order Online Store builder sections render in, top to bottom, in the DRAFT. Every id must be one this store already has; ids you leave out keep their configuration and simply stop being ordered, so pass the full list from get_store_layout with the order changed. Scope: write_storefront

​

restore_layout_revision

Puts a past publish of the Online Store layout back into the DRAFT. This is the undo for publish_store_layout. It replaces the whole draft, so anything unsaved since is lost, and it does not go live until publish_store_layout runs. PICK THE RIGHT ID: the newest revision is the state that is live now, so restoring it is a no-op. Undoing the last publish means the SECOND entry from list_layout_revisions, which labels both. Scope: write_storefront

​

set_navigation

Replaces the header navigation in the DRAFT. This is the whole menu, not an append: pass every item the merchant should have, because anything left out is removed. Unlike the section tools this reaches a page served by an authored template too: an authored header binds the same menu through navigation.links, so publishing it changes what a shopper sees on every page. A store that has never set a menu falls back to listing its published collections, so the first call here is what stops a header showing all of them. Every url must be a path on this store, starting with a single /; anything else is dropped rather than rendered. Scope: write_storefront

​

set_section_enabled

Switches one Online Store builder section on or off in the DRAFT. Call get_store_layout first for the section ids and to check the page is not served by an authored template, because a section cannot render on a page that is. Publish with publish_store_layout when the merchant is happy. Scope: write_storefront

​

update_section

Sets a section’s own settings in the DRAFT: headings, calls to action, layout variant, how many items it shows, and which products it pulls from. Call get_section_fields first for the fields a given section accepts, because the same name means different things in different sections. Repeated content such as hero slides, promo banners and footer columns is not settable here. Scope: write_storefront

​

update_theme_settings

Set one or more design tokens. Pass only the tokens you want to change; the rest are left alone. Colors are hex like #1a1a1a; logo and favicon tokens are absolute https urls. Scope: write_storefront Takes no arguments.