> ## 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. # Billing > Manage the card or bank account Fluid charges, buy usage credits, turn on auto-reload and find your invoices. The Billing screen is where your company pays Fluid. It shows this month's usage, the payment methods on file, your usage credits and your billing history. ## Where to find it In the admin, click the **Settings** gear in the top bar. In the Settings sidebar, under **Payments**, select **Billing**. To see **Billing** in the sidebar and open the screen, your role needs at least **View only** for **Billing**, in the **Settings** card on the role's **Permissions** tab. That turns on the **Billing** switch that starts with **View Fluid invoices**. Click **Billing** to expand its switches. To change anything on the screen, your role also needs the **Billing** switch **Set the address Fluid emails this company's invoices to**. That one switch covers every change on this screen, including payment methods, credit purchases, auto-reload and your plan, so turn it on only for people who should be able to make them. Without it, you can view the screen but not change anything. Using a saved bank account also needs the **Bank Accounts** switch **View bank account details for payouts**, in the **Commerce** card. See [Roles](/help/admin/settings/roles). ## What's on the screen The cards you see depend on whether Fluid invoices your company. Every company sees **This month**, **Payment**, **Usage credits** and **Invoices**, plus **Usage by product** once Fluid tracks usage for at least one product. If Fluid invoices your company, you also see **Your plan** and **Payments**, and a **Status** card when a payment to Fluid needs attention. If it doesn't, a **Billing contact** card sits above **Invoices**. If no payment method is on file, a banner near the top reads **Add a payment method to get started**. Its **Add a payment method** button takes you to the **Payment** card. ### Status This card appears only if Fluid invoices your company and a payment to Fluid didn't complete or is still being confirmed. * **Action needed** means a payment to Fluid didn't complete, or no authorized payment method is on file. Each item, such as **Direct debit did not complete** or **Invoice past due**, shows its amount and the dates under **AI features may pause after** and **Storefront may pause after**. Your standing recovers once every item clears. * **Being confirmed** means a recent payment is still being confirmed. Nothing is restricted while it is. **Update bank account** and **Set up bank account** take you to the **Payment** card, and **View invoices** takes you to **Invoices**. ### Your plan This card appears only if Fluid invoices your company. It shows: * **Current plan**: what you pay each month, plus any bonus usage the plan includes. * **Usage included**: the usage your plan includes, and how much of it is left. * **Next invoice**: the date of your next invoice. * **Projected total**: what your next invoice comes to so far. Click the eye icon next to it to show the breakdown, grouped under **Transaction fees**, **Mist usage** and any other charges. The amount builds up during the billing period, so the final amount may vary. While you're on a plan, the screen's header also shows when it renews. ### This month This card shows how much of your plan's included usage and your credits is left this month, and how much you've used. Its subtitle shows when the month resets, on the first of each month in UTC. A bar shows your usage by source. When usage comes from more than one source, a table lists each one with its **Total**, **Used** and **Left** amounts: * **Monthly plan**: the usage your plan includes. * **Over plan**: usage past what your plan includes. * **Credits**: credits you bought, plus any carried over. * **Other usage**: usage not paid from credits, when your company has no plan. A note at the bottom of the card can estimate how long your credits last at this month's pace. It can also warn about credits that expire before you can use them. ### Payment This card lists your payment methods. The one marked **Default** is the one Fluid charges. It pays for credit purchases and, if Fluid invoices your company, your invoices. If Fluid invoices your company, a card is charged once enough is owed to be worth its fee. Auto-reload charges a card only, so a bank account default doesn't pay for it. Each row shows the card brand or bank name, the last four digits and a status: * A card shows when it expires. In the 30 days before the end of its expiry month, it reads **Expires soon**. Once that month has ended, it reads **Expired**. * A bank account shows **ACH debit** and whether it's **Verified** or still in progress, such as **Pending**. Other saved cards and authorized bank accounts have a **Make default** button. The **Add payment method** button at the top of the card adds another one. If nothing is on file yet, the card shows the setup form instead. ### Usage credits This card shows your prepaid credits. * The balance row shows the credits you can spend now and whether or when they expire. Bought credits last 1 year. A purchase that hasn't arrived yet shows as pending: a card payment adds its credits when it succeeds, and a bank payment when it settles, in about 4 business days. * **Buy more** opens the **Buy usage credits** dialog. When bonus credits are on offer, the button also shows the largest bonus you can get. * **Auto-reload** buys credits for you when your balance runs low. While it's on, the **Reload** row shows how much it buys and the balance that triggers it. The **Reload limits** row shows the most it buys in a day and in a month. If AI is paid from your credits, the card warns you when your balance is running low. AI stops when your credits run out, and starts again when you buy more. ### Usage by product This card lists what each product has used this month, with a **Month forecast** of where it's on pace to land. The products are **Orders**, **AI**, **Apps and hosting**, **Media library** and **Fluid Studios**. Only products Fluid tracks appear. ### Invoices This card lists every charge and refund, newest first, with its date, description, amount and a **Paid** or **Refund** label. Click **View** to open the invoice, or a refund's credit note, in a new tab. If your browser blocks the tab, click **Open invoice** in the message that appears. **Show more** loads older entries. Your billing contact is the email address Fluid sends billing mail to: credit purchase receipts and credit notices, plus your invoices if Fluid invoices your company. If Fluid invoices your company, it appears under the **Invoices** title as **Invoices sent to**. Otherwise, the **Billing contact** card above **Invoices** shows it as **Billing emails sent to**. Admins whose roles can change billing also get receipts and notices. If no address is set, Fluid sends invoices to your longest-standing administrator. ### Payments This card appears only if Fluid invoices your company. It lists each payment Fluid collected from your card or bank account, newest first, so you can match it to your statement. Each row shows the date, **Card** or **Bank account**, the invoice numbers the payment covered or **Not yet invoiced**, the amount and a status: * **Processing**: a bank payment shows this until your bank settles it, usually within 4 business days. * **Paid**, **Failed** or **Returned**. * **Recovered**: a returned payment whose amount Fluid has since recovered. * **Refunded** or **Partly refunded**: all or part of the payment was given back. Click **Invoice** to open a payment's invoice, when one is available. ## Tasks ### Add a payment method For bank accounts, only business accounts are eligible. If nothing is on file yet, the setup form is on the **Payment** card. Choose **Business bank account** or **Business card**. For a bank account, choose a **Bank account source**: **Use a saved bank account** (when your company has one), **Connect a different bank through Stripe** or **Enter business bank details**. For **Use a saved bank account**, pick the account under **Saved bank account**. If you already have a payment method, click **Add payment method** on the **Payment** card. In the panel, choose **Connect through your bank**, **Enter bank details manually** or **Add a business card**, or pick an account under **Saved bank accounts**. The payment method you add becomes your default. If auto-reload is on and you make a bank account your default, auto-reload pauses, because it charges a card only. For a bank account, enter the **Business account name** and **Billing email**. If you enter bank details by hand, also enter the **Routing number** and **Account number**. For a saved account or one entered by hand, choose the **Account type** and confirm the account belongs to the business. If you connect through your bank, you sign in to it in Stripe after you submit. For a card, enter the **Business name on the card**, the **Billing email** and the card details. Read the **ACH authorization** or **Card authorization** and select its checkbox. Click the button at the bottom of the form, such as **Connect business bank account**, **Verify business bank account**, **Use saved business bank account** or **Save business card**. A card is ready once Fluid finishes saving it, and the page updates on its own. If you entered bank details by hand, Stripe verifies the account with a microdeposit in 1–2 business days. Stripe emails a verification link to the **Billing email** you entered; open it to finish. Right after you submit, the **Payment** card can also show an **Open the Stripe microdeposit verification page** link. Until then, the **Payment** card shows **Bank setup pending**. To stop and try another account, click **Cancel unfinished setup**. ### Change your default payment method On the **Payment** card, find the saved card or bank account you want to use. Click **Make default**. You don't need to accept the authorization again. A message confirms it's now your default. If auto-reload is on and you make a bank account your default, auto-reload pauses, because it charges a card only. ### Buy usage credits On the **Usage credits** card, click **Buy more**. Choose one of the amounts. Each shows what you pay, the credits you get and any bonus. The summary shows the **Bonus**, **Usage added**, **Balance after** and **Total today**. If bonus credits come only with auto-reload, the dialog says so. **Pay with** shows the card or bank account the purchase charges. If nothing is on file, click **Add a payment method**. Read the purchase terms and select **I agree to the purchase terms**. Click **Pay**. The button shows the total. Credits from a card payment arrive when it succeeds. Credits from a bank payment arrive when the debit settles, in about 4 business days. Credits expire 1 year from purchase. ### Turn on auto-reload Auto-reload charges a card only. If your default is a bank account, add a card or make a saved card your default first. On the **Usage credits** card, turn on **Auto-reload**. The **Auto-reload** dialog opens. In **When credits fall below**, enter the balance that starts a reload. In **Buy**, enter how much to buy each time. Use whole dollars, and keep the threshold below the amount you buy. If the dialog shows the **Auto-reload authorization**, read it and select **I authorize auto-reload**. Click **Turn on auto-reload**, or **Save** if you didn't need to authorize it. An **Auto-reload saved.** message appears, and the **Reload** and **Reload limits** rows appear on the card. ### Change auto-reload or its limits On the **Usage credits** card, click the pencil icon next to **Reload** to change the threshold and amount. To change the most auto-reload buys, click the pencil icon next to **Reload limits**. For **Reload**, use whole dollars and keep the threshold below the amount you buy. For **Reload limits**, set a **Daily cap** and a **Monthly cap**. Both need an amount above zero, and the monthly cap can't be less than the daily cap. Once a cap is reached, auto-reload stops until the next day or month. Click **Save** or **Save limits**. To stop auto-reload, turn off the **Auto-reload** switch. ### Change your plan You can change your plan only if Fluid invoices your company. On the **Your plan** card, click the pencil icon next to **Current plan**. The **Change your plan** dialog opens. Choose a plan. Each shows its monthly price, the usage it includes and its bonus. The more you pay, the bigger the bonus. Your current plan is marked **Current**. The summary shows the **Bonus**, **Usage included** and **Monthly total**. Click **Select**. Fluid bills your plan monthly to your default payment method. A **Plan updated.** message appears. ### Change the billing contact Find the billing address under the **Invoices** title, or on the **Billing contact** card if Fluid doesn't invoice your company. Click **Change** next to it. If no address is set, the field already shows. Enter the email address that should get billing mail. Click **Save**. A **Billing contact saved.** message appears. ## Frequently asked questions Auto-reload charges a card only, because a bank payment takes about 4 business days to settle. If your default payment method is a bank account, make a card your default. The switch is also unavailable if your role can't change billing or if no payment method is on file. If auto-reload was on when a bank account became your default, it shows as paused. Turn it off to withdraw your authorization. If a reload fails, the **Usage credits** card shows **Auto-reload is paused** and the reason. Change your payment method, or turn auto-reload off and on again. **Pay** stays unavailable until you agree to the purchase terms. It's also unavailable if no payment method is on file, if your role can't change billing, or if the saved payment method can't be charged. For the last three, a message in the dialog says what's missing. Your billing contact gets credit purchase receipts and credit notices, plus your invoices if Fluid invoices your company. Admins whose roles can change billing also get receipts and notices. If no billing contact is set, Fluid sends invoices to your longest-standing administrator. See [Change the billing contact](#change-the-billing-contact). ## Related pages * [Settings](/help/admin/settings) * [AI Spend](/help/admin/settings/ai-spend) * [Roles](/help/admin/settings/roles) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.