Alternate templates

By default every product uses the theme’s product template, every collection uses collection, and so on. An alternate template is a second copy of one of those templates — for example a stripped-down landing layout for sale items, or a long-form page template with extra sections — that you assign to individual resources. The base template keeps serving everything else.

Alternate templates are identified by a suffix. A file named templates/product.sale.json is the sale alternate of the product template; templates/page.contact.json is the contact alternate of the page template. You create the file in the code editor, lay it out in the visual editor, then point a product, collection, page, blog, or blog post at it from that resource’s Theme template dropdown.

When to use one

Reach for an alternate template when a subset of resources of the same type needs a genuinely different layout, not just different content:

A lookbook or campaign layout for a handful of hero products.
A landing-style collection with a custom banner and editorial blocks instead of the standard grid.
A contact or about page template with a form, map, and team section you reuse across several pages.
A gift guide blog post layout that differs from your normal article.

If you only need different text or images on one page, edit that page’s content instead — you don’t need a separate template.

Which templates support suffixes

Most JSON templates accept a suffix: product, collection, list-collections, page, blog, article, cart, search, index, 404, password, the customers/* account templates, and metaobject/{type}. A few are single-purpose and have no suffix — gift_card and robots.txt — so they can’t have alternates.

In practice the resources you assign alternates to from the admin are products, collections, pages, blogs, and blog posts, because those are the records that carry a Theme template field.

Step 1 — Create the alternate file

You create the file in the code editor, which is where new theme files are added.

Open Online store → Themes, find the theme you want to work in, and choose Edit code from its menu. (Editing the live theme directly works, but doing this on a draft you’ll publish later is safer.)
In the file explorer on the left, find the Templates folder and use its add (+) action to open Create Template File.
Pick the Template type — for example product. The Extension is chosen for you (JSON for these templates).
In Name (optional), type the suffix, for example sale. Use lowercase letters, numbers, hyphens, and underscores only. The modal previews the resulting path, e.g. templates/product.sale.json.
Choose Create. The new template appears under Templates in the explorer, labelled product.sale.

For a metaobject template the modal also asks for the metaobject type (e.g. author) and creates templates/metaobject/{type}.json. See Metaobjects & web pages for how those become pages.

Step 2 — Lay it out in the visual editor

Once the file exists, build it visually like any other template.

Open the theme in the editor (Customize from the Themes page, or Edit theme then switch to the visual editor).
Use the template picker in the top bar. Alternates are grouped under their type — under Products you’ll see Default and your sale alternate; under Pages you’ll see Default and any page suffixes. Select the alternate to edit it.
Add, reorder, hide, and configure sections and blocks exactly as you would on the default template. See Using the visual editor for the section-and-block workflow.
Save, and Publish when you’re ready for customers to see it.

Step 3 — Assign it to a resource

Each resource has a Theme template selector. It lists Default plus every suffix that exists for that resource’s type in the active theme.

Open the product and go to the final SEO & publish step of the editor. The Theme template selector sits at the top of that step, above the search listing. Set it from Default to your suffix (e.g. sale) and save the product.

Both a blog and an individual blog post have their own Theme template field (blog and article suffixes respectively). Set it in the blog or post editor.

You can point as many resources at the same alternate as you like — that’s the whole point. Twenty sale products can all share product.sale, and editing that one template restyles all of them at once.

What happens automatically

Fallback to default. The storefront only serves the alternate if the suffix template actually exists in the published theme. If you assign a suffix and the matching file isn’t there — because you deleted it, or you published a different theme that doesn’t have it — the page quietly falls back to the base template. Customers never see an error.
The dropdown reflects the active theme. The Theme template list is built from the suffixes in your live theme’s templates. Create a new alternate and it appears as an option; remove the file and that option disappears.
Stale selections self-correct. If a resource is set to a suffix that no longer exists in the theme, the selector resets to Default the next time you open the resource, so you don’t get stuck pointing at a missing template.

Removing an alternate

There’s no “delete template” button on a resource — you change the assignment, the file, or both:

To stop a single resource using the alternate, open it and set Theme template back to Default.
To retire the alternate entirely, first move every resource off it (so nothing references the suffix), then delete the templates/<type>.<suffix>.json file in the code editor.

Because of the fallback above, deleting the file before reassigning resources won’t break anything — those pages just render with the default template — but it’s tidier to reassign first.

Troubleshooting

My alternate looks identical to the default. A new alternate isn’t a copy — it starts from the theme’s preset for that template type. Build the layout you want in the visual editor, or paste the default template’s JSON in as a starting point.
The page still shows the default layout. Confirm three things: the suffix file exists in the published theme (not just a draft), the resource’s Theme template is set to that suffix, and you published after editing the template. A draft-only template won’t serve live traffic.
The suffix isn’t in the dropdown. The list comes from the active theme. Make sure the theme that has the alternate is the live one, then reopen the resource.
I can’t add a suffix for gift cards. gift_card and robots.txt don’t support alternates — only one of each exists per theme.
The visual editor says there’s nothing to preview. Assign the alternate to at least one resource (Step 3); the preview needs a real product/collection/page to render against.

Next steps

Themes & the editor

How drafts, versions, and publishing fit together in Themes & the visual editor.

Visual editor guide

The section-and-block workflow you’ll use to build the alternate — Using the visual editor.

Edit theme code

Creating and editing template files directly in Edit theme code.

Section groups

Why the header and footer don’t change with the template — Section groups.