> ## 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 overview > Returns the store's traffic overview for a named reporting period. The payload carries the resolved period window, the gross page-view headline with its period-over-period change, the distinct-visitor split into new and returning, the bot-free device mix, a gap-free daily page-view series, the content mix by resource type, and the highest-viewed individual resources — each with its own image, per-day view series, the channel that sent it the most traffic, and the orders and revenue it earned. Two fields carry readings a client must not coerce. unique_visitors is null, rather than zero, for a window visitor state cannot answer. A resource's top_channel is null, rather than "direct", when no channel-stamped visit to it fell in the window. A resource's orders and revenue credit exactly the one resource each order's attributing visit landed on, so they do not decompose store totals and must not be presented as doing so. ## OpenAPI ````yaml /api-reference/company-v0.yaml get /api/analytics/traffic/overview 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/overview: get: tags: - analytics summary: Get traffic overview description: | Returns the store's traffic overview for a named reporting period. The payload carries the resolved period window, the gross page-view headline with its period-over-period change, the distinct-visitor split into new and returning, the bot-free device mix, a gap-free daily page-view series, the content mix by resource type, and the highest-viewed individual resources — each with its own image, per-day view series, the channel that sent it the most traffic, and the orders and revenue it earned. Two fields carry readings a client must not coerce. unique_visitors is null, rather than zero, for a window visitor state cannot answer. A resource's top_channel is null, rather than "direct", when no channel-stamped visit to it fell in the window. A resource's orders and revenue credit exactly the one resource each order's attributing visit landed on, so they do not decompose store totals and must not be presented as doing so. operationId: company_v0_get_analytics_traffic_overview 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/CompanyTrafficOverviewResponse' '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: CompanyTrafficOverviewResponse: description: >- Store-traffic overview for a period — the resolved window, the page-view headline with its period-over-period change, the visitor split, the bot-free device mix, the gap-free daily series, the content mix by resource type, and the highest-viewed individual resources, wrapped in the standard API response envelope. type: object additionalProperties: false required: - period - page_views - unique_visitors - device_mix - series - content_mix - top_content - 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"). page_views: type: object additionalProperties: false required: - total - change_pct properties: total: type: integer description: >- Gross page views over the window, bots included, from the store's own daily rollup. change_pct: type: - number - 'null' description: >- Change against the immediately preceding window of equal length, or null when that window carried no views to compare with. unique_visitors: type: - object - 'null' description: | The distinct-visitor split over the window, or null for a window visitor state cannot answer — one that has already closed, or one reaching back before this store began capturing visitors. Null means "not knowable" and is deliberately distinct from a zero, which means "nobody came". A client must not coerce one into the other. It carries no change_pct, unlike page_views: the numbers come from session state, which records a visitor's most recent activity and so cannot describe the previous window. additionalProperties: false required: - total - new - returning properties: total: type: integer description: Distinct visitors over the window. new: type: integer description: Visitors on their first session. returning: type: integer description: Visitors with more than one session. device_mix: type: object additionalProperties: false description: >- Bot-free page views by device type, always carrying all four keys, zero-filled, so a client can render a stable set of segments. required: - desktop - mobile - tablet - unknown properties: desktop: type: integer description: Bot-free page views from desktop devices. mobile: type: integer description: Bot-free page views from mobile devices. tablet: type: integer description: Bot-free page views from tablets. unknown: type: integer description: Bot-free page views whose device could not be determined. series: type: array description: >- Gross page views per day over the window, gap-filled so every day in the window has a point, oldest first. items: type: object additionalProperties: false required: - at - page_views properties: at: type: string format: date description: The day this point covers (YYYY-MM-DD, UTC). page_views: type: integer description: Gross page views on that day. content_mix: type: object additionalProperties: false description: > Gross page views by content type, always carrying all six types plus "other", zero-filled, in a stable order. "other" is the views that resolved to no resource — a storefront root, a cart, a checkout URL. "promotions" was a seventh key until 2026-07-31. It was removed because it was always zero: no storefront visit has ever resolved to a promotion, and the rollup behind it has never held a row. The values sum to page_views.total with one exception: for windows predating the store rollup's backfill the per-resource rollups can over-count, and the mix then exceeds the headline. Every value is a real rollup total either way, so a client deriving shares should divide by the mix's own sum rather than by page_views.total — the two agree in the normal case, and dividing by the mix keeps a share at or below 100% in both. required: - products - pages - posts - media - libraries - enrollment_packs - other properties: products: type: integer description: Gross page views of individual products. pages: type: integer description: Gross page views of individual pages. posts: type: integer description: Gross page views of individual posts. media: type: integer description: Gross page views of individual media items. libraries: type: integer description: Gross page views of individual libraries. enrollment_packs: type: integer description: Gross page views of individual enrollment packs. other: type: integer description: Gross page views that resolved to no individual resource. top_content: type: array description: >- The highest-viewed individual resources over the window, ranked by gross page views across every content type and cut to a top-N. items: type: object additionalProperties: false required: - type - id - title - page_views - image_url - series - top_channel - top_channel_from - orders - revenue properties: type: type: string description: The resource's content type (e.g. products, pages). id: type: integer description: The resource's own identifier within its type. title: type: - string - 'null' description: The resource's title, or null when it has none. page_views: type: integer description: Gross page views of this resource over the window. image_url: type: - string - 'null' description: | The resource's own image, or null when it has none. Null is a real reading — the client renders a typed placeholder. It is never an empty string and never a server-chosen fallback. series: type: array description: > This resource's gross page views per day over the same window as the store-level series, gap-filled, oldest first. Deliberately a bare array of integers rather than the store-level series' at/page_views objects: it feeds a sparkline with no axis, and the period object already says which days those are. The two are the same length for the same period. items: type: integer top_channel: type: - string - 'null' description: > The canonical channel key that sent this resource the most page views over the window, or null when no channel-stamped visit to it fell in the window. Null means "nothing sent it that we recorded". It is not "direct", and a client must not render it as one. top_channel_from: type: - string - 'null' format: date description: > The day top_channel starts covering (YYYY-MM-DD, UTC). This field is the only statement of how much of the window the channel ranking answers. Do not infer coverage from any other date: how far back a store's channel data reaches depends on when that store began recording it and on whether historical visits have since been replayed into it, and both vary by store and change over time. What is fixed is the floor. Channel data cannot begin before 2026-07-22 under any circumstance, because no visit before that day carries a resolved channel. That bounds how far back this value can ever go; it does not promise any store reaches it. A window reaching back before this store's first channel row ranks the channel over the covered span while page_views beside it counts the whole window. This names the day that span begins, and a client showing the channel should say so rather than let the two read as the same span. Null in both the ordinary case and the empty one: null when the ranking covers the whole window, and null again when it covers none of it, where top_channel is already null and a span with no days has no first day. Null therefore never means "unknown" — pair it with top_channel to tell the two apart. orders: type: integer description: > Paid orders whose attributing visit landed on this resource. An order credits exactly one resource, so this does not decompose store orders: an order whose attributing visit landed on a storefront root, a cart, or a checkout URL credits no row at all and is not spread across them. Zero is a real count, not missing data. Resource credit is forward-only, so orders placed before the platform began recording the attributing visit's resource carry none. revenue: type: string description: > Revenue from those orders as a decimal string in the platform's base currency, summed from each order's creation-time converted total. A string rather than a number so no precision is lost in JSON. Carries the same single-resource credit rule as orders, so summing this column across the served rows is always less than store revenue and must not be presented as a decomposition of it. 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 ````