> ## 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. # Payment Routing > Choose which card gateway handles each payment with ordered rules and percentage splits, and set the fallback order for payments no rule matches. On **Payment Routing**, you decide which of your card gateways handles each card payment. You build rules that send matching payments to a gateway, and you set the default order of gateways for payments that no rule matches. ## Where to find it In the admin, click the **Settings** gear in the top bar. In the Settings sidebar, under **Payments**, select **Payment Routing**. To open the screen, your role needs at least **View only** for **Payment Routing**, in the **Settings** card on the role's **Permissions** tab. To change rules, the fallback order or test mode, the role needs **Full access** for **Payment Routing**. To add a rule, change a rule's gateway, or add a gateway to the fallback order, your role also needs at least **View only** for **Gateways**, in the **Settings** card. With **View only**, you can see the rules and the fallback order but can't change them: **Add rule**, the edit and delete buttons, **Add to order** and **Save order** don't appear, and the **Test mode** button is unavailable. An admin manages roles on [Roles](/help/admin/settings/roles). ## What's on the screen The top bar holds the **Test mode** button. See [Test mode](#test-mode). If you've put countries in test mode, a banner about it appears below the top bar. Below that, one card holds two sections: **Routing rules** and **Default Fallback Order**. Only card gateways appear on this screen. For non-card payment accounts, see [APM](/help/admin/settings/apm). ### Routing rules Rules are evaluated in order, from the top. The first rule a payment matches is the one that's used. If no rule matches, the payment falls through to the **Default Fallback Order** below. Until you add a rule, every payment uses the fallback order. Rules and the **Default Fallback Order** decide which gateway takes checkout payments and payments entered by admins. To limit a rule to orders entered by admins, give it a **Cart Source** condition with the value `admin`. Subscription renewals normally don't follow your rules or the fallback order. A renewal usually stays on the subscription's own gateway while that gateway is active. If you see **CIT (E-commerce)**, **MIT (Recurring)** and **MOTO (Admin-initiated)** tabs on this screen, each tab has its own rules and fallback order, and each rule applies only to its tab's payments. Build a rule to control routing. Don't deactivate a gateway for that: deactivating it immediately fails in-flight transactions on that gateway. Rules don't move subscription renewals, so keep a gateway's merchant account open while subscriptions still renew on it. The **Add rule** button sits next to the **Routing rules** heading. With no rules, the section shows **No rules yet. Add one to start routing traffic.** Each rule in the list shows: * A drag handle and the rule's position in the list. * The rule's name, then an arrow and the gateway it sends payments to. A rule that splits payments lists each gateway with its percentage. Past three gateways, the rest appear as a count, such as **+2 more**. * The rule's conditions, shown as chips such as `payment_source = apple_pay`. A rule without conditions shows **No conditions — matches all**. * The pencil (**Edit rule**) and trash (**Delete rule**) buttons. A rule can also show one of these badges: | Badge | What it means | | - | - | | **Inactive** | The rule is turned off. It's kept but skipped during routing. | | **Gateway not eligible for routing** | The rule's gateway is inactive or can't be found. Payments that match the rule fall through to the default fallback order. Activate the gateway on [Gateways](/help/admin/settings/gateways) or edit the rule. | | **Unreachable (caught by …)** | A rule higher in the list matches every payment this rule would match. The badge ends with that earlier rule's name. | ### Default Fallback Order This is the ordered list of gateways used when no rule matches a checkout or admin payment, or when cascading a soft decline. Only active gateways are eligible for routing. Each row shows a drag handle, the gateway's position, its logo and name, and its gateway type under the name. An inactive gateway is grayed out and shows **Not eligible for routing** until you activate it. Card gateways that aren't in the order appear below the list, with a dash instead of a position and a **Not in fallback order** badge. They're never used as a fallback until you click **Add to order** and save. If you don't have any card gateways yet, the section says **No eligible processors.** Set up a card gateway on [Gateways](/help/admin/settings/gateways) to fill the list. The **Save order** button next to the heading saves the order. It stays unavailable until you change something. ## Add a rule Click **Add rule**. The **Add rule** panel opens. The note at the top reminds you that the rule applies to every transaction type unless you add a **Cart Source** condition. Enter a **Rule name**. It starts as `Rule` followed by the next number, such as `Rule 3`. If you leave it empty, the rule keeps that name. Under **Conditions**, click **Add Condition**. A new row appears, set to the first condition you haven't used yet. Choose the condition you want, and then set its value. See [Conditions](#conditions). A payment must match every condition in the rule, so the rows are joined by **AND**. To remove a condition, click the trash button at the end of its row. A rule with no conditions matches all payments. Under **Routing**, click **Add Processor**. A row appears with a gateway already picked. Choose the gateway you want from its list. An inactive gateway shows **Inactive — activate to route**. A rule that targets it falls through to the default fallback order until you activate the gateway. To split matching payments across gateways, click **Add Processor** again for each gateway, and then enter a percentage for each one. The **Total** must equal 100%. Each time you add or remove a gateway, the percentages reset to an even split, so enter them after you've added all your gateways. To remove a gateway from the split, click the trash button on its row. The switch at the bottom of the panel reads **Active** for a new rule. Turn it off to keep the rule but skip it during routing. The label changes to **Inactive**. Click **Save rule**. The button is available once every condition has a value, the rule has at least one gateway, and split percentages total 100%. The new rule goes to the bottom of the list. A new rule starts at the bottom of the list, so a broader rule above it can catch its payments first. If the new rule shows **Unreachable (caught by …)**, drag it above the rule named in the badge. ### Conditions Conditions you can use include: | Condition | Value | | - | - | | **Payment Source** | One of `card`, `apple_pay` or `google_pay`. | | **Country Iso** | One or more of your company's countries, listed by name and code. | | **Amount Greater Than** | A number in the payment's currency, such as `49.99`. The payment amount must be greater than it. | | **Amount Less Than** | A number in the payment's currency, such as `49.99`. The payment amount must be less than it. | | **Currency Code** | One of the currencies of your company's countries. | | **Cart Source** | One of `web`, `mobile`, `external` or `admin`. Use `admin` for orders entered by admins. | | **Card Network** | One or more of `visa`, `mastercard`, `american_express`, `discover`, `jcb`, `china_union_pay` or `other`. | | **Card Type** | One or more of `credit`, `debit`, `prepaid` or `charge_card`. | You can use each condition once in a rule. For a condition that takes one value, choosing another value replaces the first. ## Edit a rule Click the pencil (**Edit rule**) on the rule's row. The **Edit rule** panel opens. Change the name, conditions, gateways or the **Active** switch, as described in [Add a rule](#add-a-rule). Click **Update rule**. ## Reorder rules Drag a rule by its handle to a new position. The new order saves right away. If the save fails, you see an error and the list goes back to its previous order. ## Delete a rule Click the trash (**Delete rule**) on the rule's row. In the **Delete rule** dialog, click **Delete**. This can't be undone. If you delete your last rule, every payment uses the default fallback order. ## Change the default fallback order Under **Default Fallback Order**, drag each gateway by its handle into the order you want. The positions update as you go. For a gateway marked **Not in fallback order**, click **Add to order**. It joins the end of the list, and you can drag it into place. Click **Save order**. A message confirms that the order was updated. ## Test mode Test mode works only after it's turned on for your company, and it's off by default. Until then, the **Test mode** panel shows **Not active until enabled**. The countries you select are saved, but all payments keep routing normally. When test mode is on, traffic from the countries you select bypasses your rules and routes to the test gateway. Other countries route normally. Use test mode to exercise integration flows without charging customers. Apple Pay payments from those countries are declined, and so is any payment the test gateway can't take, such as a recurring or admin payment on a test gateway without that transaction type. Once test mode is on, a country you add on the [Countries](/help/admin/settings/countries) screen starts in test mode, so deselect it before you start selling there. Click **Test mode** in the top bar. The **Test mode** panel opens. Select a **Test gateway**. The list shows your card gateways that have **Test Only** or **Sandbox Mode** turned on in [Gateways](/help/admin/settings/gateways). If you don't have one, the panel shows **No test gateway configured**, and you can't add countries until a test gateway exists. Under **Countries in test mode**, click a country to select or deselect it. **Select all** adds every country the test gateway is assigned to, and **Deselect all** clears the list. A country the test gateway isn't assigned to shows the gateway's name followed by **not assigned**, and you can't add it. Click **Save**. The button is available once you've changed something. The panel closes when the change is saved. After you save, the button shows how many of your countries are selected, such as **Test mode: 2/12 Countries (not active)**. A **Test mode is configured but not active** banner says that all payments keep routing normally, and lists the selected countries and the test gateway they're set to use. It also lists any selected country without a usable test gateway, whose payments would be declined once test mode is on. To take a country out of test mode, deselect it and click **Save**. ## Frequently asked questions Add a rule with no conditions so that it matches every payment, and add each gateway under **Routing** with its percentage. The percentages must total 100%. Rules above it still run first. To split only some payments, add conditions to the rule. They fall through to the **Default Fallback Order**. The same happens to payments that match a rule whose gateway is inactive. If you have no rules, every checkout and admin payment uses the fallback order. Subscription renewals don't use it. See [Routing rules](#routing-rules). ## Related pages * [Settings](/help/admin/settings) * [Gateways](/help/admin/settings/gateways) * [APM](/help/admin/settings/apm) * [Countries](/help/admin/settings/countries) * [Roles](/help/admin/settings/roles) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.