> ## 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. > 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. > Successful responses wrap the resource payload alongside a top-level integer status and a meta object. # Get traffic flows > Returns which acquisition channel sent traffic to which piece of content, for a named reporting period — the Sankey behind the Sources tab's flow card. The payload carries the resolved period window, the days of it the channel rollups could answer, one ribbon per (channel, destination) pair with its bot-free visits, and the two counts a client states coverage from. Ribbon values are visits, not distinct visitors. Destinations are ranked and cut server-side. Each channel with folded traffic carries one remainder ribbon — resource null, other true — whose visits are the exact tail it replaced, so the ribbons always sum to accounted_visits. folded_destinations counts the distinct destinations the fold replaced, and is zero when nothing was folded. covered_window is null for a period lying entirely before the channel rollups began, which is distinct from a covered window with no flows in it. capture_start reports when the rollups began either way, so an empty period reads as an empty period rather than as an absence of traffic. stamped_visits is gross while the ribbons are bot-free, so the coverage ratio under-claims and never over-claims. ## OpenAPI ````yaml /api-reference/company-v0.yaml get /api/analytics/traffic/flows openapi: 3.1.0 info: title: Fluid Company API version: v0 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: [] paths: /api/analytics/traffic/flows: get: tags: - analytics summary: Get traffic flows description: | Returns which acquisition channel sent traffic to which piece of content, for a named reporting period — the Sankey behind the Sources tab's flow card. The payload carries the resolved period window, the days of it the channel rollups could answer, one ribbon per (channel, destination) pair with its bot-free visits, and the two counts a client states coverage from. Ribbon values are visits, not distinct visitors. Destinations are ranked and cut server-side. Each channel with folded traffic carries one remainder ribbon — resource null, other true — whose visits are the exact tail it replaced, so the ribbons always sum to accounted_visits. folded_destinations counts the distinct destinations the fold replaced, and is zero when nothing was folded. covered_window is null for a period lying entirely before the channel rollups began, which is distinct from a covered window with no flows in it. capture_start reports when the rollups began either way, so an empty period reads as an empty period rather than as an absence of traffic. stamped_visits is gross while the ribbons are bot-free, so the coverage ratio under-claims and never over-claims. operationId: company_v0_get_analytics_traffic_flows parameters: - name: period in: query required: false description: | Named reporting period (default last_30_days). Supported names: today, last_7_days, last_30_days, last_90_days, last_12_months, this_month, last_month. An unsupported name returns 422. schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CompanyTrafficFlowsResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' '422': description: Unsupported period content: application/json: schema: $ref: '#/components/schemas/StandardErrorResponse' security: - bearer_auth: [] components: schemas: CompanyTrafficFlowsResponse: description: >- Store-traffic flows for a period — the resolved window, the days of it the channel rollups could answer, the ranked channel-to-content ribbons with their folded remainder, and the two counts a client states coverage from, wrapped in the standard API response envelope. type: object additionalProperties: false required: - period - covered_window - capture_start - flows - folded_destinations - accounted_visits - stamped_visits - status - meta properties: period: type: object additionalProperties: false required: - name - starts_on - ends_on - bucket properties: name: type: string description: The resolved period name (e.g. last_30_days). starts_on: type: string format: date description: Inclusive first day of the requested window (YYYY-MM-DD, UTC). ends_on: type: string format: date description: Inclusive last day of the requested window (YYYY-MM-DD, UTC). bucket: type: string description: The bucket granularity of the period window (always "day"). covered_window: type: - object - 'null' description: | The days of the requested period the flows could be drawn over — the requested window intersected with the days this store's channel rollups have carried rows. Every count in the payload is taken over this window rather than the requested one, the coverage denominator included. Null when the two do not meet, which means the period lies entirely before the channel rollups began. Null arrives with empty flows and zeroed counts, and is deliberately distinct from a covered window whose flows are empty — that means the days were answerable and nothing was visited. Do not coerce one into the other. additionalProperties: false required: - starts_on - ends_on properties: starts_on: type: string format: date description: Inclusive first answerable day (YYYY-MM-DD, UTC). ends_on: type: string format: date description: Inclusive last answerable day (YYYY-MM-DD, UTC). capture_start: type: - string - 'null' format: date description: | The day this store's channel rollups first carried a row (YYYY-MM-DD, UTC), or null when they never have. Reported whether or not the requested period overlaps it, so a client can say when the flows begin rather than presenting an empty period as an absence of traffic. A null covered_window with a capture_start set is a period that ends before capture; a null covered_window with a null capture_start is a store that has never had a rollup row at all. flows: type: array description: > One ribbon per (channel, destination) pair with visits over the covered window, ranked destinations only. Channels with no traffic in the window are absent rather than zero-filled. Destinations are cut to a bounded ranked set server-side, and each channel with folded traffic carries one remainder ribbon — resource null, other true — so the ribbons still sum to accounted_visits. items: type: object additionalProperties: false required: - channel - resource - visits - other properties: channel: type: string description: >- The acquisition channel the ribbon leaves (reps, email, paid, social, organic, referral, or direct). resource: type: - object - 'null' description: >- The destination the ribbon lands on, or null on a folded remainder ribbon, which lands nowhere nameable. additionalProperties: false required: - id - title - type properties: id: type: integer description: >- The destination resource's id, within its own content type rather than globally unique. title: type: - string - 'null' description: >- The destination's display title, so a client renders a name rather than an id. Null when the resource has none — a product synced from an external catalogue is exempt from the title requirement its five sibling content types enforce, and such a product can still rank as a destination on visits it really drew. Same reading as top_content.title on the overview payload. type: type: string description: >- The destination's content type (products, pages, posts, media, libraries, or enrollment_packs). visits: type: integer description: >- Bot-free channel-stamped visits from this channel to this destination over the covered window. Visits, not distinct visitors — a counting rollup cannot recover the latter. other: type: boolean description: >- True on the single folded remainder ribbon for this channel, false on a real destination. A flag rather than a title to string-match. folded_destinations: type: integer description: >- How many distinct destinations the fold replaced across every channel, counting a destination reached by three channels once. Zero when nothing was folded, in which case no ribbon carries other. accounted_visits: type: integer description: >- The sum of the visits on the ribbons this payload carries, the folded remainder included, so a merchant adding the diagram up arrives at this number. stamped_visits: type: integer description: > Channel-stamped visits over the same covered window, read from the store's channel rollup — the traffic there was, against the accounted_visits the diagram draws. Gross, bots included, while every ribbon is bot-free. So accounted_visits over stamped_visits is bot-free over gross and under-claims coverage: the real share of nameable traffic is at least what this payload implies, never less. Two checkable numbers rather than one computed percentage, so the client owns the phrasing. status: type: integer description: The HTTP status code echoed in the response envelope. meta: type: object additionalProperties: false required: - request_uuid - timestamp properties: request_uuid: type: - string - 'null' description: The request correlation id, or null when unset. timestamp: type: string format: date-time description: ISO 8601 timestamp when the response was built. UnauthorizedResponse: type: object properties: message: type: string required: - message 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' 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 - 'null' properties: request_id: type: - string - number - integer - 'null' timestamp: type: - string - number - integer - 'null' 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' 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 ````