> ## 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.

# Use Liquid theme variables

> Reference the global and template-scoped Liquid data available while Fluid renders a storefront theme.

Fluid supplies global variables and template-scoped variables when it renders Liquid.
Global variables describe the storefront, request, localization, attribution, and shared resources.
Template variables describe the resource or experience being rendered.

Use this reference to choose the correct scope before you build a section.

## Understand variable scope

Global variables are available to rendered storefront templates.
Template variables are available only in their matching context.
For example, `product` is available in a product template, while `post` is available in a post template.

An unavailable value renders blank.
Guard optional values and arrays before you use them:

```liquid theme={null}
{% if product and product.images.size > 0 %}
  <img
    src="{{ product.images.first.src }}"
    alt="{{ product.title | escape }}"
  >
{% endif %}
```

Use `default` for presentation fallbacks:

```liquid theme={null}
<h1>{{ product.title | default: 'Featured product' }}</h1>
```

Do not use a fallback to hide a misspelled field.
Confirm the variable's context and name first.

## Global variables

The following top-level values are shared across rendered storefront templates.
Some values can still be blank when the current visitor or company does not provide the underlying data.

| Variable                | Useful fields                                                                                                                        |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `company`               | `id`, `name`, `logo_url`, `base_url`, `home_page_url`, `shop_page_url`, `join_page_url`, `checkout_url`, social URLs, `points_label` |
| `request`               | `path`, `host`, `full_url`, `page_type`, `query_parameters`                                                                          |
| `localization`          | `country`, `language`, `available_countries`, `available_languages`, `market`                                                        |
| `country`               | The active country value                                                                                                             |
| `affiliate`             | `name`, `email`, `avatar`, `initials`, `my_site_url`, sign-in state, and hydration state                                             |
| `username`              | The attributable storefront handle or its hydration sentinel                                                                         |
| `sharing_id`            | The affiliate sharing identifier                                                                                                     |
| `external_id`           | The affiliate's configured external identifier                                                                                       |
| `share_guid`            | The current share attribution value                                                                                                  |
| `affiliate_guid`        | The affiliate handle used by attributable links                                                                                      |
| `routes`                | `root_url`, `cart_url`, `collections_url`                                                                                            |
| `privacy_policy_path`   | Storefront privacy-policy path                                                                                                       |
| `terms_conditions_path` | Storefront terms-and-conditions path                                                                                                 |
| `library_navigation`    | Current library navigation state and adjacent item URLs                                                                              |
| `products`              | On-demand product collection                                                                                                         |
| `collections`           | On-demand collection collection                                                                                                      |
| `categories`            | On-demand category collection                                                                                                        |
| `enrollment_packs`      | On-demand enrollment-pack collection                                                                                                 |
| `posts`                 | On-demand post collection                                                                                                            |
| `most_popular_posts`    | On-demand popular-post collection                                                                                                    |
| `settings`              | Values from the theme's root settings                                                                                                |

`navbar`, `footer`, and `sections` are also assembled for the current template.
Use their settings within the corresponding theme structure.

<Note>
  On-demand resource collections are not populated for static content renders.
  Test a resource loop in a rendered storefront context.
</Note>

### Company points labels

Use `company.points_label.singular` and `company.points_label.plural` instead of hard-coding a rewards label.
Product and variant values also expose the same pair where points data appears.

```liquid theme={null}
{% if product.points == 1 %}
  Earn 1 {{ company.points_label.singular }}.
{% else %}
  Earn {{ product.points }} {{ company.points_label.plural }}.
{% endif %}
```

Select the singular or plural form yourself.
The value does not choose a form based on the number.

### Affiliate hydration

Cached storefront HTML can contain sentinel values that the FairShare client replaces after it resolves attribution.
Do not treat `affiliate.name` as a reliable server-rendered sign-in check.

Use `affiliate.logged_in_rep_for_store` for the sign-in state.
See [affiliate hydration](/themes/affiliate-hydration) before you branch on affiliate fields or build attributable URLs.

### Localization

`localization.country` is the selected country object.
`localization.language` is the selected language object.
The available collections include display names, ISO codes, and selection state.
Country entries also include currency details.

```liquid theme={null}
<html lang="{{ localization.language.iso_code | default: 'en' }}">
```

## Product template

Use `product` for the current product.

| Group           | Fields                                                                                                            |
| --------------- | ----------------------------------------------------------------------------------------------------------------- |
| Identity        | `id`, `sku`, `title`, `url`, `active`, `tags`                                                                     |
| Content         | `short_description`, `description`, `feature_text`, `metadata`, `metafields`, `metafields_collection`             |
| Pricing         | `price`, `unit_price`, `subscription_price`, `unit_subscription_price`, savings fields, points-label fields       |
| Availability    | `available_for_country`, `out_of_stock`, `limited_stock`, `buyable_quantity`                                      |
| Media           | `images`, `media`, `featured_media`, `thumbnail_image`                                                            |
| Options         | `available_values`, `options_available`, `options_with_values`, `variants`, `selected_or_first_available_variant` |
| Subscriptions   | `allow_subscription`, `subscription_only`, `subscription_plans`, `selected_subscription_plan_id`                  |
| Recommendations | `recommendations`                                                                                                 |
| Bundles         | `bundle_config`, `product_bundles`, `product_bundle_groups`, `track_inventory_on_bundle_items`                    |

Images expose fields such as `id`, `src`, `url`, `position`, and `media_type`.
Variants include identity, availability, selected option values, localized pricing, images, and points labels.
Bundle groups include their selection constraints, pricing configuration, images, and items.

```liquid theme={null}
<article>
  <h1>{{ product.title }}</h1>
  <p>{{ product.price }}</p>

  {% for image in product.images %}
    <img src="{{ image.src }}" alt="{{ product.title | escape }}">
  {% endfor %}
</article>
```

## Shop template

Use these values in `shop_page` templates:

| Variable       | Contents                                             |
| -------------- | ---------------------------------------------------- |
| `collection`   | Product results, filter groups, and sort choices     |
| `products`     | Compact product summaries for the current result set |
| `options`      | Product-option summaries and selected values         |
| `categories`   | Category choices, counts, and selection state        |
| `price_ranges` | Price choices, display values, and selection state   |
| `url`          | Attributable shop URL                                |
| `search_query` | Active search text                                   |
| `sorted_by`    | Active sort value                                    |

Each `collection.filters` entry includes its label, selection values, input name, presentation, and add or remove URLs.
Use the supplied URLs instead of reconstructing filter query strings.

## Collection template

Use `collection` for the current collection.

| Field         | Description                         |
| ------------- | ----------------------------------- |
| `id`          | Collection identifier               |
| `handle`      | Collection handle                   |
| `title`       | Collection title                    |
| `description` | Collection description              |
| `image`       | Collection image                    |
| `url`         | Attributable collection URL         |
| `products`    | Products assigned to the collection |

```liquid theme={null}
<section>
  <h1>{{ collection.title }}</h1>
  {% for item in collection.products %}
    <a href="{{ item.url }}">{{ item.title }}</a>
  {% endfor %}
</section>
```

## Home template

Use these values in `home_page` templates:

| Variable       | Description                                                           |
| -------------- | --------------------------------------------------------------------- |
| `base_url`     | Storefront base URL                                                   |
| `logo_url`     | Company logo or the default logo                                      |
| `shop_url`     | Attributable shop URL                                                 |
| `all_products` | On-demand product collection retained for home-template compatibility |

Prefer the global `products` collection for new product loops.

## Join template

Use these values in `join_page` templates:

| Variable                                | Description                                           |
| --------------------------------------- | ----------------------------------------------------- |
| `url`                                   | Attributable join URL                                 |
| `collection.enrollment_packs`           | Enrollment packs available in the join experience     |
| `collection.enrollment_packs_count`     | Number of enrollment packs in the rendered result set |
| `collection.all_enrollment_packs_count` | Number of matching enrollment packs                   |
| `search_query`                          | Active search text                                    |
| `sorted_by`                             | Active sort value                                     |

Each entry in `collection.enrollment_packs` uses the enrollment-pack shape described below.

## Medium template

Medium templates expose the medium fields at the top level.

| Group    | Fields                                                                                                 |
| -------- | ------------------------------------------------------------------------------------------------------ |
| Identity | `id`, `title`, `kind`, `description`, `poster`                                                         |
| Media    | `embed_url`, `video_url`, `pdf_url`, `image_url`, `powerpoint_url`                                     |
| Actions  | `cta_url`, `cta_button_text`, `shop_path`, `learn_more_path`                                           |
| Comments | `display_comments`, `comment_visibility`, `comment_submit_url`, `contact`, `comments`                  |
| Behavior | `display_shop`, `lead_captureable`, `visitable_on_click`, `video_shopping_enabled`, `video_status_url` |
| Sharing  | `social_media`                                                                                         |

Check `kind` before selecting a media-specific URL:

```liquid theme={null}
{% case kind %}
  {% when 'video' %}
    <video controls poster="{{ poster }}" src="{{ video_url }}"></video>
  {% when 'image' %}
    <img src="{{ image_url }}" alt="{{ title | escape }}">
  {% endcase %}
```

## Enrollment-pack template

Use `enrollment_pack` for the current enrollment pack.

| Group        | Fields                                                                |
| ------------ | --------------------------------------------------------------------- |
| Identity     | `id`, `title`, `url` when supplied                                    |
| Content      | `description`, `images_array`                                         |
| Pricing      | `price` when supplied, `enrollment_fee`, `enrollment_fee_in_currency` |
| Availability | `available_for_country` when supplied                                 |
| Products     | `membership_products`, `subscription_products`                        |
| Timing       | `membership_after_one_month`, `first_payment_date`                    |
| Agreements   | `agreements`                                                          |

Membership and subscription product entries include display values, product options, and bundle information where applicable.
Agreement entries include `id`, `title`, `description`, and `required`.

## Library template

Library templates expose:

| Variable             | Description                                                        |
| -------------------- | ------------------------------------------------------------------ |
| `id`                 | Library identifier                                                 |
| `title`              | Library title                                                      |
| `library_items`      | Product, enrollment-pack, and medium cards                         |
| `active_product_ids` | Active product variant identifiers for the current library context |
| `social_media`       | Company sharing URLs                                               |
| `contact`            | Current contact details when available                             |
| `comments`           | Visible comments                                                   |
| `comment_submit_url` | Comment submission URL                                             |

Every library item includes `id`, `type`, `title`, `description`, `image`, and `url`.
Product items add `product`, pricing fields, and enrollment items add `enrollment_pack`.
Medium items add `kind` and the matching media URLs.

## My Site template

Use `fluid_affiliate` in `mysite` templates.

| Group         | Fields                                                                                                                                     |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Profile       | `name`, `bio`, `image`                                                                                                                     |
| Social links  | `facebook_url`, `twitter_url`, `instagram_url`, `linkedin_url`, `youtube_url`, `tiktok_url`, `pinterest_url`, `whatsapp_url`, `wechat_url` |
| Custom links  | `links` with `text` and `url`                                                                                                              |
| Display cards | `my_site_displayables`                                                                                                                     |

Each display card identifies the saved item and contains a `favoriteable` object.
The nested object provides common card content plus resource-specific URLs, pricing, or media fields.

## Cart template

Use `cart` in `cart_page` templates.

| Group      | Fields                                                                                                       |
| ---------- | ------------------------------------------------------------------------------------------------------------ |
| Identity   | `id`, `cart_token`, `email`                                                                                  |
| Currency   | `currency_code`, `currency_symbol`                                                                           |
| Amounts    | `sub_total`, `discount_total`, `shipping_total`, `tax_total`, `amount_total`, plus formatted currency values |
| Enrollment | `enrollment_fee`, `enrollment_fee_in_currency`                                                               |
| Volume     | `cv_total`                                                                                                   |
| Lines      | `items`                                                                                                      |
| Checkout   | `checkout_url`                                                                                               |

Cart items contain the line's resource, quantity, pricing, and option data supplied to the storefront cart.
Guard optional product or enrollment-pack details because the item shape depends on its resource.

## Post template

Use `post` for the current post.

| Group            | Fields                                                 |
| ---------------- | ------------------------------------------------------ |
| Identity         | `title`, `slug`, `preview_url`, `active`               |
| Content          | `description`, `summary`, `image_url`                  |
| Dates and author | `created_at`, `updated_at`, `post_date`, `post_author` |
| Taxonomy         | `category`, `collections`                              |

Category and collection summaries include `id`, `title`, `description`, and `image_url`.

## Use variables from schema settings

Resource settings resolve saved identifiers into Liquid values.
For example, a `product` setting makes the selected product available at `section.settings.featured_product`.

```liquid theme={null}
{% assign featured_product = section.settings.featured_product %}

{% if featured_product %}
  <a href="{{ featured_product.url }}">
    {{ featured_product.title }}
  </a>
{% endif %}
```

Use the setting ID as the key under `section.settings` or `block.settings`.
See [schema components](/themes/schema-components) for supported resource setting types.