> ## 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. # Move the company onto another plan > Moves the authenticated company onto another plan, sized to its usage, and sets how it is paid for. A price or credit amount Fluid agreed with the company stays as it was. Recorded, not yet billed. Only a company platform billing invoices has a plan to change. ## OpenAPI ````yaml /api-reference/settings-v0.yaml patch /api/settings/billing/credits 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/credits: patch: tags: - billing summary: Move the company onto another plan description: >- Moves the authenticated company onto another plan, sized to its usage, and sets how it is paid for. A price or credit amount Fluid agreed with the company stays as it was. Recorded, not yet billed. Only a company platform billing invoices has a plan to change. operationId: settings_v0_update_billing_credits requestBody: required: true content: application/json: schema: type: object properties: plan_key: type: string description: Key of the plan to move to. billing_interval: type: string enum: - monthly - annual description: How the plan is paid for. monthly_price_cents: type: - integer - 'null' minimum: 1 description: >- What the plan costs each month, sized between the catalog's; it buys that much usage plus its tier's bonus. Null is the plan's own price. example: plan_key: growth billing_interval: annual responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/BillingCreditsResponse' example: credits: balance_cents: 184250 spendable_cents: 184250 expired_cents: 0 held_cents: 0 pending: card: amount_cents: 0 credit_cents: 0 us_bank_account: amount_cents: 0 credit_cents: 0 drawn_cents: 0 pace: null expiries: - at: '2027-09-12T16:20:05Z' cents: 110000 next_expiry: at: '2027-09-12T16:20:05Z' cents: 110000 low_balance_cents: 2000 funded_categories: - ai plan: key: growth name: Growth monthly_price_cents: 1500000 bonus_percent: 10 included_credits: 16500 billing_interval: annual monthly_charge_cents: 1350000 plans: - monthly_price_cents: 250000 bonus_percent: 0 included_credits: 2500 - monthly_price_cents: 1000000 bonus_percent: 10 included_credits: 11000 - monthly_price_cents: 2500000 bonus_percent: 20 included_credits: 30000 - monthly_price_cents: 5000000 bonus_percent: 30 included_credits: 65000 credit_bonus_mode: always usage: period_start: '2026-09-01T00:00:00Z' orders: 70012 ai: 18400 hosting: null media: null studios: null orders_percent: '1.45' rollover_months: 3 annual_discount_percent: 10 top_up_cents: 100 min_purchase_cents: 10000 max_purchase_cents: 1000000 discounts: - min_cents: 10000 percent_off: 0 - min_cents: 50000 percent_off: 5 - min_cents: 100000 percent_off: 10 - min_cents: 250000 percent_off: 15 - min_cents: 500000 percent_off: 20 - min_cents: 1000000 percent_off: 30 purchasable: true purchase_terms: version: '2026-09-26' text: >- Usage credits are prepaid. One credit pays for one US dollar of Fluid usage. Credits you buy, and any bonus credits on them, expire one year after the purchase date. Credits are not refundable and cannot move between companies, except where Fluid refunds unused purchased credits to the payment method that paid for them. If a payment is refunded, returned, or disputed, the credits it paid for, and their bonus share, are taken back, even when that makes the balance negative. status: 200 meta: request_id: f3b8c2d1-6a4e-4f7b-9c1d-2e5a8b7c4d90 timestamp: '2026-09-30T14:05:11Z' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/StandardUnauthorizedResponse' '403': description: Missing billing.update permission, or a Droplet token content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' '404': description: >- Platform billing does not invoice this company, so it has no plan to change content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' '422': description: The plan is not one Fluid offers content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' security: - bearer_auth: [] components: schemas: BillingCreditsResponse: type: object description: The credits section of the billing page. required: - credits properties: credits: $ref: '#/components/schemas/BillingCredits' 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' BillingCredits: type: object description: >- The company's credits: its plan, what its usage has drawn this month, and what more cost. One credit is one dollar, and every kind of usage draws on one balance. Priced but not billed or for sale yet. required: - balance_cents - spendable_cents - expired_cents - held_cents - next_expiry - low_balance_cents - funded_categories - pending - drawn_cents - pace - expiries - plan - plans - credit_bonus_mode - usage - orders_percent - rollover_months - annual_discount_percent - top_up_cents - min_purchase_cents - max_purchase_cents - discounts - purchasable - purchase_terms properties: balance_cents: type: integer description: >- The credit balance, in cents: the sum of every credit movement. Below zero only when usage overdraws it. spendable_cents: type: integer description: >- What new usage may draw on, in cents: the balance less expired_cents and held_cents. expired_cents: type: integer minimum: 0 description: Credits past their expiry whose expiry is still being recorded in cents.: null held_cents: type: integer minimum: 0 description: Credits held for usage being confirmed in cents.: null low_balance_cents: type: integer minimum: 0 description: The spendable balance below which the credits are running low in cents.: null funded_categories: type: array description: >- The kinds of usage paid from this balance as they run; the rest stay on the bill. items: type: string enum: - ai drawn_cents: type: integer minimum: 0 description: >- What usage that occurred this UTC month drew from the balance, in cents, overdrawn parts included. Usage billed on the invoice draws nothing. pace: oneOf: - $ref: '#/components/schemas/BillingCreditPace' - type: 'null' description: >- How fast the balance is drawn now, or null when no usage is paid from it. pending: type: object description: >- Purchases Stripe took but has not yet paid, by payment method. Their credits are not in the balance: a card payment adds them when it succeeds, and a bank payment when its debit settles, about 4 business days later. required: - card - us_bank_account additionalProperties: false properties: card: $ref: '#/components/schemas/BillingCreditPending' us_bank_account: $ref: '#/components/schemas/BillingCreditPending' next_expiry: oneOf: - $ref: '#/components/schemas/BillingCreditNextExpiry' - type: 'null' description: The earliest expiry ahead, or null when no credits expire. expiries: type: - array - 'null' description: >- Every expiry ahead, soonest first, less what open usage claims will draw from it first. Empty when nothing is left to expire. Null while an open usage claim may be drawn after a lot expires, so which credits expire is unknown. items: $ref: '#/components/schemas/BillingCreditNextExpiry' plan: oneOf: - $ref: '#/components/schemas/BillingCreditPlan' - type: 'null' description: >- The company's plan; the lowest tier until another is chosen. Null when platform billing does not invoice the company. plans: type: array description: >- The monthly minimum tiers a plan can be priced at, smallest first; empty when platform billing does not invoice the company. items: $ref: '#/components/schemas/BillingCatalogPlan' credit_bonus_mode: type: string enum: - always - auto_reload - 'off' description: >- When a purchase's credit bonus applies; auto_reload is only while auto-reload is on. usage: $ref: '#/components/schemas/BillingCreditUsage' orders_percent: type: string description: Share of order value an order draws as a decimal string.: null rollover_months: type: integer description: How long unused included credits carry over. annual_discount_percent: type: integer description: What annual billing takes off the monthly price. top_up_cents: type: integer description: The step an exhausted balance tops up by in cents.: null min_purchase_cents: type: integer minimum: 1 description: The smallest credit purchase in cents.: null max_purchase_cents: type: integer minimum: 1 description: The largest credit purchase in cents.: null discounts: type: array description: >- The credit tiers, smallest amount first; the last one an amount reaches applies. items: $ref: '#/components/schemas/BillingCreditDiscount' purchasable: type: boolean description: >- Whether the company can buy credits now: it has a usable card or bank account on file. purchase_terms: type: object description: >- The terms shown before Buy; a purchase names the version it agreed to. required: - version - text properties: version: type: string text: type: string 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' BillingCreditPace: type: object description: >- What the balance drew since it last started paying for usage, or since the start of the UTC month when that was earlier. required: - since - drawn_cents properties: since: type: string format: date-time description: When the span began. drawn_cents: type: integer minimum: 0 description: What usage in the span drew from the balance in cents.: null BillingCreditPending: type: object description: The purchases on one payment method still waiting to be paid. required: - amount_cents - credit_cents - count additionalProperties: false properties: amount_cents: type: integer minimum: 0 description: What they charge in cents.: null credit_cents: type: integer minimum: 0 description: The credits they add once paid bonus included: null in cents.: null count: type: integer minimum: 0 description: How many purchases are waiting. BillingCreditNextExpiry: type: object description: An expiry ahead and the credits it takes. required: - at - cents properties: at: type: string format: date-time description: When the credits expire. cents: type: integer minimum: 0 description: Credits that expire then in cents.: null BillingCreditPlan: type: object description: The company's plan under credits billing. required: - key - name - monthly_price_cents - bonus_percent - included_credits - billing_interval - monthly_charge_cents properties: key: type: string description: The plan's key. name: type: string description: The plan's name. monthly_price_cents: type: integer minimum: 0 description: What the plan costs each month in cents: null before any annual discount.: null bonus_percent: type: integer minimum: 0 maximum: 100 description: >- The credit tier the price reaches, as the percent of usage added on top of what is paid ($100 at 10% buys 110 credits). included_credits: type: integer minimum: 0 description: The usage it buys each month bonus included; one credit is one dollar.: null billing_interval: type: string enum: - monthly - annual description: How the plan is paid for. monthly_charge_cents: type: integer minimum: 0 description: What the plan costs a month on its interval after any annual discount.: null BillingCatalogPlan: type: object description: >- One monthly minimum tier a plan can be priced at: the commitment, the discount it earns as usage on top, and the usage it buys. required: - monthly_price_cents - bonus_percent - included_credits properties: monthly_price_cents: type: integer minimum: 0 description: The monthly minimum in cents.: null bonus_percent: type: integer minimum: 0 maximum: 100 description: >- The tier's discount, as the percent of usage added on top of what is paid ($100 at 10% buys 110 credits). included_credits: type: integer minimum: 0 description: The usage it buys each month bonus included; one credit is one dollar.: null BillingCreditUsage: type: object description: >- Credits each kind of usage has drawn this UTC month, in cents. Null wherever that usage is not metered yet. required: - period_start - orders - ai - hosting - media - studios properties: period_start: type: string format: date-time description: Start of the month being measured. orders: type: - integer - 'null' minimum: 0 description: Drawn by orders. ai: type: - integer - 'null' minimum: 0 description: Drawn by AI. hosting: type: - integer - 'null' minimum: 0 description: Drawn by hosting; not metered yet. media: type: - integer - 'null' minimum: 0 description: Drawn by media; not metered yet. studios: type: - integer - 'null' minimum: 0 description: Drawn by studios; not metered yet. BillingCreditDiscount: type: object description: >- One credit tier. A purchase of at least min_cents earns percent_off more credits on top of what is paid ($100 at 10% is 110 credits); a plan whose included usage reaches it takes percent_off off its price. required: - min_cents - percent_off properties: min_cents: type: integer minimum: 0 description: Smallest amount in cents: null the tier applies to.: null percent_off: type: integer minimum: 0 maximum: 100 description: The tier's percent as bonus credits on a purchase and off a plan's price.: null ErrorValue: description: A validation or API error value. anyOf: - type: string - type: array items: type: string - type: object additionalProperties: $ref: '#/components/schemas/JsonValue' securitySchemes: bearer_auth: type: http scheme: bearer description: Bearer token authentication ````