> ## 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. > 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 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. > 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. # Sitemap > Control your storefront's XML sitemap, choose which URLs it lists, and create custom routes and country-specific routes that keep reps' links working. Use the Sitemap screen to see your storefront's URLs, control what search engines find at `/sitemap.xml`, and add your own routes. A route can show a product, a page, or a template at an address you choose, or send visitors somewhere else, and it can do something different for each country. A non-credited route can break reps' shared links and collide with a rep's username. Read [Rep credit](#rep-credit) before you create a route for a URL that reps or customers share. ## Where to find it In the admin sidebar, under **Platforms**, click **Website** > **Sitemap**. If you don't see the **Search Engine Visibility** card, **Create Custom Route**, or the row switches, your role can view the sitemap but not change it. See [Roles](/help/admin/settings/roles). ## What's on the screen The top of the screen has these buttons: * **Theme:** Picks whose routes you see and edit. It starts on your active theme, marked **(Active)**. Choose **Reset to active theme** to go back. Only routes on your active theme reach visitors. * **View Sitemap**: Opens your live `/sitemap.xml` in a new tab. * **Create Custom Route**: Opens the drawer for a new route. See [Create a custom route](#create-a-custom-route). Below them are the **Search Engine Visibility** card and the route list: * **Viewing for:** Shows **All countries**, or only the routes that have a country route for the country you pick. * **Table** and **Structure**: Switch between a searchable, filterable table and a tree of your URLs. **Structure** isn't available when the theme has more than 10,000 routes. * Each table row shows the URL's **Path**, its **Country Routes**, and an **Include in Sitemap** switch. Click a row to open it. * Select rows to delete routes. New products, pages, and other content can take up to five minutes to appear in the list. ## Your sitemap Fluid publishes your sitemap at `/sitemap.xml` on every storefront domain your company uses, such as `https://acme.fluid.app/sitemap.xml` or `https://www.example.com/sitemap.xml`. `/sitemap.xml` is an index. It links to one sitemap for each kind of content that has something to list: `/sitemap-static.xml` for your home, shop, and join pages, then `/sitemap-pages.xml`, `/sitemap-products.xml`, `/sitemap-media.xml`, `/sitemap-enrollments.xml`, `/sitemap-categories.xml`, `/sitemap-collections.xml`, `/sitemap-posts.xml`, `/sitemap-libraries.xml`, and `/sitemap-custom.xml` for custom routes. What the sitemap lists: * **Every URL uses your primary domain.** If you have a connected primary domain, the sitemap uses it. Otherwise it uses `https://.fluid.app`. See [Domains](/help/admin/settings/domains). * **Content uses its `/home/` address**, the one with no rep in it, such as `/home/products/beet-blend`. Posts use `/home/blog/`. * **Only live content that search engines may index.** Drafts, scheduled items that haven't gone live, and items whose SEO settings block search engines are left out. * **Only routes on your active theme.** Your storefront also serves `/robots.txt`. It lets search engines crawl every page and points them to your sitemap. ## Search Engine Visibility The **Search Engine Visibility** switch is on by default. When you turn it off: * `/sitemap.xml` and every sitemap it links to return not found. * `/robots.txt` stops pointing to your sitemap. Turning it off doesn't hide your storefront. Your pages still load, and search engines can still find and index them through links. To keep a page out of search results, turn off search indexing in that page's SEO settings. ## Include in Sitemap Each row's **Include in Sitemap** switch adds or removes that one URL from your sitemap. The page itself stays live either way. The setting applies to your company's sitemap, whichever theme you're viewing. On a custom route, the **Include in Sitemap** switch inside the route's drawer currently does more than its label says: saving the drawer with it off also switches the route off, so the route stops serving visitors. To hide a custom route from the sitemap and keep it working, use the switch in the table row instead. After you save a route's drawer, click **Visit Link** to check that it still loads. ## Create a custom route A custom route is a URL you add yourself, such as `/about-us` or `/spring-sale`. For a marketing URL such as `/tv-offer`, or an address from your old website, a [redirect](/help/admin/url_redirects) to the product or page is usually better than a custom route. See [Rep credit](#rep-credit). 1. Click **Create Custom Route**. 2. Enter the **Path**. It must start with `/` and can't contain spaces or `//`. 3. Choose the **URL Shape**. See [The two URL shapes](#the-two-url-shapes). 4. Choose a **Default override**: what the route shows when no country route applies. 5. Fill in the fields that override needs, then click **Save**. The **Theme** field shows the theme you're adding the route to. It's the one picked in **Theme:** at the top of the screen. The **Default override** can be: * **URL Redirect**: Sends visitors to the **Redirect URL** you enter, with a temporary redirect. * **Home Page**, **Shop Page**, or **Join Page**: Shows that page with the **Theme Template** you pick. * **Product**, **Page**, **Media**, **Enrollment**, or **Collection**: Shows the **Resource** you pick, with the **Theme Template** you pick. The template must be a template for that type of content, on the same theme. **Post** and **Playlist** also appear in the list, but a route that shows a post or a playlist can't be saved today. Some paths are taken by your storefront's own pages. You can't create a custom route at `/shop` or `/join`, or at any path that starts with `/products/`, `/pages/`, `/collections/`, `/categories/`, `/media/`, `/enrollments/`, or `/libraries/`. A new or changed route can take up to about 90 seconds to reach every visitor. ### The two URL shapes | URL Shape | Where the route lives | Rep credit | | - | - | - | | **Credited — /:credit/path** | `//spring-sale` and `/home/spring-sale` | Works like any storefront page. The username in the URL gets credit. | | **Non-credited — /path directly** | `/spring-sale` only | No rep in the URL. `//spring-sale` and `/home/spring-sale` return not found. | A credited route doesn't answer at the bare `/spring-sale`. That address shows your home page instead. Use a non-credited route only for an address that must stay in the visitor's address bar. Read [Rep credit](#rep-credit) first. The sitemap currently lists a credited custom route at `/`, without `/home/`. That address shows your home page rather than the route. ## Country-specific routing **Country-Specific Routing** in a route's drawer shows something different to visitors from particular countries. It works on custom routes and on your storefront's own pages, such as a product page. 1. Click **Add Country Route**. 2. Pick one or more **Countries**. 3. Pick an **Override Type**, fill in its fields, then click **Done**. The **Override Type** can be: * **Template override**: Shows the same page with a different **Theme Template**. Not offered on custom routes. * **URL Redirect**: Sends these visitors to another address, with a temporary redirect. * **Disabled**: The page returns not found for visitors from these countries. * **Home Page**, **Shop Page**, or **Join Page**, or a type of content: Shows that page or item instead. The card says each route can enable Fair Share attribution. That setting has no effect today. A country route never changes who gets credit for a visit. ### How a visitor's country is chosen Fluid uses the first of these that it finds: 1. A `region` in the link, such as `?region=CA`. Use this to test a country route, not in links you share. 2. The country in the visitor's language and country choice, from your storefront's locale selector. 3. The country the visitor is browsing from. 4. Your company's default country. 5. The United States. Fluid then uses the route's rule for that country. If there's none, it uses the route's default override. If that's missing too, it uses the rule for your company's default country. Country routes depend on the country only, not the language. To show a page in another language, translate the page or template rather than adding a country route. ## Rep credit Fluid credits a rep when a visitor lands on that rep's credit path. That's a storefront URL whose first part is the rep's username, such as `/jordan-lee/products/beet-blend`. The rep keeps that credit as the visitor browses other pages and comes back later. `/home/...` pages, custom routes, and redirects don't give credit to anyone. They also don't take away credit a visitor already has. See [FairShare: sales rep attribution](/concepts/fair-share) and [Fair Share](/help/admin/settings/fair-share). A non-credited route's first part is your route, not a username. Here's what that means today: * **A non-credited route doesn't establish credit.** A visitor who reaches `/spring-sale` from search, an ad, or another site without a rep's credit places an order with no rep. A visitor a rep already credited keeps that rep's credit. * **Rep links to a non-credited route return not found.** A rep who shares `/jordan-lee/spring-sale` sends customers to a not-found page. Reps should share the product's or page's own credit path instead, such as `/jordan-lee/products/beet-blend`. * **A rep whose username matches a non-credited route loses their own link.** If a rep's username is `spring-sale`, `/spring-sale` shows your route, not their storefront. Fluid doesn't stop you from creating a route that matches a username, or a rep from choosing a username that matches a route. * **A rep whose username matches a non-credited route's path is credited for its visitors.** Fluid looks for a rep in the first part of the path, so visits to `/spring-sale` credit the rep named `spring-sale`. * **A Fair Share setting on a country route doesn't change credit.** See [Country-specific routing](#country-specific-routing). ### Recommended: redirect marketing and legacy URLs A marketing URL such as `/tv-offer`, or an address from your old website, is what customers without a rep type or click: from TV, print, ads, or old links. Send that traffic to the real product or page with a [URL redirect](/help/admin/url_redirects), such as `/tv-offer` to `/home/products/`. Reps don't use that URL. When they share from the Fluid mobile app or their own links, they use credited paths such as `//products/`, so they get credit for their customers. * **Keep rep-shared links on credited paths.** Reps share `//...` links, never a non-credited route. * **Don't add `?username=` to a marketing URL.** It serves customers who arrive without a rep. * **Use non-credited routes only where the address must stay in the address bar** and the page doesn't need to establish credit: company pages, search landing pages, and old URLs from a previous site that must keep their address. * **Check usernames before you add a non-credited route.** Make sure no rep uses the route's first path segment as their username. ## Redirects To send an old address to a new one with a permanent redirect, use the **URL Redirects** screen. See [URL Redirects](/help/admin/url_redirects). ## Related * [URL Redirects](/help/admin/url_redirects) * [Domains](/help/admin/settings/domains) * [Custom routes for theme developers](/themes/custom-routes) * [Supported storefront paths](/themes/supported-paths) 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.