> ## 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 ; 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. # Choose blocks or components > Choose between components, inline blocks, and standalone theme blocks when you build reusable Fluid theme UI. Fluid themes provide three ways to reuse markup: * Components are Liquid partials that accept values when you render them. * Inline blocks are configurable items defined and rendered by one section. * Standalone theme blocks package markup and schema for reuse across sections. Choose the smallest primitive that gives editors the control they need. ## Use a component Create a component when you want to reuse markup without adding an editor-controlled item. Components do not have their own schema. Store each component in its own directory: ```text theme={null} components/ ├── button/ │ └── index.liquid └── product_card/ └── index.liquid ``` Render a component with named values: ```liquid theme={null} {% render 'button', text: 'View starter collection', href: collection.url, variant: 'primary' %} ``` Inside the component, use the passed values like regular Liquid variables: ```liquid theme={null} {% assign button_text = text | default: 'Learn more' %} {{ button_text }} ``` Document the accepted values in a Liquid comment at the top of the component. Give optional values a fallback. A component can render another component. ## Use an inline block Use an inline block when an item belongs to one section. Define its schema inside the section and render it from `section.blocks`. ```liquid theme={null}
{% for block in section.blocks %} {% case block.type %} {% when 'feature' %}

{{ block.settings.heading }}

{{ block.settings.description }}

{% endcase %} {% endfor %}
{% schema %} { "name": "Feature list", "blocks": [ { "type": "feature", "name": "Feature", "limit": 6, "settings": [ { "type": "text", "id": "heading", "label": "Heading", "default": "Flexible delivery" }, { "type": "textarea", "id": "description", "label": "Description", "default": "Choose the schedule that works for you." } ] } ], "presets": [ { "name": "Feature list", "blocks": [ { "type": "feature" } ] } ] } {% endschema %} ``` Add `{{ block.fluid_attributes }}` to the block's outer element. The editor uses these attributes to identify the selected item. ## Use a standalone theme block Use a standalone theme block when several sections need the same configurable item. A standalone block owns both its Liquid markup and its schema. Store blocks under `blocks/`: ```text theme={null} blocks/ ├── heading/ │ └── index.liquid ├── button/ │ └── index.liquid └── _product_card/ └── index.liquid ``` For example, `blocks/heading/index.liquid` can contain: ```liquid theme={null}
{{ block.settings.text }}
{% schema %} { "name": "Heading", "settings": [ { "type": "richtext", "id": "text", "label": "Text", "default": "

Build your daily routine

" } ], "presets": [ { "name": "Heading" } ] } {% endschema %} ``` Render the section's standalone blocks with `content_for`: ```liquid theme={null}
{% content_for 'blocks' %}
{% schema %} { "name": "Content stack", "blocks": [ { "type": "@theme" } ], "presets": [ { "name": "Content stack", "blocks": [ { "type": "heading", "settings": { "text": "

Build your daily routine

" } } ] } ] } {% endschema %} ``` `content_for 'blocks'` renders each block through its own template. Do not also loop over `section.blocks` to render the same standalone blocks. ### Control which blocks a section accepts Add `{"type": "@theme"}` to accept every public standalone block in the theme. Reference a block by name when the section should accept only selected block types: ```json theme={null} { "blocks": [ { "type": "heading" }, { "type": "button" } ] } ``` A named reference contains `type` without an inline `name` or `settings` definition. Fluid reads the matching standalone block's schema. You can combine public blocks, named references, and inline blocks: ```json theme={null} { "blocks": [ { "type": "@theme" }, { "type": "_product_card" }, { "type": "divider", "name": "Divider", "settings": [ { "type": "color", "id": "color", "label": "Color", "default": "#d9dee8" } ] } ] } ``` ### Keep a standalone block private Prefix a standalone block name with `_` to exclude it from `@theme`. Reference the private block by its exact name in sections that need it: ```json theme={null} { "blocks": [ { "type": "_product_card" } ] } ``` Use private blocks for section-specific structure that should not appear in every compatible block picker. ### Nest standalone blocks A standalone block can accept child blocks. Inside its template, `content_for 'blocks'` renders the current block's children. ```liquid theme={null}
{% content_for 'blocks' %}
{% schema %} { "name": "Card group", "blocks": [ { "type": "@theme" } ], "settings": [ { "type": "color_background", "id": "background", "label": "Background", "default": "#f4f7fb" } ], "presets": [ { "name": "Card group", "blocks": [ { "type": "heading" }, { "type": "button" } ] } ] } {% endschema %} ``` Fluid supports two levels of block nesting. Keep the hierarchy shallow so editors can understand and reorder it. ### Render a fixed block Use the singular `content_for 'block'` form for a block that belongs in a fixed position: ```liquid theme={null} {% content_for 'block', type: '_product_card', id: 'featured-product' %} ``` You can pass a nearby resource through the `closest` namespace: ```liquid theme={null} {% content_for 'block', type: '_product_card', id: 'featured-product', closest.product: product %} ``` The block can then read `closest.product`. This pattern is useful when the surrounding section controls the resource but the block controls its presentation. ## Add presets Presets provide initial settings and blocks when an editor adds a section or standalone block. They can also expose multiple configured variants in the picker. ```json theme={null} { "presets": [ { "name": "Primary button", "settings": { "style": "primary" } }, { "name": "Outline button", "settings": { "style": "outline" } } ] } ``` Add at least one preset when authors should be able to add the item from the editor. Use realistic defaults that produce a useful preview. ## Compare the options | Capability | Component | Inline block | Standalone theme block | | ------------------------ | ----------------------------- | ---------------------- | ----------------------- | | Own schema | No | In its section | Yes | | Editor-controlled | No | Yes | Yes | | Reusable across sections | Yes | No | Yes | | Render with | `render` | `section.blocks` | `content_for` | | Supports child blocks | Through component composition | No | Yes | | Best for | Repeated markup | Section-specific items | Reusable editor content | Use a component for rendering concerns. Use a block for editor-owned content. A standalone block can render a component when you need both behaviors. See [schema components](/themes/schema-components) for setting types and schema rules. See the [developer guide](/themes/developer-guide) for the complete theme structure.