Fluid Commerce API Reference — Overview and Base URLs

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/...:

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.

Authentication

Company endpoints require a bearer token in the Authorization header:

Authorization: Bearer <your_token>

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 for token types, scopes, and management.

Request format

Send request bodies as JSON and set the Content-Type header:

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:

{
  "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:

{
  "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:

{
  "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:

"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 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.

Authentication

Token types, scopes, and how to pass and manage credentials.

Find and create categories and collections

Browse the public catalog and manage rows with the company API.

Work with the category hierarchy

Nest categories and traverse parents and children.

Control country availability

Set, read, and filter the countries a row is available in.

Rename, publish, and schedule

Rename a row and control when it goes live.

Translate a resource

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. 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.

Overview

Task guides

Endpoints

Auth endpoints

Checkout endpoints

Public SDK endpoints

Payment gateway endpoints

Cart payment endpoints

Commerce endpoints

Webhooks endpoints

Fluid Commerce API Reference — Overview and Base URLs

Base URLs

API versioning

Authentication

Request format

Response format

Errors

Localization

What’s available

Authentication

Find and create categories and collections

Work with the category hierarchy

Control country availability

Rename, publish, and schedule

Translate a resource

​Base URLs

​API versioning

​Authentication

​Request format

​Response format

​Errors

​Pagination

​Localization

​What’s available

Authentication

Find and create categories and collections

Work with the category hierarchy

Control country availability

Rename, publish, and schedule

Translate a resource

Base URLs

API versioning

Authentication

Request format

Response format

Errors

Pagination

Localization

What’s available