> ## 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. # Switch collections onto an authorized bank account or saved card > Move the authenticated company's collections onto a saved bank account or a saved card the merchant already authorized through instrument setup. Send exactly one of `bank_account_id` or `instrument_setup_id`. The authorization recorded then is reused, so no authorization text is accepted here. Fails when the instrument was never authorized, a bank account's details changed since, Stripe can no longer collect from it, or a setup is still pending. ## OpenAPI ````yaml /api-reference/settings-v0.yaml patch /api/settings/billing/instrument openapi: 3.1.0 info: title: Fluid Settings API version: v0 contact: email: support@fluid.app license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.fluid.app security: [] paths: /api/settings/billing/instrument: patch: tags: - billing summary: Switch collections onto an authorized bank account or saved card description: | Move the authenticated company's collections onto a saved bank account or a saved card the merchant already authorized through instrument setup. Send exactly one of `bank_account_id` or `instrument_setup_id`. The authorization recorded then is reused, so no authorization text is accepted here. Fails when the instrument was never authorized, a bank account's details changed since, Stripe can no longer collect from it, or a setup is still pending. operationId: settings_v0_update_billing_instrument requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - instrument properties: instrument: type: object additionalProperties: false minProperties: 1 maxProperties: 1 properties: bank_account_id: type: integer minimum: 1 description: >- Authorized bank account owned by the authenticated company. instrument_setup_id: type: integer minimum: 1 description: >- A saved card, by the id the setup state lists in `saved_cards`. example: instrument: bank_account_id: 3187 responses: '200': description: The billing page with the switched instrument. content: application/json: schema: $ref: '#/components/schemas/BillingPageResponse' example: billing: invoicing: true upcoming: total_cents: 18420 scheduled_at: '2026-10-01T06:00:00Z' groups: - label: Payments amount_cents: 12870 entries: - product_code: txn_fee description: Transaction fee quantity: '429.0' unit: transaction amount_cents: 12870 - label: Mist amount_cents: 5550 entries: - product_code: mist_ai description: Mist AI usage quantity: '5550.0' unit: unit amount_cents: 5550 invoices: - number: FLB-1405-2026-0008 period_start: '2026-08-01T00:00:00Z' period_end: '2026-09-01T00:00:00Z' total_cents: 21630 owed_cents: 21630 collected_at_source_cents: 0 paid_with_credits_cents: 0 status: finalized paid_cents: 21630 balance_cents: 0 processing_cents: 0 groups: - label: Payments amount_cents: 21630 entries: - product_code: txn_fee description: Transaction fee quantity: '721.0' unit: transaction amount_cents: 21630 billing_email: angela.martin@dundermifflin.com payment_method: status: usable method: auto_debit bank: PNC Bank mask: ••••6789 bank_account_id: 3187 instrument_type: us_bank_account display: bank_name: PNC Bank last4: '6789' transaction_rates: reset_period: monthly_calendar accumulated_cents: 4829150 minimum_volume_cents: null tiers: - threshold_cents: 0 rate_percent: '2.9' fixed_cents: 30 current: true - threshold_cents: 10000000 rate_percent: '2.5' fixed_cents: 30 current: false pull_schedule: frequency: weekly next_pull_at: '2026-10-01T06:00:00Z' status: 200 meta: request_uuid: 7c2e9a41-3b8d-4f62-a1c5-9d0e6f2b8a37 timestamp: '2026-09-30T14:05:11Z' '401': description: Authentication is required. content: application/json: schema: $ref: '#/components/schemas/StandardUnauthorizedResponse' '403': description: >- The caller lacks billing update or billing view permission, is not an admin, or authenticates as a Droplet installation. content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' '404': description: Billing is not set up for this company (no billing profile). content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' '409': description: A bank setup is pending or the company's Stripe mode changed. content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' '422': description: >- The bank account is unavailable, was never authorized, changed, or is no longer held by Stripe. content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' security: - bearer_auth: [] components: schemas: BillingPageResponse: type: object description: The merchant billing page. required: - billing properties: billing: $ref: '#/components/schemas/BillingPage' StandardUnauthorizedResponse: description: Common legacy unauthorized response envelope. allOf: - $ref: '#/components/schemas/StandardErrorResponse' StandardErrorResponse: description: >- Common legacy error response envelope. Older endpoints may return one or more of these fields depending on the controller path. type: object properties: message: type: string error: $ref: '#/components/schemas/ErrorMessage' error_message: $ref: '#/components/schemas/ErrorMessage' errors: $ref: '#/components/schemas/ErrorBag' meta: $ref: '#/components/schemas/Meta' additionalProperties: $ref: '#/components/schemas/JsonValue' BillingPage: type: object description: >- Everything the merchant billing page renders. Every company reads it. When invoicing is false, platform billing is left out: the upcoming charge is zero with no groups and no scheduled date, there are no invoices, transaction_rates is null, and the pull schedule is null. required: - invoicing - upcoming - invoices properties: invoicing: type: boolean description: >- Whether platform billing invoices this company: merchant billing is on for it, or its billing profile is one platform billing can bill or collect. The upcoming charge, invoices, standing, the plan, and the transaction rates show only when this is true; credits show for every company. upcoming: $ref: '#/components/schemas/BillingUpcoming' invoices: type: array description: Issued invoices, newest first; empty when invoicing is false. items: $ref: '#/components/schemas/BillingInvoiceSummary' billing_email: type: - string - 'null' description: >- Where this company's invoices and credit notices are sent. Null means none is nominated, and Fluid falls back to the longest-standing administrator. payment_method: oneOf: - $ref: '#/components/schemas/BillingPaymentMethod' - type: 'null' description: The instrument funds are pulled from, or null when none is set up. transaction_rates: oneOf: - $ref: '#/components/schemas/BillingTransactionRates' - type: 'null' description: >- The contracted rate card, or null when no rate is contracted or invoicing is false. pull_schedule: $ref: '#/components/schemas/BillingPullSchedule' ErrorMessage: description: An API error message represented as text or structured JSON. anyOf: - type: string - $ref: '#/components/schemas/ErrorBag' - type: 'null' ErrorBag: description: >- Validation errors keyed by field, a list of errors, a single error message, or null when no structured error details are available. anyOf: - type: string - type: array items: $ref: '#/components/schemas/ErrorValue' - type: object additionalProperties: $ref: '#/components/schemas/ErrorValue' - type: 'null' Meta: type: object properties: request_id: type: - string - 'null' timestamp: type: string format: date-time JsonValue: description: >- Any valid JSON value for provider, integration, theme, metadata, or other dynamic payloads whose keys are not fixed by the API contract. anyOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: $ref: '#/components/schemas/JsonValue' - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' BillingUpcoming: type: object description: What the current period has accrued and when it will be collected. required: - total_cents - groups properties: total_cents: type: integer description: Everything accrued so far this period in cents.: null scheduled_at: type: - string - 'null' format: date-time description: When the next pull is due. groups: type: array description: The accrual grouped by heading. items: $ref: '#/components/schemas/BillingUpcomingGroup' BillingInvoiceSummary: type: object description: One issued invoice as it appears in the merchant's history. required: - number - period_start - period_end - total_cents - owed_cents - status - paid_cents - balance_cents - processing_cents - groups properties: groups: type: array description: >- The invoice's headings with their amounts, so the history can show what share of a month each was. items: $ref: '#/components/schemas/BillingInvoiceGroup' number: type: string description: The number the invoice was issued under. period_start: type: string format: date-time description: When the period began. period_end: type: string format: date-time description: When the period ended. total_cents: type: integer description: Everything the period came to earned rather than owed.: null owed_cents: type: integer description: What was collectable when the invoice was issued in cents.: null collected_at_source_cents: type: integer description: >- What was earned but not owed, in cents: fees the rail already took, and usage the credit balance already paid. paid_with_credits_cents: type: integer description: The part of collected_at_source_cents the credit balance paid in cents.: null status: type: string description: The invoice's lifecycle state. paid_cents: type: - integer - 'null' description: Settled debits recorded manual payments: null and attributed refunds against this invoice: null in cents. Null when the payment history is incomplete; null is not a payment.: null balance_cents: type: - integer - 'null' description: What remains after recorded payments in cents; negative when the invoice is a credit. Null when the payment history is incomplete; null is not a debt.: null processing_cents: type: integer minimum: 0 description: >- What pulls still waiting for the bank to settle cover on this invoice, in cents. Not part of paid_cents: a bank debit can still fail until it settles. BillingPaymentMethod: type: object description: The instrument funds are pulled from, masked. required: - status - method - bank_account_id - instrument_type - display properties: status: type: - string - 'null' description: Whether the instrument is usable. method: type: string description: How this company is collected from. bank: type: - string - 'null' description: The bank's display name. mask: type: - string - 'null' description: The masked account identifier never the account number.: null bank_account_id: type: - integer - 'null' description: >- The saved company bank account the instrument was set up from. Null for a card or a bank connected through Stripe. instrument_type: type: - string - 'null' enum: - us_bank_account - card - null description: >- The rail the instrument is on. Null on an instrument promoted before rails were recorded. display: oneOf: - $ref: '#/components/schemas/BillingBankDisplay' - $ref: '#/components/schemas/BillingCardDisplay' - type: 'null' description: >- What the merchant recognizes the instrument by, shaped by its rail. Null when no verified setup describes it. Supersedes `bank` and `mask`. BillingTransactionRates: type: object description: The rate card in force, with the reached rung marked. required: - tiers properties: reset_period: type: - string - 'null' description: How often tier accumulation resets. accumulated_cents: type: - integer - 'null' description: Volume accumulated toward the tiers. minimum_volume_cents: type: - integer - 'null' description: Committed minimum for the period in cents.: null tiers: type: array description: The rungs, lowest threshold first. items: $ref: '#/components/schemas/BillingRateTier' BillingPullSchedule: type: object description: >- How often this company is swept. Contracted per merchant rather than earned by volume, so there are no rungs to move between. required: - frequency properties: frequency: type: - string - 'null' description: The cadence in force or null when this company has no billing profile or invoicing is false.: null next_pull_at: type: - string - 'null' format: date-time description: When the next pull is due. ErrorValue: description: A validation or API error value. anyOf: - type: string - type: array items: type: string - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' BillingUpcomingGroup: type: object description: One heading on the upcoming statement. Group amounts sum to the total. required: - label - amount_cents - entries properties: label: type: string description: The heading this group renders under. amount_cents: type: integer description: The sum of the entries beneath it in cents.: null entries: type: array description: The products under this heading. items: $ref: '#/components/schemas/BillingUpcomingEntry' BillingInvoiceGroup: type: object description: >- One heading on an issued invoice and what sat under it. Group amounts sum to the invoice total. required: - label - amount_cents - entries properties: label: type: string description: The heading the lines rendered under. amount_cents: type: integer description: The sum of the lines beneath it in cents.: null entries: type: array description: The products under this heading, as they were invoiced. items: $ref: '#/components/schemas/BillingUpcomingEntry' BillingBankDisplay: type: object description: A bank account as the merchant recognizes it. additionalProperties: false required: - bank_name - last4 properties: bank_name: type: - string - 'null' description: The bank's display name. last4: type: - string - 'null' description: The last four digits of the account never the account number.: null BillingCardDisplay: type: object description: A card as the merchant recognizes it. additionalProperties: false required: - brand - last4 - exp_month - exp_year properties: brand: type: - string - 'null' description: The card network as the provider names it.: null last4: type: - string - 'null' description: The last four digits of the card never the card number.: null exp_month: type: - integer - 'null' description: The month the card expires 1 through 12.: null exp_year: type: - integer - 'null' description: The four-digit year the card expires. BillingRateTier: type: object description: One rung of the contracted rate card. required: - threshold_cents - rate_percent - fixed_cents - current properties: threshold_cents: type: integer description: Volume at or above which this rung prices every transaction. rate_percent: type: string description: Percentage of the transaction as a decimal string.: null fixed_cents: type: integer description: Flat amount added per transaction in cents.: null current: type: boolean description: Whether accumulated volume puts the company on this rung. BillingUpcomingEntry: type: object description: One product's contribution to the period so far. required: - product_code - description - amount_cents properties: product_code: type: string description: The SKU this line came from. description: type: string description: The SKU's display name. quantity: type: - string - 'null' description: How many units accrued as a decimal string.: null unit: type: - string - 'null' description: What one unit is. amount_cents: type: integer description: What the product came to in cents.: null securitySchemes: bearer_auth: type: http scheme: bearer description: Bearer token authentication ````