> ## 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. > 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/auth-v0.yaml covers the unversioned auth surface (/api/... paths — authentication, MFA, social auth, and token exchange); 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. # Subscription Billing one day's renewals, each with its risk band > Returns one page of a single day's renewals for the day drawer. A day has two kinds of row and a subscription can be either: one still scheduled to bill on the date, or one whose charge already ran. Today has both. A renewal that qualifies as both — billed early and already scheduled again — is reported as settled, because an outcome that exists outranks a grade that predicts one. The scheduled half repeats the billing pipeline's own eligibility gates, so a renewal automatic billing will never claim is not listed as one the operator can expect to collect. The settled half applies none of them: what ran, ran. Every row carries the risk band `Analytics::RenewalRiskBands` gave it — the same classifier behind the month grid's at-risk figures. The band is served rather than left to the caller precisely so a client cannot keep a second copy of those rules and drift from the cell that opened the drawer. ## OpenAPI ````yaml /api-reference/analytics-v2026-04.yaml get /api/v202604/analytics/subscription_billing/day openapi: 3.1.0 info: title: Fluid Analytics Dashboard v2026-04 API version: v2026-04 description: | Endpoints backing the fluid-admin Analytics section (Home / Traffic / Brand Buzz). One endpoint per card on each tab; the frontend polls independently so each card can have its own refresh cadence. contact: email: support@fluid.app license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.fluid.app - url: https://{company}.fluid.app description: Production server with company subdomain variables: company: default: myco description: Company subdomain security: - bearer_auth: [] tags: - name: analytics_dashboard_home_overview description: | Home > Overview tab cards. Card 1 (header tiles) is served here; cards 2-11 land in subsequent PRs. - name: analytics_dashboard_home_live description: | Home > Live tab cards. Card 1 (header tiles) is served here; cards 2-6 land in subsequent PRs. - name: analytics_dashboard_home_field description: | Home > Field tab cards. Card 1 (field momentum header) is served here; cards 2-5 land in subsequent PRs. - name: analytics_subscription_billing description: | Subscription Billing surface — a month of renewals worked day by day, plus that month's failure reporting. Same `reports.view` gate and country scoping as the Home dashboard cards. The day drawer's per-subscription table is not served here; it is a paginated list on `GET /api/subscriptions`, which already accepts `next_bill_date` and `last_failed_at` range filters. paths: /api/v202604/analytics/subscription_billing/day: get: tags: - analytics_subscription_billing summary: Subscription Billing one day's renewals, each with its risk band description: | Returns one page of a single day's renewals for the day drawer. A day has two kinds of row and a subscription can be either: one still scheduled to bill on the date, or one whose charge already ran. Today has both. A renewal that qualifies as both — billed early and already scheduled again — is reported as settled, because an outcome that exists outranks a grade that predicts one. The scheduled half repeats the billing pipeline's own eligibility gates, so a renewal automatic billing will never claim is not listed as one the operator can expect to collect. The settled half applies none of them: what ran, ran. Every row carries the risk band `Analytics::RenewalRiskBands` gave it — the same classifier behind the month grid's at-risk figures. The band is served rather than left to the caller precisely so a client cannot keep a second copy of those rules and drift from the cell that opened the drawer. operationId: getAnalyticsSubscriptionBillingDay parameters: - $ref: '#/components/parameters/DayDateQueryParam' - $ref: '#/components/parameters/CountryQueryParam' - $ref: '#/components/parameters/TimeZoneQueryParam' - $ref: '#/components/parameters/DayPageQueryParam' - $ref: '#/components/parameters/DayPerPageQueryParam' responses: '200': description: One page of the day's renewals content: application/json: schema: $ref: '#/components/schemas/SubscriptionBillingDayResponse' '400': $ref: '#/components/responses/InvalidRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '422': $ref: '#/components/responses/Unprocessable' components: parameters: DayDateQueryParam: name: date in: query required: true description: | Calendar date to list, as `YYYY-MM-DD`. Required and not defaulted: the drawer is always opened from a day the operator picked, so a missing date would answer for a different day than the one on screen. A value that is not this exact shape, or one that names a date which does not exist, returns `400` rather than being coerced. schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ example: '2026-09-17' CountryQueryParam: name: country in: query required: false description: | ISO alpha-2 code of one of the requesting company's configured countries (see `GET /countries`). When present, every service on this endpoint filters its data to that country and reports money in the country's own currency. Omit (or send `"all"`) for the aggregate-across-countries view, which is the default and matches pre-Phase-004 behavior. Unknown ISO codes or ones the company is not configured for return `400`. schema: type: string example: US TimeZoneQueryParam: name: tz in: query required: false description: | IANA timezone name (e.g. `America/Denver`) or Rails-style alias (`Eastern Time (US & Canada)`) used to anchor "today" boundaries and hour-of-day bucketing. The frontend sends `Intl.DateTimeFormat().resolvedOptions().timeZone`. Unknown or malformed values silently fall back to UTC — callers omit the param when the endpoint doesn't need wall-clock alignment (see CURRENT-3077). schema: type: string example: America/Denver DayPageQueryParam: name: page in: query required: false description: | 1-based page number. Defaults to `1`. Values below `1` are read as `1`. schema: type: integer minimum: 1 example: 1 DayPerPageQueryParam: name: per_page in: query required: false description: | Renewals per page. Defaults to `25` and is capped server-side at `100` — a day drawer is a working list rather than an export, and the band lookup costs one extra query per page whatever its size. A larger value is clamped to the cap rather than rejected, so the cap is deliberately not declared as a schema `maximum`: doing so would publish a constraint the endpoint does not enforce. Read `per_page` off the response for the size actually applied. schema: type: integer minimum: 1 example: 25 schemas: SubscriptionBillingDayResponse: type: object properties: date: type: string format: date description: The date the roster covers. time_zone: type: string description: | Zone the scheduled half was bucketed in, echoed back so the drawer can label itself. The settled half ignores it: billing events carry an already-local date. example: America/Denver currency: type: string description: ISO code every amount on the response is quoted in. example: USD page: type: integer description: 1-based page number this payload represents. per_page: type: integer description: Page size actually applied, after clamping. total_count: type: integer description: Renewals on the day across every page. summary: $ref: '#/components/schemas/SubscriptionBillingDaySummary' entries: type: array items: $ref: '#/components/schemas/SubscriptionBillingDayEntry' required: - date - time_zone - currency - page - per_page - total_count - summary - entries SubscriptionBillingDaySummary: type: object description: | The day as a whole, independent of which page was requested — computed over the day's full scope, so paging never changes what these figures describe. Two figures the prototype's day panel showed are absent rather than estimated. A count of scheduled smart retries has no source: billing events carry no retry marker, and the only real fact is whether a retry is scheduled right now, which is per renewal. New against returning is split per *customer* and not per renewal, so it does not sum to `renewal_count`. properties: renewal_count: type: integer description: Renewals on the day. average_amount: type: string description: | Mean charge, in the response currency. Converted once per currency rather than per renewal, so a mixed-currency day does not accumulate rounding. `"0.0"` for an empty day. example: '238.0' new_customer_count: type: integer description: | Customers with no cleared charge before this day. A renewal with no member counts here — there is no history to find. returning_customer_count: type: integer description: | Customers who had a charge clear before this day. Measured before the day rather than before the renewal: a charge earlier the same morning does not make someone a returning customer by lunchtime. top_products: type: array description: Biggest money first, capped at five. items: $ref: '#/components/schemas/SubscriptionBillingDayProduct' required: - renewal_count - average_amount - new_customer_count - returning_customer_count - top_products SubscriptionBillingDayEntry: type: object description: | One renewal on the day. A scheduled renewal carries its risk band; one that has already run carries `outcome` instead. Both carry the band, because a settled failure's factors are what say whether a retry alone is enough. properties: subscription_id: type: integer description: Primary key of the subscription. subscription_token: type: string description: Token the drawer links and acts on. customer_name: type: - string - 'null' description: Customer display name, null when unresolved. customer_email: type: - string - 'null' description: Customer email, null when unresolved. variant_name: type: - string - 'null' description: Product variant name, null when the variant is discarded. quantity: type: integer description: Units on the renewal. amount: type: string description: | Charge as `price * quantity`, converted into `currency`. A decimal string, matching every other analytics amount — the wire keeps precision the client rounds at display time. example: '8.92' currency: type: string description: ISO code every amount on the response is quoted in. example: USD status: type: string description: The subscription's status. example: active occurred_at: type: - string - 'null' format: date-time description: | When the charge ran, for a settled renewal, or when it is due, for a scheduled one. Both are real times rather than one standing in for the other, which is what lets the drawer's hour-of-day view mean something. settled: type: boolean description: Whether a charge has already run on this date. outcome: type: - string - 'null' enum: - succeeded - hard_decline - soft_decline - awaiting_retry - in_flight - null description: | What happened, for a settled renewal; null for one still scheduled. `awaiting_retry` outranks the other two failure buckets because it describes the subscription now, while they describe the charge that ran. decline_reason: type: - string - 'null' description: Gateway wording for a failed charge, else null. risk_level: type: string enum: - none - elevated - severe description: | Deterministic grade of present dunning state — not a predicted likelihood, which nothing in the platform produces. Graded by the same classifier the month grid folds into its at-risk figures, so a row and the cell that opened it cannot disagree. risk_factors: type: array description: What produced the level, most significant first. items: type: string enum: - disabled - hard_decline - stale_failure - repeated_declines - dunning_in_flight - prior_failures awaiting_retry: type: boolean description: | Whether the dunning chain has this renewal in hand. Mirrors the gates the retry cron applies before dispatching. required: - subscription_id - subscription_token - customer_name - customer_email - variant_name - quantity - amount - currency - status - occurred_at - settled - outcome - decline_reason - risk_level - risk_factors - awaiting_retry ErrorResponse: type: object properties: error: type: object properties: message: type: string details: type: object additionalProperties: true required: - message meta: $ref: '#/components/schemas/Meta' required: - error LegacyUnauthorizedResponse: type: object properties: message: type: string required: - message LegacyForbiddenResponse: type: object properties: message: type: string error: type: string minProperties: 1 SubscriptionBillingDayProduct: type: object description: One product's share of a day. properties: variant_id: type: integer description: Variant primary key. name: type: - string - 'null' description: Variant display name, null when the variant is discarded. count: type: integer description: Renewals on this variant. amount: type: string description: Their money, in the response currency. example: '476.0' required: - variant_id - name - count - amount Meta: type: object properties: request_id: type: - string - 'null' timestamp: type: string format: date-time required: - timestamp responses: InvalidRequest: description: | A query parameter the endpoint cannot act on — a `country` the requesting company is not configured for, a `month` that is not `YYYY-MM`, or a `date` that is not `YYYY-MM-DD`. All are caller errors rather than scoping failures, and all render the structured error envelope. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Missing or invalid bearer token content: application/json: schema: $ref: '#/components/schemas/LegacyUnauthorizedResponse' Forbidden: description: | Token present but the caller is not a company admin (or is one without `reports.view`). Both branches render via legacy `authorize_*` helpers whose response predates the structured error envelope, so the body is the flat legacy shape. content: application/json: schema: $ref: '#/components/schemas/LegacyForbiddenResponse' Unprocessable: description: An Analytics service returned a business-rule failure. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearer_auth: type: http scheme: bearer description: | Bearer token authentication. Requires a company-admin token whose role holds `reports.view`. ````