> For the complete documentation index, see [llms.txt](https://docs.flowretail.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flowretail.com/docs/developers/for-ai-agents.md).

# 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 <integration@flowretail.no> and ask for a Slack invite. Bring the `logId` from any error you are stuck on.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flowretail.com/docs/developers/for-ai-agents.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.