Skip to main content

​
Liquid Theme Settings

Liquid themes receive settings through the render context. Settings are producer-normalized before templates render.

​
Files

FilePurpose
schema.jsonDescribes editable settings and blocks
settings.jsonTheme defaults
theme-package.jsonDeclares settings/schema paths and block registry

​
Reading Settings In Liquid

Use the setting filter when reading nested settings: 
{% assign title = settings | setting: "hero.title", "" %}
{% assign accent = settings | setting: "colors.primary", "#7c3aed" %}

<h1>{{ title }}</h1>
The fallback argument is for display defaults. Do not use it to hide missing required platform data such as product stock or price.

​
CSS Variables

Themes usually map settings to CSS variables in the generated theme head or stylesheet. Example: 
<button style="background-color: rgb(var(--brand-600)); color: #fff">
  Add to cart
</button>
The platform or theme CSS defines --brand-600 from settings.

​
Updating Settings Through The API

Read settings: 
GET /dev/v1/themes/{id}/control/settings
Update settings: 
POST /dev/v1/themes/{id}/control/settings
The request body uses builderSettings.

​
Settings vs Source

Use settings for merchant-editable values:
  • colors
  • font choices
  • hero copy
  • section visibility
  • spacing controls
Use source edits for structural changes:
  • adding a new snippet
  • changing section markup
  • changing block registry
  • adding a new CSS file

​
Next Steps

Core Contract

What Liquid templates may and may not do.

Editing Themes

Change settings and source through CLI, API, MCP, or dashboard.