FLOW Catalog API (1.0.0)

Product catalog, catalog assignment by location, and storefront catalog endpoints for FLOW.

Environments

All paths in this document are relative to the base URL. Use HTTPS only.

Authentication

FLOW has two kinds of API caller. Both authenticate with cookies. There is no API-key or OAuth client-credentials flow yet. An integration account for a partner system is set up on request.

1. Staff (internal) endpoints

Every endpoint that is not under /api/public-store needs a staff session and a persona.

1. Sign in. POST /api/auth/sign-in/email with the email and password AWC issued to you. The response sets the session cookie __Secure-flow_app.session_token.
2. Load your persona. POST /api/persona/auto with the session cookie. The response sets the signed ff_persona cookie. Your persona decides which capabilities you have.
3. Call the API. Send both cookies on every request.

Server-to-server clients must keep the cookies (a cookie jar) and send an Origin header set to the base URL on the sign-in request.

A request with no session gets a 302 redirect to /login, not a 401. Treat a 302 from any /api/* path as "session expired, sign in again". A request with a session whose persona lacks the needed capability gets a 403 with required set to the missing capability.

2. Storefront endpoints

/api/public-store/{storeKey}/* endpoints that read the catalog, store configuration or prices need no authentication. Endpoints that submit data on behalf of a buyer need a storefront session, obtained with POST /api/store-auth/sign-in/email (cookie __Secure-flow_store.session_token).

Capabilities

Price fields need modify_pricing. A write that includes a list, cost or sell price from a persona without modify_pricing is refused with 403 and the fields (or skus) that caused it. Reads from such a persona leave the cost fields out of the response; the key is absent, not null.

Conventions

• Format. Request and response bodies are JSON (application/json) unless an operation says multipart/form-data (file uploads) or returns a file.
• Errors. Every error body has an error string. Some add code, issues, fields, skus or blockers. See the Error schema.
• Status codes. 200 read or update, 201 created, 202 accepted for approval, 400 invalid input, 403 missing capability or price permission, 404 not found, 409 conflict (duplicate name or SKU, still in use), 413 upload too large, 429 rate limited, 500 server error, 503 dependency unavailable.
• Pagination. List endpoints take page (1-based) and pageSize and return total (and totalPages where shown). Limits are given on each parameter.
• Identifiers. Products have a string id (32 hex characters or a UUID) and a unique sku. Catalogs and locations have integer ids. Catalog versions have UUID string ids.
• Money. Prices are numbers in US dollars. listPrice is the manufacturer list price; sellPrice / unitPrice is the contract price for a catalog or location.
• Images. Image URLs are paths on the same host (for example /api/images/catalog-assets/…). Prefix them with the base URL. /api/images/* needs no authentication.
• Request tracing. Every response carries x-request-id. Send your own x-request-id to correlate logs; quote it when you report a problem.
• CORS. The API does not send CORS headers. Call it from a server, not from a browser on another origin.

Rate limits

Over the limit, the response is 429 with a retry-after header in seconds.

Recommended endpoints for an integration