For AI agents

Point your AI coding agent at this page before it writes a line of Flow Retail integration code.

Building a Flow Retail integration with an AI coding agent? Give it this page.

Paste this URL into Claude Code, Cursor, Copilot, or any agent that can fetch a URL, and it has what it needs to write correct Flow Retail API calls:

https://docs.flowretail.com/docs/developers/for-ai-agents

Everything below is written to be read by a machine as much as by you.

Machine-readable entry points

What	URL
Documentation index	https://docs.flowretail.com/docs/llms.txt
All documentation, one file	https://docs.flowretail.com/docs/llms-full.txt
Any page as Markdown	append .md to its URL
Ask the docs a question	GET https://docs.flowretail.com/docs/developers/<page>.md?ask=<question>
OpenAPI 3.0 specification	https://api.flowretail.com/v2/spec

The specification is served by the API itself, needs no authentication, and is regenerated on every deploy — so it always describes the endpoints that are actually live. Fetch it rather than relying on training data.

Base URLs

Environment	URL
Production	https://api.flowretail.com/v2
Stage	https://api.stage.flowretail.com/v2

Build against stage first. Both serve their own /spec.

Authentication in one paragraph

Every request carries Authorization: Bearer <token>. For server-to-server work — which is almost certainly what you are writing — use an integration token, created against an Integration user in Flow Retail Admin. Two other flows exist: exchanging a user auth token for an access token via POST /tenants/{tenantUid}/account when acting on behalf of a signed-in user, and a device token flow for POS hardware.

Conventions that are easy to get wrong

These are the five things an agent writing Flow Retail code gets wrong most often. Read them before generating anything.

1. All money, percentages and quantities are integers with two implied decimals. There are no floats anywhere in the API. 1299 is 12.99. 250 is 2.50%. 150 is 1.50 units. Multiply by 100 on the way in, divide by 100 on the way out, and round explicitly — never send a decimal.

2. Identifiers end in Uid and are strings. A field that points at another entity reuses that entity's field name, so an order line references a product as productUid. Do not invent productId or assume an integer. Note that the tenant is called a client in the product UI but tenantUid in every path.

3. Clearing a field depends on its type. Text and optional Uid fields are cleared by sending an empty string "". Date fields are cleared by sending null. Sending null to a text field is not the same thing.

4. List endpoints return items and paging. paging carries totalCount, pageNumber and pageSize. There is no cursor and no next link. You are on the last page when items.length < pageSize. The default pageSize is 1000 — set it deliberately.

5. Errors come back as three fields. Every error is {"code": "...", "message": "...", "logId": "..."}. Branch on code, never on message — messages are human-facing and may be translated. Log logId and quote it when you contact support.

Webhooks: the two surprising behaviours

If you are generating a webhook receiver, these two rules are not what you would guess, and both lose events if you get them wrong.

A timeout counts as success. If your endpoint does not respond within 10 seconds, Flow Retail records the delivery as successful and drops the event. It is not retried. The same goes for a connection that hangs rather than being refused. Acknowledge fast — return 200 or 202 immediately and do the work on your own queue.

429 is retried, other 4xx codes are not. Retries happen on transport errors, on 429, and on 5xx. Any other 4xx permanently discards the event.

Retries run up to 30 times with backoff of 1, 2, 5, 10, 20, 30, 45, 60, 90, then 120 minutes — just under two days in total. Every payload carries jobId and attempt, so deduplicate on jobId. Nested references in the payload use capitalised Id and Uid keys, inside an otherwise lowerCamelCase envelope.

A prompt you can paste

Read https://docs.flowretail.com/docs/llms-full.txt and fetch the OpenAPI spec
from https://api.flowretail.com/v2/spec before writing any code.

Flow Retail API rules you must follow:
- Base URL https://api.flowretail.com/v2, auth via `Authorization: Bearer <token>`.
- All amounts, percentages and quantities are integers with two implied
  decimals. 1299 means 12.99. Never send a float.
- Identifiers end in Uid and are strings.
- Clear text and Uid fields with ""; clear date fields with null.
- List responses are { items, paging } with totalCount/pageNumber/pageSize.
- Errors are { code, message, logId }. Branch on code, never on message.
- Verify every endpoint and field against the spec. Do not invent either.

What not to trust

The specification at https://api.flowretail.com/v2/spec is the only authoritative description of this API. If a model's memory, an older specification file, or a third-party copy disagrees with it, the specification wins.

Two caveats worth knowing:

• Most operations document only their success response. The error envelope above applies regardless, whether or not a given operation lists the status code.

• The API does not publish rate limits. Handle 429 by backing off anyway, and back off on 5xx — do not assume a fixed budget in either direction.

When the docs are not enough

Every integration partner gets direct access to the developers who build this API — free and unlimited. Email [e-mail] and ask for a Slack invite. Bring the logId from any error you are stuck on.