> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluid.app/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> For new direct REST integrations, use the v2026-04 surfaces. The @fluid-app FairShare SDK continues to use its own published public-v2025-06 contract.
> Authenticate with the header Authorization: Bearer <token>; public storefront read endpoints require no auth.
> Lists use cursor pagination via the page[cursor] and page[limit] query params; follow meta.pagination.next_cursor until it is null.
> Never use /api/company/v1 or /api/v1 paths, page/per_page params, or offset pagination — they are legacy.
> The OpenAPI specs under api-reference/ are the authoritative contracts; prefer them over prose when in doubt. api-reference/storefront-v2026-04.yaml covers the v2026-04 storefront surface (/api/v202604/... paths); api-reference/auth-v0.yaml covers the unversioned auth surface (/api/... paths — authentication, MFA, social auth, and token exchange); api-reference/checkout-v2026-04.yaml covers the v2026-04 checkout surface (/api/checkout/v2026-04/... paths — carts, cart auth, discounts, items, subscriptions, orders, enrollments, and store config); api-reference/public-v2025-06.yaml covers the Public SDK surface used by the @fluid-app FairShare SDK, including its parallel cart lifecycle, browser integrations, versioned payment callbacks, unversioned public utilities, and the cart price-override operation; api-reference/payment-v2026-04.yaml covers the v2026-04 payment gateway admin surface (/api/payment/v2026-04/... paths, bearer-authenticated — gateway CRUD, gateway purchase/authorize/$0-verify, transaction list/show and capture/void/credit, and merchant payment configuration); api-reference/payments-v2026-04.yaml covers the v2026-04 cart payment surface (/api/payments/v2026-04/carts/{cart_token}/... paths, authenticated by the cart token in the path with no bearer — payment-method selection, VGS card tokenization, 3D Secure verification, and PayPal/Braintree/Klarna/Apple Pay flows); api-reference/commerce-v2026-04.yaml covers the v2026-04 commerce order-editing surface (/api/v202604/orders/{order_id}/edits paths, bearer-authenticated — post-checkout order edits that atomically insert items and add adjustments/discounts, with an optional dry-run preview); api-reference/webhooks-v0.yaml covers the unversioned webhooks surface (/api/... paths — webhook registration, delivery payloads, callback registrations, company events, and webhook/callback schemas).
> Successful responses wrap the resource payload alongside a top-level integer status and a meta object.

# Fluid Themes: Overview, Architecture, and Hierarchy

> Fluid's themes system lets you build fully custom websites using Liquid templating, JSON section schemas, and a drag-and-drop visual editor.

Fluid's themes system gives you everything you need to build, customize, and maintain a fully branded website — from a drag-and-drop visual editor for marketers to a complete Liquid templating engine for developers. Whether you're launching a new storefront or redesigning an existing one, themes are the foundation that controls how every page looks and behaves.

## Choosing a Theme

Every Fluid company theme starts as a clone of one of three platform-provided root themes. Each root theme has a distinct design philosophy and a set of ideal use cases:

<CardGroup cols={3}>
  <Card title="Base" icon="square">
    A clean, minimal starting point with no strong stylistic opinions. Best suited for **professional services** and **B2B companies** that need a polished, understated look and plan to apply heavy custom styling.
  </Card>

  <Card title="Vox" icon="bolt">
    A modern, bold design with strong typography and high-contrast layouts. Best suited for **creative agencies** and **portfolios** that want to make a visual statement out of the box.
  </Card>

  <Card title="Fluid" icon="droplet">
    A versatile, feature-rich theme built for commerce. Best suited for **e-commerce stores** that need extensive customization, built-in section variety, and a proven storefront structure.
  </Card>
</CardGroup>

## How Themes Work

When you create a company theme, Fluid clones the root theme of your choice into your account. From that point on, your company theme is independent — you can modify templates, add sections, and customize settings without affecting the root theme or any other company.

Root themes are maintained by the Fluid platform and receive ongoing updates. Your company theme does not automatically inherit those updates after cloning, which means you have full control over your theme's evolution without unexpected changes to your live storefront.

Each theme is made up of **template files** (Liquid), **section schemas** (JSON), **assets** (images, CSS, JS), and **locale files** (for translations). You can edit all of these through the visual Page Editor, through Code Mode in the editor, or locally using the Fluid CLI.

## Theme Hierarchy

When Fluid resolves which template to render for a given page, it follows a priority order. The first match wins:

<Steps>
  <Step title="URL Parameter Override">
    If the request includes a `?template_id=...` query parameter, Fluid uses that specific template. Useful for previewing unpublished templates.
  </Step>

  <Step title="Content-Specific Assignment">
    If a product, collection, or other content item has been explicitly assigned a template in the admin, Fluid uses that assignment.
  </Step>

  <Step title="Company Theme Default">
    Fluid uses the published default template of the matching type from your company theme.
  </Step>

  <Step title="Root Theme Fallback">
    If no company template exists for the requested type, Fluid falls back to the root theme's template for that type.
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Page Editor" icon="paintbrush" href="/themes/page-editor">
    Customize pages visually with the drag-and-drop editor — no code required.
  </Card>

  <Card title="Developer Guide" icon="code" href="/themes/developer-guide">
    Build custom templates and sections using Liquid and JSON schemas.
  </Card>

  <Card title="Fluid CLI" icon="terminal" href="/themes/cli">
    Pull, push, and develop themes locally with the Fluid CLI.
  </Card>

  <Card title="Theme Variables" icon="brackets-curly" href="/themes/theme-variables">
    Reference every Liquid variable available across page types.
  </Card>

  <Card title="Root Theme Configuration" icon="sliders" href="/themes/root-theme-configuration">
    Connect settings, stored values, and CSS variables across Base, Vox, and Fluid.
  </Card>

  <Card title="Supported Paths" icon="route" href="/themes/supported-paths">
    Build storefront links with the current route patterns.
  </Card>

  <Card title="Affiliate Hydration" icon="user-group" href="/themes/affiliate-hydration">
    Render affiliate-specific details safely in cacheable pages.
  </Card>

  <Card title="GitHub Integration" icon="github" href="/themes/github-integration">
    Connect a theme to a repository branch.
  </Card>
</CardGroup>