> ## 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, 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. The merchant must open the emailed sign-in link and create an API token before authenticated calls are possible. > 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. /api/company/v1 and /api/v1/... paths are documented in no spec here and must never be used (/api/v1.1/... is distinct and documented in company-v0). Use page/per_page offset pagination only where a spec documents it — in practice the unversioned company-v0 admin surface; every versioned surface uses cursor pagination. > Navigation menu management is documented in themes/navigation-menus. These unversioned admin endpoints (/api/menus and nested menu_items) are verified against the implementation but are not yet in the synced OpenAPI specs. Use that reference for menu payloads and its flat page/per_page pagination; missing spec coverage does not make these endpoints unavailable. > 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 — 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. # Domains > Add custom domains, track their DNS and SSL status, and manage subdomains, redirects, your primary domain, and trusted payment hosts. Use the Domains screen to add domains you own to Fluid and follow each one from setup until it's live. Each domain also has its own page. ## Where to find it In the admin, click the **Settings** gear in the top bar. In the Settings sidebar, under **System**, select **Domains**. To open the screen, your role needs at least **View only** for **Domains**, in the **Settings** card. To add or change domains, subdomains, redirects or trusted hosts, it also needs the **Edit domain configuration** switch. Deleting a domain also needs **Remove custom domains**. See [Roles](/help/admin/settings/roles). ## What's on the screen The Domains screen has a **Connect Domain** button at the top, the **External payment redirects** card, and a table of your domains. ### External payment redirects The **External payment redirects** card limits where customers can return after an external payment flow. Company-owned domains are already trusted, so add only external storefront hosts that aren't managed on this screen. A redirect to any other host falls back to Fluid Checkout. * **Additional trusted hosts**: Enter one exact hostname per line, such as `shop.example.com`. Don't include a protocol, port, path, query, wildcard, or credentials, and list each subdomain on its own line. IP addresses aren't accepted. * **Save hosts**: Saves the list. Changes apply to this company only. ### Domains table The table lists each domain that has its own SSL certificate, usually your root domains such as `example.com`. The `www` version and subdomains you add with **Add Subdomain** share their root domain's certificate, so they don't appear in the table. Open them from the root domain's **Subdomains** card, which appears once the root domain is **Verified** or **Connected**. Use the **All**, **Connected**, **Verified**, **Pending**, and **Failed** tabs to filter by status, or search by domain name. The table has these columns: * **Domain**: The domain name. A **Primary** badge marks your primary domain. A subdomain in the table shows **Subdomain of** and its root domain. * **Redirects to**: The domain this one sends visitors to, if you set a redirect. * **Status**: How far the domain is through setup. Each status means: * **Pending**: Fluid hasn't verified that you own the domain yet. * **Verified**: Ownership is confirmed, but the domain doesn't point to Fluid yet. * **Connected**: The domain points to Fluid and is live. * **Setup Failed**: A setup step failed. These domains show under the **Failed** tab. Open the domain to see why. Click a row, or choose **Edit** from the row's menu, to open that domain's page. The row menu also has **Delete**. ### Add a domain dialog **Connect Domain** opens the **Add a domain** dialog. It has a field for the domain you want to add, such as `example.com`, and: * **Also add `www.example.com` (recommended)**: This checkbox appears for a two-part domain such as `example.com`. It adds the `www` version as a second domain. * **Continue**: Adds the domain. If you type `www.example.com`, the dialog changes it to `example.com` and checks **Also add `www.example.com` (recommended)**. ## What's on a domain's page A domain's page shows its name and status badge, plus a **Primary** badge if it's your primary domain. A subdomain shows **Subdomain of** with a link to its root domain, and a redirected domain shows **Redirects to**. ### Page buttons The top of the page has these buttons: * **Make Primary**: Makes this your primary domain. It appears once the domain is **Connected** and isn't already primary. * **Visit Site**: Opens the domain in a new tab. It appears once the domain is **Connected**. * **Actions**: Opens a menu with **Delete**. ### Setup cards Until the domain is **Connected**, its page shows one setup step at a time. The **Verify Ownership** card shows a CNAME record, with its **Type**, **Name**, and **Value**, to add at your DNS provider. Each value has a copy button. **Verify DNS** starts the ownership check, which can take a few minutes. Once ownership is verified, a **Domain ownership confirmed** banner replaces that card. It says your current site is unaffected and that you can go live now or test on a subdomain first. Click **Connect this domain** to show the **Configure DNS Records** card. The **Configure DNS Records** card lists the DNS records that point your domain to Fluid, each with a copy button. **Verify DNS** checks them. The card then says whether DNS is pointing to Fluid yet and, if it isn't, compares the expected record with the records it found. Each setup card also says Cloudflare records must be DNS-only (not proxied). The `www` version and subdomains you add with **Add Subdomain** share their root domain's SSL certificate. They skip **Verify Ownership**, because the root domain handles ownership, and open on the **Domain ownership confirmed** banner. They can't connect until the root domain's ownership is verified. After you click **Verify DNS**, and while a **Verified** domain waits for its DNS records, the page rechecks the status every 10 seconds. If a step fails, the card explains what went wrong and shows a **Check Status** button that retries it. ### Connected domain cards Once the domain is **Connected**, these cards replace the setup cards: * **DNS Records**: The records that point your domain to Fluid. * **SSL Certificate**: Shows **Active**. Fluid renews your SSL certificate automatically. ### Subdomains card A root domain that's **Verified** or **Connected** also has a **Subdomains** card: * The table lists this domain's subdomains, including its `www` version, with their **Certificate** (**Shared via** and the domain whose certificate it uses, or **Own cert**) and **Status**. Click a subdomain to open its page. * **Add Subdomain**: Opens the **Add a subdomain** dialog. * **Wildcard Subdomains**: Gives each Fair Share rep their own subdomain, such as `jane.example.com`. Fluid manages these subdomains, so they need no DNS setup. The toggle appears once the domain is **Connected**, and turning it on or off saves right away. ### Redirect card Every domain page has a **Redirect** card. **Origin** shows this domain. **Redirect to** lists **Do not redirect** and the other domains in the Domains table that don't redirect themselves. ## Add a domain Click **Connect Domain** at the top of the Domains screen. Enter a domain you own, such as `example.com`. For a two-part domain, the **Also add `www.example.com` (recommended)** checkbox is checked by default. Leave it checked to add the `www` version too. Click **Continue**. A message tells you to follow the DNS steps to verify the domain. Click the domain in the table. Its **Verify Ownership** card shows the CNAME record to add and a **Verify DNS** button. If the card shows **Setting up domain verification...** instead, reload the page to see the record. A subdomain of a root domain you already added isn't in the table: open it from the root domain's **Subdomains** card. ## Make a domain primary Click a domain whose status is **Connected**. Click **Make Primary** at the top of the page. In the **Make this your primary domain?** dialog, click **Make Primary**. The domain becomes the default domain for your site right away, and your previous primary domain becomes a secondary domain. ## Redirect a domain Click the domain you want to redirect. In the **Redirect** card, open **Redirect to** and choose another of your domains. The change saves as soon as you choose it. To stop redirecting, choose **Do not redirect**. A domain that other domains redirect to can't redirect itself. ## Add a subdomain Click a root domain, such as `example.com`, whose status is **Verified** or **Connected**. In the **Subdomains** card, click **Add Subdomain**. In the **Add a subdomain** dialog, enter the part that goes before your domain, such as `shop` for `shop.example.com`. Use only letters, numbers, and hyphens. Click **Continue**. The subdomain appears in the **Subdomains** card. Click it to open its page. ## Delete a domain You can't delete your primary domain, or a root domain whose `www` version or subdomain is your primary domain. Make another domain primary first. In the Domains table, open the domain's row menu and choose **Delete**. Or, on the domain's page, choose **Actions**, then **Delete**. For a `www` version or subdomain, open it from the root domain's **Subdomains** card, then choose **Actions**, then **Delete**. Click **Remove**. You can't undo this. ## FAQ No. The ownership record on the **Verify Ownership** card doesn't change your site. Your site changes only when you add the records on the **Configure DNS Records** card, which point your domain to Fluid, and you choose when to do that. The ownership check can take a few minutes, and the **Connect this domain** button estimates about 5 minutes to connect. Fluid creates the SSL certificate during the ownership check, so it's ready by the time the domain is connected. The domain's status changes to **Setup Failed**, and the setup card explains what went wrong. For example, the CNAME record may not match, or the domain may not point to Fluid yet. **Check Status** runs the check again. Some failures are temporary and clear on a retry. If it keeps failing, contact support. Email Fluid support at [help@fluid.app](mailto:help@fluid.app). The [Getting help](/help/getting-help) page lists what to include in your request. The Domains screen doesn't let you rename a domain. To use a different domain, add it with **Connect Domain**. ## Related pages * [Settings](/help/admin/settings) * [Fair Share](/help/admin/settings/fair-share): how commission is attributed for rep links * [FairShare: sales rep attribution](/concepts/fair-share): how the FairShare SDK attributes sales to reps * [Roles](/help/admin/settings/roles)