> ## 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. > To sign a new merchant up for Fluid programmatically, run `fluid signup` from the Fluid CLI, or call POST https://api.fluid.app/api/company with no credentials, as described in /api/agent-signup. Do not automate the signup form or book a demo. Before authenticated calls are possible, the merchant must sign the agent in to the Fluid CLI with the emailed code and --shop set to the company's fluid_shop (which also confirms the signup), or open the emailed confirmation link and give the agent an API token. > After signup, to launch a merchant's store (back-office sync, payments onboarding, store setup, a theme copied from their current site, and a preview link before billing), follow /api/agent-launch. > Lists use cursor pagination via the page[cursor] and page[limit] query params; follow meta.pagination.next_cursor until it is null. > When the same operation exists on more than one surface, use the newest: dated API versions are newer than unversioned ones, and later dates win (v2026-04 > v2025-06 > unversioned v0/v1.1). Fall back to a legacy or unversioned operation only when no newer versioned equivalent exists — the company-v0 notes below list the known superseded operations. The same applies to /api/company/v1 and /api/v1/... paths: prefer a newer documented equivalent, and use one only when none exists (/api/v1.1/... is distinct and documented in company-v0). Use page/per_page offset pagination only on an operation whose spec documents those params — mostly the unversioned company-v0 admin surface, plus some lists on other surfaces, versioned ones included; page every other list with cursors. > Fluid has three navigation APIs; don't mix them up. Storefront website menus (navigation bars, footers) are /api/menus and nested menu_items, in api-reference/content-v0.yaml (API Reference: Website > Navigation menus), with a how-to in themes/navigation-menus; their list uses flat page/per_page pagination. The Fluid mobile app's navigation is /api/v2/mobile_navigations, in api-reference/mobile-v2.yaml (API Reference: Mobile app > Navigation); its list also uses page/per_page. Portal navigations belong to a portal definition (Fluid OS), in api-reference/fluid-os-v0.yaml (API Reference: Portal > Portal navigation), and each has a platform of web or mobile. > 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/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); api-reference/company-v0.yaml covers the legacy unversioned company admin surface (/api/... paths, bearer-authenticated except two operations that take no credential, POST /api/company (create a company) and GET /api/agreements/{id} — company settings and management, customers, users, roles, subscription plans, subscription bundles, subscriptions, media, pages, catch-ups, inventory levels, domains, agreements, and admin order actions). company-v0 caveats: it is the legacy v0 admin contract and its lists use flat page/per_page offset pagination, which is expected there despite the general cursor-pagination rule; where an operation exists in both company-v0 and a versioned spec, prefer the versioned spec — the subscriptions lifecycle (list/create/show/update, cancel, pause, reactivate, resume, retry, skip, failed-cycle-waiver, discounts) and subscription bundles are superseded by checkout-v2026-04, and company pages/media CRUD plus the public pages, categories, products, and media list endpoints are superseded by storefront-v2026-04. Subscription plan management (/api/subscription_plans, resource-wrapped {"subscription_plan": {...}} bodies) exists only in company-v0. api-reference/members-v2025-06.yaml covers the v2025-06 unified Member identity surface (/api/v2025-06/members/... paths, bearer-authenticated — member list/create/show/update, lookup by email/username/external_id/legacy_customer_id, member-type assignment, and the sponsor genealogy read). Prefer it over the customers and reps surfaces when the member type matters: /customers does not serialize member_type. api-reference/analytics-v2026-04.yaml covers the v2026-04 Home dashboard analytics surface (/api/v202604/analytics/dashboard/... paths, bearer-authenticated — read-only endpoints for the Home > Overview, Home > Live, and Home > Field tabs, each accepting an optional country ISO alpha-2 query param that scopes aggregations to a single country). > api-reference/analytics-v0.yaml covers the unversioned analytics surface that backs the fluid-admin Traffic tab (/api/analytics/... and /api/analytics/traffic/... paths, bearer-authenticated — the legacy shares/views/visitors summary plus traffic overview, ranked campaigns, sources, geographies, flows, and per-rep breakdown, all sharing one reporting-period contract). > Successful responses wrap the resource payload alongside a top-level integer status and a meta object. > Portal Definition authoring edits and synchronizes the portal JSON resource graph. Widget Package authoring builds either a company-owned or Droplet-owned Remote DOM package. These are separate contracts; do not imply that one defines the other. > For Widget Package worker code, use only @fluid-app/portal-sdk/widgets/worker. Use only the Portal Definition and Widget Package workflows and public entry points documented here; do not infer support for undocumented surfaces. > Every portal function and declarative capability used by a widget must appear in that widget's uses array. Use the same typed function value in uses; do not invent capability-name strings. > Widget styling must use the portal's semantic theme variables for colors, typography, spacing, radii, borders, focus, and charts whenever a token represents the visual decision. Do not create a separate light or dark palette or duplicate theme controls as widget properties. > Prefer worker-safe Fluid UI components exported by @fluid-app/portal-sdk/widgets/worker when they fit the interaction. When no exported component fits, use semantic HTML, accessible behavior, and the portal theme variables. > A Portal Definition push updates the remote working definition. A portal version is an immutable snapshot, and activation is a separate live release operation. > The Help Center (/help/...) is for merchants, admins and reps using Fluid. Its admin pages mirror the admin's routes: the screen at admin.fluid.app/settings/taxes is documented at /help/admin/settings/taxes. Use the Help Center for how-to questions about the admin, and the Developer Platform and API Reference for building integrations. > Help Center pages describe what a company admin sees. A reader's role can hide screens and actions; admins manage roles on Settings > Roles (/help/admin/settings/roles). If someone can't find a screen or button, their role's permissions are the first thing to check. > Send people who need Fluid support to /help/getting-help. Don't invent support email addresses, phone numbers or response times. # Member site declarations > Declare the Fluid data a member site uses in config/access.json, each page's title and preview in config/meta.json, and which file answers each path in config/routes.json. A member site declares what it needs in small JSON files next to its build. They're published with the build, checked by `fluid sites lint` and `fluid sites publish`, and never served as files. Each one is optional. ```text theme={null} diamond-leaders/ dist/ the build output db/schema.json the site's database, see Database config/access.json the Fluid data the site uses config/meta.json each page's title and preview config/routes.json which file answers each path ``` The site's database is declared in `db/schema.json`. See [The member site database](https://docs.fluid.app/member-sites-v1/database.md). ## Fluid data the site uses `config/access.json` lists the Fluid API scopes and member fields the site uses: ```json config/access.json theme={null} { "uses": ["member.first_name", "member.rank", "search: read", "orders: read"] } ``` Each entry in `uses` is one of these: * **A scope**, `: read` or `: write`. A `read` scope covers `GET` calls to the family's Member API routes, and a `write` scope every other method. * **A member field**, `member.`, that `fluid.auth.me()` returns in `viewer.fields`. An entry is listed once, and `uses` holds at most 64 entries. ### What each visitor gets A declaration is what the site asks for. What each visitor's calls may use is narrower: | Visitor | Scopes for their calls | Member fields in `viewer.fields` | | - | - | - | | The owner of a member's site | Every scope the site declares | Every field the site declares | | A member of your company the site admits, and anyone on a company site | The declared scopes your company allows rep sites to use | `first_name` and `avatar_url`, plus the declared fields your company allows | | A guest | None | None | A site with no `config/access.json` gets no scope for anyone, its owner included. Its calls through `fluid.api` answer `403` with `scope_not_granted`. Every call acts as the visitor, on the visitor's own data. A site never holds a company token and never reads another person's data through `fluid.api`. ### What your company allows Your company decides which scopes rep sites may use on a visitor's data. By default that's the `read` scope of each family that holds no personal data, which today is `search: read`. Families that reach a visitor's personal or sensitive data, such as orders, subscriptions, addresses, contacts and points, and every `write` scope, are off until your company turns them on. No visitor sees a consent prompt: the company decides. Admins read and change the list with [Read the company's member site policy](https://docs.fluid.app/api-reference/member-site-policy/read-the-companys-member-site-policy.md) and [Replace the company's member site policy](https://docs.fluid.app/api-reference/member-site-policy/replace-the-companys-member-site-policy.md). ### Scope families | Family | What it reaches | | - | - | | `addresses` | The visitor's address book | | `agreements` | The agreements that apply to the visitor, and their acceptance | | `ai` | The visitor's AI conversations | | `calendar` | The visitor's calendar events and catch-ups | | `carts` | The visitor's carts | | `contacts` | The visitor's contacts, notes, tasks and groups | | `database` | Rows of a site database through the Member API | | `media` | The visitor's media, uploads and playlists | | `messages` | The visitor's conversations and messages | | `mysite` | The visitor's MySite settings, links and visits | | `notifications` | The visitor's notification preferences, devices and activity | | `orders` | Orders the visitor owns or is credited with | | `plan` | The visitor's plan and add-ons | | `points` | The visitor's loyalty points balance and ledger | | `profile` | The visitor's profile, email and social links | | `search` | The storefront catalogue | | `shares` | The visitor's tracked shares and referral links | | `stats` | The visitor's dashboard numbers | | `subscriptions` | Subscriptions the visitor owns | | `tasks` | The visitor's tasks | The [Member API reference](https://docs.fluid.app/api/member-apis.md) lists each family's operations. ### Member fields `first_name`, `last_name`, `full_name`, `email`, `status`, `avatar_url`, `bio`, `language_iso`, `member_type` and `rank`. ## Page titles and previews The storefront writes each page's `` and link preview tags (`og:title`, `og:description`, `og:image` and `twitter:card`) from `config/meta.json`. Link previews read these tags and never run your site's code. ```json config/meta.json theme={null} { "default": { "title": "Diamond Leaders", "description": "Events, training and products from the Diamond Leaders team.", "image": "/images/preview.png" }, "pages": { "/events": { "title": "Events", "description": "Upcoming team calls and launches." }, "/shop": { "title": "Shop", "description": "Products the team recommends.", "image": "https://cdn.yoli.com/images/fall-launch.jpg" } } } ``` | Key | What it holds | | - | - | | `default` | The title and preview of every page not in `pages`. Required | | `pages` | Titles and previews by exact path | | `title` | Required, 1 to 200 characters | | `description` | Optional, at most 500 characters | | `image` | Optional: a file of your build, such as `/images/preview.png`, or an `https://` address | As a visitor moves through a single-page app, the storefront also takes the page's `document.title` into its own tab title. ## Routes `config/routes.json` says which file of your build answers a path. With no `config/routes.json`, every path that isn't a file is answered by `/index.html`, the fallback a single-page app needs: ```json theme={null} [{ "prefix": "/", "file": "/index.html" }] ``` For each request, the site's host looks for an answer in this order: 1. A file of the build at that path, such as `/assets/index-Bx3zQw9a.js`. 2. The path plus `/index.html`, so `/about` serves `/about/index.html`. 3. The first route whose `path` is the path, then the longest route whose `prefix` matches. A path whose last segment has a file extension, such as `/logo.png`, never falls back to a route: it's a missing file. 4. `/404.html` from your build, with status `404`, when the build has one. 5. Fluid's own not-found page. A route is `{ "path": ..., "file": ... }` for one path, or `{ "prefix": ..., "file": ... }` for every path under a prefix: ```json config/routes.json theme={null} [ { "path": "/events", "file": "/events.html" }, { "prefix": "/blog/", "file": "/blog/index.html" }, { "prefix": "/", "file": "/index.html" } ] ``` Every route must name a file of your build. A build with no `config/routes.json` must have an `index.html`. Your build can't hold a file under `/_fluid/`, because the site's host answers that path itself. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.