At a glance
Why a Fluid theme
Merchants can keep editing after you ship
Your templates, sections, and schemas become the panels in the Page Editor. Merchants rearrange sections and change settings without a developer, and without breaking your code. A headless front end loses that, unless you build an editor too.Routes carry FairShare credit
Fluid’s routes are built for FairShare. When a member shares a credit path such as/<username>/products/<slug>, the FairShare SDK logs the credit. FairShare then keeps that member’s credit as the shopper moves around the store. Every Fluid storefront already loads the SDK, so you don’t add it to a theme. See Supported paths and FairShare SDK and the storefront.
A headless site has to load the SDK itself and follow the same credit routes. If it doesn’t, member shares can’t credit the member.
Resources arrive on the right routes
Products, collections, categories, pages, posts, and media each have a slug route, such as/products/<slug>. Fluid matches the route to the resource and passes it into the right template. You write the template, and Fluid fetches the data. See Supported paths and Slugs and URLs.
Admins manage SEO and the page head
Each resource carries its own SEO title, description, preview image, and indexing setting, which admins can change. Admins add scripts and tags to the page head or body with global embeds, such as analytics or verification tags. See SEO. With a Fluid theme, you don’t build any of this.Droplets plug into your theme
Droplets that add storefront features have a structure to build on. A droplet can add sections that merchants place on pages, blocks inside your sections, and app embeds that load across the storefront. Your theme doesn’t change when a merchant installs one. See Droplet theme extensions.Menus survive theme changes
Navigation menus live in Fluid, not in your theme’s code. Admins edit the links in the admin, and your theme renders whatever menu it’s given. You can redesign or replace a theme later without rebuilding the menu structure.Every market can get its own view
The storefront sitemap gives every route a structure you can control. Country routes, called theme region rules in the API, can serve a different template, resource, or redirect for each country at the same URL. Use them when one market needs a different layout. Combine them with translations for language. See country routes in the API reference.Translations are easy to add and keep up
Your theme renders translated content from the same structure in every language. Products, collections, pages, menus, and your theme’s own text each carry a translation for every language the store sells in. Admins translate from the admin, or ask Mist, Fluid’s AI assistant, to do it. Agents and developers can use the Add a language guided setup. It finds what isn’t translated, machine-translates it, and confirms nothing is left. Shoppers pick their language on the storefront, and the theme doesn’t change. See Translations.You still control every pixel
None of this limits the design. Your theme is your own Liquid, CSS, and JavaScript, built from sections and blocks that you define. You work locally with the Fluid CLI or in the editor’s code mode. Developers and agents have full control, as long as they follow the structure these docs describe.When headless makes sense
Go headless when the front end isn’t a website Fluid can render: for example, a native mobile app, a kiosk, or a checkout embedded in another product. For those, build against the API:- Build a headless checkout for the purchase flow.
- Choosing a cart surface to pick between the Checkout API and the FairShare SDK’s cart.
- FairShare SDK to keep rep credit working.
For AI agents building a storefront
- Start from a Fluid theme, not a blank front end. To match a merchant’s current site, copy it into a theme. See Agent launch guide.
- Read the developer guide and common pitfalls before you edit.
- Install Fluid’s theme skills with
fluid theme skills install. See Fluid CLI. - Push to an unpublished theme, preview it, and publish only when the merchant approves.