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

# Custom routes, country routes, and redirects

> How Fluid serves custom storefront routes, country-specific routes, and redirects, in what order, and how each one relates to rep attribution.

Fluid gives a storefront three ways to answer a URL that isn't one of its built-in [supported paths](/themes/supported-paths):

* **Redirects** send an exact path to another address with a permanent `301`.
* **Custom routes** serve a template, a resource, or a temporary `302` redirect at a path you choose.
* **Country routes** change what a route serves for visitors from particular countries. They work on custom routes and on built-in pages.

Merchants manage them in the admin on the [Sitemap](/help/admin/sitemap) and [URL Redirects](/help/admin/url_redirects) screens. Custom and country routes are stored as **theme region rules**. See [API reference](#api-reference).

## Recommended: redirect marketing and legacy URLs

A marketing URL such as `/tv-offer`, or a path from a merchant's previous website, is what customers without a rep type or click: from TV, print, ads, or old links. Redirect it to the Fluid product or page it stands for:

```text theme={null}
/tv-offer  →  301  →  /home/products/beet-blend
```

Members don't use that URL. When a member shares, from the Fluid mobile app or their own links, they use credited paths such as `/jordan-lee/products/beet-blend`, so attribution works through the credit segment as usual. The marketing URL keeps working for everyone else, and the product keeps a single canonical address.

Choose the redirect type by what the URL needs:

| Need | Use | Status |
| - | - | - |
| A permanent marketing or legacy URL | A redirect on the **URL Redirects** screen | `301` |
| A different destination per country | A custom route whose default and country routes use **URL Redirect** | `302` |
| The URL itself must stay in the address bar | A non-credited custom route that renders the content. See [Attribution](#attribution) for the trade-offs | `200` |

Redirects on the URL Redirects screen have one target for every visitor. Only country routes can send visitors from different countries to different places.

## Credited and non-credited routes

Every custom route has one of two URL shapes:

| Shape | Serves at | Doesn't serve at |
| - | - | - |
| Credited | `/:credit/<path>`, such as `/home/spring-sale` and `/jordan-lee/spring-sale` | `/<path>`, which Fluid reads as a credit segment and renders the home page |
| Non-credited | `/<path>`, such as `/spring-sale` | `/:credit/<path>`, including `/home/<path>`, which returns `404` |

A credited route behaves like any other storefront page: the credit segment carries attribution.

A non-credited route claims its **first path segment** for the company. Once `/spring-sale` is a non-credited route, Fluid treats any request whose first segment is `spring-sale` as a custom-route request, not a credit segment.

### Reserved paths

A custom route can't use a built-in storefront path: `shop`, `join`, or anything under `products/`, `pages/`, `collections/`, `categories/`, `media/`, `enrollments/`, or `libraries/`. Those paths can still take country routes, but only as credited routes and never with a `default` rule.

## What a route can serve

Each rule serves one of these:

* **A template.** The page renders with a template from the rule's own theme. Use a template for the page type the rule renders, such as a product template for a product. The admin offers only those.
* **A resource.** A product, page, media item, enrollment pack, category, or collection, rendered with the rule's template.
* **A built-in page.** The home, shop, or join page.
* **A redirect.** A `302` to the rule's URL.
* **Nothing (disabled).** A `404` for visitors from the rule's countries. A disabled rule can't be the `default` rule.

When a route serves content, Fluid renders it in place. The visitor's address bar keeps the route's URL, such as `/spring-sale`, and the page has no redirect hop.

## How Fluid picks a rule

### Country detection

Fluid decides the visitor's country from the first of these it finds:

1. The `region` query parameter, such as `?region=CA`. Use it to test; don't put it in links you publish.
2. The country in the visitor's saved locale, which the [locale selector](/themes/navbar-locale-selector) sets, such as `CA` in `fr_CA`.
3. The visitor's location, from the CDN's geolocation headers.
4. The company's default country.
5. `US`.

### Rule selection

For a route, Fluid then picks one active rule on the active theme:

1. A rule for the visitor's country.
2. The route's `default` rule. Only custom routes have one.
3. A rule for the company's default country.

Within a tier, the rule with the lower priority number wins.

### Country, not language

Rules are keyed by country only. Two visitors in Canada get the same rule whether they browse in English or French. To change language, translate the template rather than adding a rule: a template renders in the visitor's language from its translations.

## Themes, caching, and propagation

* **Only the active theme's rules apply.** A rule belongs to one theme. Rules on other themes apply only while someone previews that theme. When a merchant publishes a different theme, its routes need to exist on that theme too.
* **Pages are cached per country and language.** The CDN keeps a separate copy of a storefront page for each country and language.
* **Changes take a few seconds to about 90 seconds to propagate.** Saving a rule clears the CDN's copies of that path. Non-credited routes also update a list the CDN keeps, which takes up to about 90 seconds to reach every edge.

## Redirects

Redirects on the URL Redirects screen run before any route:

1. **Redirects.** An exact path match sends a `301` to the target. A redirect can be limited to one domain through the API; otherwise it applies on every storefront domain.
2. **Custom and country routes.** If no redirect matched, Fluid applies the route's rule.
3. **The built-in page**, if no rule applies.

Things to know:

* **Exact paths only.** A redirect on `/tv-offer` doesn't match `/tv-offer/extra`.
* **Query strings aren't forwarded.** Neither redirects nor `302` route rules carry the request's query string to the target.
* **Usernames win.** A redirect on a single-segment path, such as `/jordan-lee`, doesn't fire while an active member has that username.
* **Some paths can't be redirected.** A path that contains `/app`, `/www`, `/fluid`, `/api`, `/shop`, `/cable`, `/cart/`, `/checkout/`, or `/admin/` anywhere is rejected, so `/apple-cider` and `/shop-sale` are too. So is a path that matches a built-in route, such as `/:credit/products/:slug`.
* **Changes can be slow.** Redirect lookups are cached per path and domain for up to 30 days, and saving a redirect doesn't always clear that cache today. Create a redirect before you publish the URL.

## Attribution

Fluid looks for a rep in a page URL in this order: the `share_guid` or `username` query parameter, the `referral` query parameter, a rep subdomain, then the first path segment (the second, after `/my/`). See [FairShare SDK and the storefront](/storefront/fairshare-sdk#how-attribution-works-on-the-storefront).

A visit to a member's credit path establishes that member's credit, and the member keeps it across later pages and visits. Non-credited routes and redirects establish no new credit, and they don't remove credit a visitor already has. See [FairShare: sales rep attribution](/concepts/fair-share).

On a non-credited route the first path segment is the route, so Fluid looks it up as a username. Today that means:

* **The route doesn't establish credit.** A shopper who reaches `/spring-sale` from search, an ad, or a backlink without a member's credit places an order with no rep. A shopper a member already credited keeps that member's credit.
* **Credited links to the route break.** `/jordan-lee/spring-sale` returns `404`. Members should share the product's or page's own credit path, such as `/jordan-lee/products/beet-blend`.
* **Usernames and routes collide.** Fluid doesn't stop a route from matching a member's username, or a username from matching a route. A member named `spring-sale` loses `/spring-sale` to the route, and visits to the route credit that member.
* **Country routes don't change credit.** The admin offers a Fair Share option on country routes, but it has no effect.

To keep members' links working:

* Keep every link a member shares on a credited path: `/<username>/...`.
* Redirect marketing and legacy URLs to the product or page, as described in [Recommended](#recommended-redirect-marketing-and-legacy-urls). Don't add `?username=` to a marketing URL.
* Use non-credited routes only for company pages, search landing pages, and legacy URLs that must keep their address.
* Before you create a non-credited route, check that no member uses its first segment as a username.

### Migrate a site

1. **List the old site's URLs** and the Fluid product, page, or collection each one stands for.
2. **Add a redirect for each URL that has a Fluid equivalent**, to its `/home/...` address, such as `/home/products/beet-blend`.
3. **Use a non-credited route only for a URL that must keep its address** and has no Fluid page to redirect to.
4. **Point members at their credited links.** Member links use `/<username>/...` paths from the Fluid mobile app or their own storefront, not the old site's URLs.
5. **Test each old URL** on the live domain, including one you've already visited, and confirm it reaches the right page.

## Sitemap

Custom routes on the active theme appear in `/sitemap-custom.xml`, linked from `/sitemap.xml`. The sitemap currently lists a credited custom route at `/<path>` rather than `/home/<path>`, so prefer a redirect or a non-credited route for a URL that must be indexed. See [Sitemap](/help/admin/sitemap#your-sitemap).

## API reference

* Sitemap: [Get sitemap URLs](/api-reference/sitemap/get-sitemap-urls) and [Update sitemap URL visibility](/api-reference/sitemap/update-sitemap-url-visibility).
* Custom and country routes: [List](/api-reference/theme-region-rules/list-theme-region-rules), [Create](/api-reference/theme-region-rules/create-theme-region-rule), [Show](/api-reference/theme-region-rules/show-theme-region-rule), [Update](/api-reference/theme-region-rules/update-theme-region-rule), and [Delete](/api-reference/theme-region-rules/delete-theme-region-rule) theme region rules.
* Redirects: [List redirects](/api-reference/company-v0/redirects/lists-redirects) and [Create a redirect](/api-reference/company-v0/redirects/create-redirect).

## Related

* [Supported storefront paths](/themes/supported-paths)
* [Query parameters and caching](/themes/query-parameters-and-caching)
* [FairShare SDK and the storefront](/storefront/fairshare-sdk)
* [Sitemap](/help/admin/sitemap)
* [URL Redirects](/help/admin/url_redirects)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.