> ## 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. # Update a Collection > Token-authenticated. PATCH semantics — only keys present in the payload are updated. Triggers fresh Lighthouse + compliance scans automatically. ## OpenAPI ````yaml /api-reference/storefront-v2026-04.yaml patch /api/v202604/company/collections/{id} openapi: 3.1.0 info: title: Fluid Storefront v2026-04 API version: v2026-04 description: | The modernized storefront surface, covering all eight storefront resources: **Categories**, **Collections**, **Products**, **Posts**, **Pages**, **Media**, **Enrollment Packs**, and **Playlists**. ## Two surfaces Every resource is exposed twice, and the pair is the thing to understand first: - **Public** — `/api/v202604/{resource}` and `/api/v202604/{resource}/{slug}`. Unauthenticated (`security: []`); the store is resolved from the request subdomain. Addressed by `slug`, the same identifier that appears in `canonical_url`. Returns only live rows — non-live content never leaks here. - **Company** — `/api/v202604/company/{resource}`. Bearer-token authenticated, addressed by `id`, and returns every row whatever its lifecycle state, so an admin can manage drafts and archives. Full CRUD plus the standardized `shares`, `lighthouse`, and `compliance` member actions on each resource. Path segments use the storefront's nouns, not the database's: `enrollment-packs` and `playlists` (the Library model). ## One response shape Every resource response opens with the same canonical "common top", in the same order, before any resource-specific fields: id, slug, title, description, image_url, canonical_url, images, active, status, publish_at, seo, metafields, languages That means a consumer can render any storefront resource from one code path. `seo` is always present and always fully populated — the server resolves it through a priority chain (SEO record → resource field → store default → built-in), so there is no client-side fallback logic and the API can never disagree with the rendered ``. `metafields`, `languages`, and (where applicable) `countries` are always arrays, never null. ## Lifecycle `status` is the canonical four-value contract — `draft`, `scheduled`, `published`, `archived` — and resolves at the API boundary: a stored `scheduled` row whose `publish_at` has passed reads as `published` with no write required. `active` is the separate merchant on/off toggle; a resource is live only when it is both active and resolved-published. Company create and update auto-queue Lighthouse and compliance scans, so the scores on the member actions always describe the current state of the resource. ## Listing and pagination Index endpoints share one query surface: `lang`, `q` (Elasticsearch over title and description), `filter[…]`, `sort`, and cursor pagination via `page[cursor]` / `page[limit]` (default 25, max 100). Follow `meta.pagination.next_cursor`; do not construct cursors. Products additionally take `country`, which selects the country-relative price and currency AND gates availability. Categories and Collections expose their products from their own path — `GET /api/v202604/categories/{slug}/products` — which is the products catalog scoped to one owner, with the same card shape, filters, sorting, and pagination. ## Translating a resource Translations are written inline on the resource's own create/update. There is no separate translations endpoint and no `translations` object in the payload — the `lang` query parameter selects the locale a request reads or writes. **Read** a locale with `lang` on any GET: GET /api/v202604/company/collections/4821?lang=fr Translated fields (`title`, `description`, `image_url`, and each resource's own translated fields) come back inline in that locale. On the public surface any field with no `fr` translation falls back to its `en` value, so a partially-translated resource never renders blank. The `languages` array on every response lists exactly the locales that carry a translation, always including the default. **Write** a locale with `lang` on POST/PATCH: PATCH /api/v202604/company/collections/4821?lang=fr { "collection": { "title": "Essentiels bien-être" } } Omitting `lang` writes the store's default locale — the store's own default language, not the platform's. A store selling in French treats `lang=fr` as its default write. A translation PATCH is TEXT ONLY: against any other locale, everything but the translated fields is ignored, so translating a title can never regenerate the slug, move `status`, or change `country_isos`, metafields, SEO, or associations. Send those in a request against the store's default locale instead. Creating is different: POST always writes the store's default locale whatever `lang` says, and keeps its full payload. A resource created under a translation would have no value in the store's own language and would take its slug from the translation. `lang` is still validated on POST, so an unsupported locale is a 422 rather than a surprise. A `lang` the store does not sell in returns 422 — translations are never written to a locale the store has not enabled. Add the language to the store first. The typical flow is: create in the default locale, then one PATCH per additional locale carrying only the translated text. 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: [] tags: - name: storefront description: | Unauthenticated public surface that backs storefront pages and AEO crawlers. All operations are `security: []`. - name: company description: | Token-authenticated company surface that backs the admin UI and integrations. paths: /api/v202604/company/collections/{id}: patch: tags: - company summary: Update a Collection description: | Token-authenticated. PATCH semantics — only keys present in the payload are updated. Triggers fresh Lighthouse + compliance scans automatically. operationId: companyCollectionsUpdate parameters: - $ref: '#/components/parameters/LangWrite' - name: id description: The unique identifier of the collection. in: path required: true schema: type: integer - $ref: '#/components/parameters/Lang' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CollectionUpdateRequest' examples: publish: summary: Publish (make live) value: collection: status: published active: true setCountries: summary: Restrict country availability value: collection: country_isos: - GB - US clearCountries: summary: Clear restrictions (available everywhere the company sells) value: collection: country_isos: [] responses: '200': description: The updated Collection. content: application/json: schema: $ref: '#/components/schemas/CollectionCompanyShowResponse' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' security: - bearer_auth: [] components: parameters: LangWrite: name: lang in: query required: false description: | Locale to WRITE, and to render the response in. ISO code (e.g. `fr`, `de`); omit to write the store's default locale. On PATCH, a locale other than the store's own default writes ONLY the translated fields — slug, lifecycle, countries, metafields, SEO, and associations in the same payload are ignored, so translating a title cannot regenerate the slug or move `status`. Send those in a request against the store's default locale. POST always writes the store's default locale, whatever `lang` says, and keeps its full payload. Mobility's base values hold the default locale, so a resource created under a translation would read back blank in the store's own language. `lang` is still validated on POST. Translate a resource after it exists, with PATCH. The comparison is against the STORE's default language, not the platform's — a store selling in French treats `lang=fr` as its default write, not a translation. A locale the store does not sell in returns 422. See "Translating a resource" in the API description. schema: type: string example: fr Lang: name: lang in: query required: false description: | Response locale. ISO code (e.g. `fr`, `de`). When omitted, responds in the company's default locale. On the public surface, falls back to `en` for any translated field missing in the requested locale. schema: type: string example: fr schemas: CollectionUpdateRequest: type: object required: - collection additionalProperties: false properties: collection: $ref: '#/components/schemas/CollectionWrite' CollectionCompanyShowResponse: allOf: - $ref: '#/components/schemas/Envelope' - type: object required: - collection properties: collection: $ref: '#/components/schemas/CollectionAuthenticated' CollectionWrite: type: object additionalProperties: false properties: title: type: string example: Wellness Essentials description: type: - string - 'null' image_url: type: - string - 'null' image_path: type: - string - 'null' slug: type: string description: | Send `slug` + `custom_slug: true` together to pin a permanent merchant-set slug. Without `custom_slug: true`, the slug auto-regenerates from `title` on every title change. custom_slug: type: boolean description: > Send together with `slug` and set `true` to pin a permanent merchant-set slug. Without it, the slug is auto-generated from `title` and regenerates whenever the title changes. active: type: boolean description: > Merchant on/off toggle. Set `false` to hide the collection from every public surface regardless of `status`. status: type: string enum: - draft - scheduled - published - archived description: > Lifecycle state to set. `published` with `active: true` makes the collection live; `scheduled` with a future `publish_at` goes live automatically when that time passes. There is no separate publish endpoint — visibility is changed through `active` and `status`. publish_at: type: - string - 'null' format: date-time description: > Target go-live timestamp used with `status: scheduled`. Once it passes, the row resolves to `published` at read time. Models go-live only — there is no unpublish-at field. application_theme_template_id: type: - integer - 'null' country_isos: type: array items: type: string description: > ISO country codes restricting availability; maps to the read-side `countries` field. An empty array (`[]`) clears all restrictions (unrestricted — available everywhere the company sells); omitting the key leaves the existing countries unchanged (PATCH semantics). product_ids: type: array items: type: integer description: | Full replacement set of product ids in this collection. `[]` empties it; key omitted leaves membership unchanged. Ids must belong to the authenticated store — a product from another store returns 422. metafields_attributes: type: array description: > Metafields to write on the collection using Rails nested-attributes semantics: each entry sets `namespace`, `key`, `value`, and `value_type`, with an optional `description`; send `_destroy: true` to remove an entry. Include the entry's `id` to update or destroy an existing metafield. This per-metafield `id` is accepted on collections only — `CategoryWrite` metafields do not model it, and the asymmetry is intentional (it matches the backend write contract). items: type: object required: - namespace - key - value - value_type properties: id: type: integer description: Present = update / destroy an existing entry. namespace: type: string key: type: string value: {} value_type: type: string description: type: string _destroy: type: boolean search_engine_optimizer_attributes: type: - object - 'null' description: | SEO record nested attributes. The response key is renamed to `seo` for v202604, but the request key stays at the AR `accepts_nested_attributes_for` name during the migration. properties: id: type: integer title: type: string description: type: string image_url: type: string block_crawler: type: boolean Envelope: type: object description: | Shared success envelope for list / show / create / update responses: the resource payload is returned alongside a top-level integer `status` and `meta`. Composed onto each resource response via `allOf`. required: - status - meta properties: status: type: integer example: 200 meta: $ref: '#/components/schemas/Meta' CollectionAuthenticated: description: | Authenticated (company-surface) Collection read shape: the public `CollectionBase` plus `custom_slug`, admin metadata never rendered on the public surface. allOf: - $ref: '#/components/schemas/CollectionBase' - type: object properties: custom_slug: type: boolean description: | Authenticated-only. True when the merchant has pinned a permanent merchant-set slug; false when the slug is auto-generated from `title` and regenerates on rename. Rendered only on the company surface — admin metadata about how the slug is managed, not something a storefront consumer needs. example: false unevaluatedProperties: false UnauthorizedError: type: object description: | Bare 401 body — a single `message` string, not the wrapped `ErrorResponse`. required: - message properties: message: type: string example: Invalid credentials. ForbiddenError: description: | Bare 403 body: `{ error }` when a storefront permission is missing, or `{ message }` when the credential is not company-admin tier. oneOf: - type: object required: - error properties: error: type: string example: Not authorized. - type: object required: - message properties: message: type: string example: Not authorized. ErrorResponse: type: object required: - error - status - meta properties: error: type: object required: - message properties: message: type: string details: type: object additionalProperties: true status: type: integer meta: $ref: '#/components/schemas/Meta' Meta: type: object description: | Response metadata included on every successful response body. `request_id` and `timestamp` are always present; list endpoints also add `pagination`. required: - request_id - timestamp properties: request_id: type: - string - 'null' timestamp: type: string format: date-time pagination: $ref: '#/components/schemas/Pagination' CollectionBase: type: object description: | Storefront Collection. The first thirteen fields are the canonical common top shared by every storefront resource in v202604 — same names, same order, same types across Categories, Collections, Products, Pages, Enrollment Packs, Posts, Media, Playlists. Collection adds NO public tail fields (admin metadata like `position`, `is_default`, and the legacy `public` flag are kept out of the v202604 boundary). required: - id - slug - title - description - image_url - canonical_url - images - active - status - publish_at - seo - metafields - languages - countries properties: id: type: integer description: | Numeric identifier for the collection. This is the canonical company-surface identifier used to address the row on `/api/v202604/company/collections/{id}` endpoints. example: 5102 slug: type: string description: > URL-safe identifier and the canonical public identifier for the collection. It matches the row's `canonical_url` and is the key used by the public show endpoint (`GET /api/v202604/collections/{slug}`). example: wellness-essentials title: type: string description: | Human-readable display title of the collection. When the slug is auto-generated, it derives from this value. example: Wellness Essentials description: type: - string - 'null' description: | Optional long-form description of the collection; `null` when unset. example: Hand-picked supplements and recovery gear. image_url: type: - string - 'null' description: > URL of the collection's primary image, or `null` when it has no image. See `images` for responsive renditions. example: https://cdn.fluid.app/collections/5102.png canonical_url: type: string description: | Absolute canonical storefront URL for the collection, built from its current `slug`. example: https://acme.fluid.app/home/collections/wellness-essentials images: $ref: '#/components/schemas/ResponsiveImageSet' active: type: boolean description: | Merchant on/off toggle. When false, the Collection is hidden from EVERY public surface regardless of `status`. example: true status: type: string enum: - draft - scheduled - published - archived description: | Lifecycle. The auto-go-live rule applies at read time: a stored `scheduled` row whose `publish_at` has passed resolves to `published`. "Live" = `active == true` AND resolved `status == published`. example: published publish_at: type: - string - 'null' format: date-time description: > Scheduled go-live timestamp (ISO 8601), or `null` when none is set. At read time, once `publish_at` has passed a stored `scheduled` row resolves to `published` automatically. Models go-live only — there is no corresponding unpublish-at timestamp. example: null seo: $ref: '#/components/schemas/Seo' metafields: type: array description: > Custom metadata entries (each a `namespace`/`key`/`value` with a `value_type`) attached to the collection; empty array when none are set. items: $ref: '#/components/schemas/Metafield' languages: type: array items: type: string description: | ISO codes of locales this Collection is translated into. Always includes the company default locale; never empty. example: - en - fr countries: type: array items: type: string description: | ISO codes restricting availability. Empty array means available in every country the company sells in (unrestricted). example: - GB - US Pagination: type: object required: - cursor - limit - prev_cursor - next_cursor properties: cursor: type: - string - 'null' limit: type: integer example: 25 prev_cursor: type: - string - 'null' next_cursor: type: - string - 'null' ResponsiveImageSet: type: - object - 'null' description: | Three ImageKit-transformed renditions of the resource's primary image: 200/600/1200 wide, scale-down only, format auto-negotiated. `null` when the resource has no image. properties: thumb: $ref: '#/components/schemas/ImageRendition' medium: $ref: '#/components/schemas/ImageRendition' large: $ref: '#/components/schemas/ImageRendition' Seo: type: object description: > Render-ready search-engine optimization metadata. ALWAYS present on every storefront response — never null. Values are resolved server-side via this priority chain: - `title` SEO title → resource title → company name - `description` SEO desc → resource desc → company default → "Live Free." - `image_url` SEO image → resource og_image → resource image → company default → hardcoded - `block_crawler` SEO block_crawler (false when no SEO row) Frontends, AEO crawlers, and SDKs can render directly from these values — no client-side fallback logic, no chance of HTML and JSON API drifting. `id` is exposed only on the authenticated surface and distinguishes a merchant-configured SEO row from inherited defaults. required: - title - description - image_url - block_crawler properties: title: type: string example: Summer Sale — Up to 40% Off description: Resolved title. Never null. description: type: string example: Shop the July clearance event before it ends. description: Resolved description. Never null. image_url: type: string example: >- https://ik.imagekit.io/fluidapp/tr:w-1200,h-630,c-maintain_ratio,fo-auto,f-auto,q-80/seo/9215.png description: Resolved OG-ready 1200×630 image URL. Never null. block_crawler: type: boolean example: false description: When true, the resource page emits a noindex meta tag. id: type: - integer - 'null' example: 9215 description: >- Authenticated-only. SearchEngineOptimizer row id when one exists; null when the values are inherited from the resource / company / hardcoded defaults. Metafield: type: object required: - namespace - key - value - value_type properties: namespace: type: string example: custom key: type: string example: material value: example: cotton value_type: type: string example: single_line_text_field description: type: - string - 'null' example: The primary material used in this product created_at: type: string format: date-time example: '2026-05-01T12:00:00Z' updated_at: type: string format: date-time example: '2026-05-01T12:00:00Z' locked: type: - boolean - 'null' example: false ImageRendition: type: object required: - url - width properties: url: type: string example: >- https://ik.imagekit.io/fluidapp/tr:w-600,c-at_max,f-auto,q-75/categories/4821.png width: type: integer example: 600 responses: Unauthorized: description: | Missing or invalid bearer token. The body is a bare `{ message }` object — not the wrapped `ErrorResponse` envelope used by 404 / 422. content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' Forbidden: description: | Authenticated but lacking the required permission. The body is bare — `{ error }` when the storefront permission is missing, or `{ message }` when the credential is not company-admin tier — not the wrapped `ErrorResponse` envelope used by 404 / 422. content: application/json: schema: $ref: '#/components/schemas/ForbiddenError' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' UnprocessableEntity: description: Validation failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearer_auth: type: http scheme: bearer description: | Bearer token authentication. Accepts company-admin tokens with `storefront.view` for read operations and `storefront.update` for writes and scan triggers (legacy per-resource grants like `categories.update` / `products.view` / etc. are still accepted during the migration), required on every `company` operation. Storefront public operations under `/api/v202604/{resource}` and `/api/v202604/{resource}/{slug}` are unauthenticated (`security: []`). ````