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

# Hydrate affiliate details in a cached theme

> Render affiliate names, images, links, and conditional content safely in cacheable Fluid themes.

Affiliate hydration lets one cacheable storefront page work for both attributed and anonymous visitors. Your Liquid template emits a stable placeholder. The FairShare SDK replaces that placeholder in the browser after it resolves the visitor's affiliate.

Use the placeholder that matches where the value appears:

| Context                   | Use                               |
| ------------------------- | --------------------------------- |
| Visible text              | A `<fluid-affiliate-*>` element   |
| A complete HTML attribute | A `data-fluid-affiliate-*` marker |
| A username inside a URL   | The `{{ username }}` Liquid value |

## Render affiliate text

Fluid provides five affiliate elements:

| Element                         | Value                     |
| ------------------------------- | ------------------------- |
| `<fluid-affiliate-name>`        | Display name              |
| `<fluid-affiliate-email>`       | Email address             |
| `<fluid-affiliate-initials>`    | Initials                  |
| `<fluid-affiliate-avatar>`      | Avatar URL as text        |
| `<fluid-affiliate-my-site-url>` | Personal site URL as text |

Put fallback text inside an element. Fluid keeps that text when the field is empty during the
initial affiliate resolution.

```html theme={null}
<p>
  Shop with <fluid-affiliate-name>our team</fluid-affiliate-name>
</p>
```

These elements render in the light DOM, so your theme styles apply normally.

## Hydrate HTML attributes

Use a data marker when the affiliate value needs to become an HTML attribute:

```html theme={null}
<img
  data-fluid-affiliate-src="avatar"
  data-fluid-affiliate-alt="name"
  alt="Your shopping guide"
/>

<a data-fluid-affiliate-href="my_site_url">
  Visit your guide's site
</a>
```

The supported markers are:

| Marker                                | Result             |
| ------------------------------------- | ------------------ |
| `data-fluid-affiliate="<field>"`      | Sets `textContent` |
| `data-fluid-affiliate-src="<field>"`  | Sets `src`         |
| `data-fluid-affiliate-href="<field>"` | Sets `href`        |
| `data-fluid-affiliate-alt="<field>"`  | Sets `alt`         |

`<field>` can be `name`, `email`, `initials`, `avatar`, `my_site_url`, or `username`.

For `my_site_url`, you can set `data-fluid-affiliate-base-url` on the same element to use a different origin:

```html theme={null}
<a
  data-fluid-affiliate-href="my_site_url"
  data-fluid-affiliate-base-url="https://shop.example.com"
>
  Visit your guide's site
</a>
```

Use a data marker for eagerly loaded attributes such as image `src`. A browser can request a literal placeholder before hydration if you put one directly in `src`.

## Put an affiliate username in a URL

Use `{{ username }}` when the affiliate username is one part of a link or form URL:

```liquid theme={null}
<a href="/{{ username }}/shop">Shop</a>
<form action="/{{ username }}/join" method="get">
  <button type="submit">Join</button>
</form>
```

Fluid renders a stable sentinel into the cacheable page. The SDK replaces every sentinel with the resolved username. Anonymous visitors fall back to `home`.

Use the sentinel in attributes that the browser follows after user interaction, such as `href` and
`action`. For an eagerly fetched image source, use `data-fluid-affiliate-src`; the hydration API
does not provide generic `srcset` or `poster` markers.

## Show content conditionally

Liquid conditions run before the browser resolves the affiliate. Use hydration visibility markers for affiliate-dependent content:

```html theme={null}
<aside
  data-fluid-affiliate-show-if="affiliate"
  style="display: none"
>
  Shopping with
  <fluid-affiliate-name>your guide</fluid-affiliate-name>
</aside>

<aside data-fluid-affiliate-hide-if="affiliate">
  Shop with the Fluid community
</aside>
```

Use `affiliate` to test whether any affiliate resolved. You can also test a specific field such as `avatar` or `email`.

`data-fluid-affiliate-show-if` requires every comma-separated token to have a value. `data-fluid-affiliate-hide-if` hides the element when any listed token has a value. If both markers are present, the hide condition wins.

Pre-hide `show-if` content with `style="display: none"` to prevent a flash before hydration.
If an SPA changes affiliates without replacing the element, do not rely on `hide-if` alone to reveal
content that it previously hid. Re-render that conditional region when the attribution changes.

## React to hydrated content

Hydration happens after the initial HTML is parsed. If your script measures or copies hydrated content, observe the element instead of reading it immediately:

```html theme={null}
<div
  id="affiliate-banner"
  data-fluid-affiliate-show-if="affiliate"
  style="display: none"
>
  <fluid-affiliate-name></fluid-affiliate-name>
</div>

<script>
  const banner = document.getElementById("affiliate-banner");

  const syncBannerHeight = () => {
    const visible = window.getComputedStyle(banner).display !== "none";
    document.documentElement.style.setProperty(
      "--affiliate-banner-height",
      visible ? `${banner.offsetHeight}px` : "0px",
    );
  };

  new MutationObserver(syncBannerHeight).observe(banner, {
    attributes: true,
    attributeFilter: ["style"],
    childList: true,
    subtree: true,
    characterData: true,
  });

  syncBannerHeight();
</script>
```

There is no public `rescanForSentinels()` method. Hydration reapplies when FairShare publishes an
affiliate settings change and scans the current document again. In an SPA, render the destination
content before that settings update. Prefer the custom elements for text that must continue reacting
after the affiliate changes.

## Test your theme

Test both attributed and anonymous paths:

1. Open a supported storefront path with an affiliate username.
2. Confirm text, images, links, and conditional regions resolve.
3. Open the equivalent path with `home`.
4. Confirm fallback content remains usable and no affiliate-only region flashes.
5. Test a second affiliate to catch values that were copied only once.
6. Check keyboard focus, image alternative text, and screen-reader output after hydration.

See [supported storefront paths](/themes/supported-paths) for route patterns and [FairShare components](/sdk/components) for the SDK component inventory.