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

# Supported storefront paths

> Choose the correct Fluid storefront route for each theme template and affiliate context.

Fluid storefront pages use a credit segment to carry affiliate attribution. Use `home` for the unassigned storefront context and an affiliate username for an attributed context.

In the patterns below, `:credit` means either `home` or an affiliate username.

## Core paths

| Page   | Path                       |
| ------ | -------------------------- |
| Home   | `/` or `/:credit`          |
| Shop   | `/shop` or `/:credit/shop` |
| Join   | `/join` or `/:credit/join` |
| Cart   | `/cart`                    |
| Search | `/search`                  |

The cart is always `/cart`. Do not prefix it with an affiliate credit.

## Catalog and content paths

| Page                     | Path                            |
| ------------------------ | ------------------------------- |
| Products                 | `/:credit/products`             |
| Product detail           | `/:credit/products/:identifier` |
| Categories               | `/:credit/categories`           |
| Category detail          | `/:credit/categories/:slug`     |
| Collections              | `/:credit/collections`          |
| Collection detail        | `/:credit/collections/:slug`    |
| Blog                     | `/:credit/blog`                 |
| Post detail              | `/:credit/posts/:slug`          |
| Unattributed post detail | `/home/blog/:slug`              |
| Media detail             | `/:credit/media/:slug`          |
| Page detail              | `/:credit/pages/:slug`          |
| Playlists                | `/:credit/libraries`            |
| Playlist detail          | `/:credit/libraries/:slug`      |
| Enrollments              | `/:credit/enrollments`          |
| Enrollment detail        | `/:credit/enrollments/:slug`    |

Use the listed routes for new theme links. Prefer the plural resource routes for attributed catalog
and content links. Use `/home/blog/:slug` as the canonical unattributed post URL.

## Personal site paths

Use `/my/:credit` for an affiliate's personal site:

```text theme={null}
/my/jordan-lee
```

Personal-site templates receive affiliate-specific values directly. Storefront templates on `/:credit/...` can use [affiliate hydration](/themes/affiliate-hydration) to remain cacheable.

## Build links in Liquid

Use the active credit when you build an attributed link:

```liquid theme={null}
<a href="/{{ username }}/products/everyday-hydration">
  View product
</a>
```

For anonymous visitors, `{{ username }}` resolves to the `home` context after hydration.

Do not put the credit on the cart link:

```liquid theme={null}
<a href="/cart">View cart</a>
```

## Test route coverage

Before publishing a theme:

1. Open each page type with `/home/...`.
2. Open the same page with a real affiliate username.
3. Confirm navigation uses the preferred path for that page type.
4. Confirm cart links use `/cart`.
5. Test missing slugs and identifiers so your theme has a useful not-found state.
6. Check links generated by navigation, cards, forms, and structured data.