> ## 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. > Never use /api/company/v1 or /api/v1 paths, page/per_page params, or offset pagination — they are legacy. > 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). > Successful responses wrap the resource payload alongside a top-level integer status and a meta object. # Fluid Commerce API Reference — Overview and Base URLs > The Fluid Commerce API is a versioned REST API. This overview covers base URLs, the v2026-04 surface, the standard response envelope, error shapes, and cursor pagination. The Fluid Commerce API is a versioned REST API that gives you programmatic access to your storefront: catalog, content, media, and the resources that back your storefront pages. Requests and responses are JSON, and every response follows a single, predictable envelope so your integration can parse success and error bodies the same way across every endpoint. ## Base URLs All requests are made over HTTPS. Two servers are available: | Server | Base URL | Use it for | | ----------------- | ----------------------------- | --------------------------------------------------------------------------- | | Global | `https://api.fluid.app` | Company (token-authenticated) endpoints — the token identifies your company | | Company subdomain | `https://{company}.fluid.app` | Public storefront endpoints — the company is resolved from the subdomain | Public storefront reads resolve the company from the request subdomain, so a catalog request looks like `https://acme.fluid.app/api/v202604/products`. Company endpoints work against the global host with your token, for example `https://api.fluid.app/api/v202604/company/products`. ## API versioning The current, canonical surface is **v2026-04**. Its URL paths use the non-hyphenated form `/api/v202604/...`: ```bash theme={null} GET https://acme.fluid.app/api/v202604/products GET https://api.fluid.app/api/v202604/company/products ``` New standardized surfaces ship under date versions like this one. Earlier per-domain surfaces (v0/v1) remain live but frozen — no new fields or endpoints are added to them — so build new integrations against the current version. A small number of related surfaces carry their own date version in the path. Each endpoint's reference entry shows its exact path, so always copy the version from there. For token types, scopes, and how to pass credentials, see [Authentication](/api/authentication). ## Authentication Company endpoints require a bearer token in the `Authorization` header: ```bash theme={null} Authorization: Bearer ``` Public storefront endpoints (`/api/v202604/{resource}` and `/api/v202604/{resource}/{slug}`) require no authentication — the company is resolved from the subdomain. Company endpoints (`/api/v202604/company/...`) require a company-admin bearer token with `storefront.view` for reads and `storefront.update` for writes. See the [Authentication guide](/api/authentication) for token types, scopes, and management. ## Request format Send request bodies as JSON and set the `Content-Type` header: ```bash theme={null} Content-Type: application/json ``` String values must be quoted, booleans must be `true` or `false`, and numbers must not be quoted. ## Response format Every successful response carries a top-level integer `status`, a `meta` object, and the resource under its own key. List endpoints return the resource under a plural key (for example `products`) and add a `pagination` object to `meta`: ```json theme={null} { "status": 200, "products": [ { "id": 4821, "slug": "cascade-merino-crew", "title": "Cascade Merino Crew" } ], "meta": { "request_id": "9f1c2d34-5e6a-4b7c-8d9e-0f1a2b3c4d5e", "timestamp": "2026-07-20T18:42:11Z", "pagination": { "cursor": null, "limit": 25, "prev_cursor": null, "next_cursor": "eyJpZCI6NDgyMn0" } } } ``` Show, create, and update endpoints return a single resource under its singular key (for example `product` or `category`) and omit `pagination`: ```json theme={null} { "status": 200, "category": { "id": 4821, "slug": "summer-sale", "title": "Summer Sale" }, "meta": { "request_id": "9f1c2d34-5e6a-4b7c-8d9e-0f1a2b3c4d5e", "timestamp": "2026-07-20T18:42:11Z" } } ``` `meta.request_id` is a per-request identifier (it may be `null`) — include it when contacting support so a request can be traced. ## Errors Validation (`422`) and not-found (`404`) responses use a wrapped error envelope that mirrors the success shape — an `error` object, a top-level `status`, and `meta`: ```json theme={null} { "error": { "message": "Validation failed.", "details": { "page.cursor": ["is invalid"] } }, "status": 422, "meta": { "request_id": "9f1c2d34-5e6a-4b7c-8d9e-0f1a2b3c4d5e", "timestamp": "2026-07-20T18:42:11Z" } } ``` Two responses are deliberate exceptions to the envelope, and integrators should handle them explicitly. A `401` returns a bare `{ "message": "..." }`, and a `403` returns a bare `{ "error": "..." }` (or `{ "message": "..." }` when the credential is not company-admin tier). Neither is wrapped in the `error`/`status`/`meta` envelope. Status codes follow these conventions: | Status | Meaning | | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200` | Success | | `401` | Missing or invalid token | | `403` | Authenticated, but the token lacks the required permission | | `404` | Resource not found — also returned for non-public resources requested on the public surface (the public surface never returns `403`) | | `422` | Validation failed, including an invalid cursor or a `page[limit]` above `100`; failing fields are keyed under `error.details` (for example `page.cursor`) | ## Pagination List endpoints use opaque cursor pagination. Two query parameters control it: | Parameter | Type | Description | | -------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- | | `page[cursor]` | string | An opaque cursor returned in a previous response's `meta.pagination.next_cursor` or `prev_cursor`. Omit it on the first page. | | `page[limit]` | integer | Page size. Default `25`, maximum `100`. A value above `100` returns `422`. | Each list response reports pagination under `meta.pagination`: ```json theme={null} "pagination": { "cursor": null, "limit": 25, "prev_cursor": null, "next_cursor": "eyJpZCI6NDgyMn0" } ``` To walk a full result set, pass the response's `next_cursor` as `page[cursor]` on the next request and repeat until `next_cursor` comes back `null`. Cursors are opaque strings — pass them back verbatim and do not attempt to decode or construct them. Pagination is count-free by design: there are no `total_count` or `total_pages` fields. ## Localization Every storefront resource can carry its translated text — title, description, and image — in more than one language. Reads render a locale with the `lang` query parameter (falling back to the store default on the public surface); writes add a translation with a company `PATCH` carrying `lang`. Writing a translation is always a company update, never a public read, and never a separate translations endpoint. See [Translate a resource](/api/guides/translate-resources) for the full model and a per-resource reference. ## What's available The v2026-04 storefront surface covers categories, collections, products, pages, posts, media, playlists, and enrollment packs — each with a public (unauthenticated) read surface and a company (token-authenticated) management surface. Browse every endpoint, with request and response schemas, in the auto-generated **Endpoints** reference. Token types, scopes, and how to pass and manage credentials. Browse the public catalog and manage rows with the company API. Nest categories and traverse parents and children. Set, read, and filter the countries a row is available in. Rename a row and control when it goes live. Write and read translations for any storefront resource with `lang`. Additional surfaces — including checkout, payments, and webhooks — are being published to this same standard. Download the full OpenAPI specification at [https://storage.googleapis.com/fluid-public/docs/api/storefront-v2026-04.yaml](https://storage.googleapis.com/fluid-public/docs/api/storefront-v2026-04.yaml). This public mirror is synced hourly; the same spec is committed in this docs repo at `api-reference/storefront-v2026-04.yaml` and drives the Endpoints reference.