> 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/introduction.md).

# Introduction

Flow Retail is API-first. This is where integrating with it starts.

**Flow Retail is built API-first.** Every feature in the product is powered by the same endpoints you get — so anything the application can do, your integration can do too.

It is a REST API, modelled around resources, speaking JSON in both directions, with standard HTTP status codes. If you have used a modern retail or commerce API before, most of it will feel familiar — the parts that will not are under [Conventions](#conventions) below, and they are worth five minutes.

## Base URLs

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

Build and test against stage first.

## The specification

The API serves its own OpenAPI 3.0 specification, publicly and without authentication:

```
https://api.flowretail.com/v2/spec
```

It is regenerated on every deploy, so it always describes the endpoints that are actually live on that environment. The [API documentation](/docs/developers/api-documentation.md) in this section is generated from it. Use it to generate clients, drive tests, or feed an AI agent — and where any other copy of the specification disagrees with it, it wins.

## Before you begin

You need a **client** in Flow Retail — the top-level identifier representing either a chain of stores or the owner of a single store.

A client is called a **tenant** in the API, which is why `tenantUid` appears in almost every path. The two words mean the same thing; you will see *client* in the product and in Admin, and *tenant* in the API.

* Already a customer? Your identifier is in [Flow Retail Admin](https://admin.flowretail.com/).
* Not yet? Contact us and we will set you up.

Then create an **Integration user** and generate a token for it. That token is what almost every server-side integration authenticates with.

## Your first request

```bash
export FLOW_TOKEN="your-integration-token"

curl -H "Authorization: Bearer $FLOW_TOKEN" \
     -H "Accept: application/json" \
     "https://api.stage.flowretail.com/v2/tenants/{tenantUid}/reasons"
```

A `401` means the token is wrong or expired; a `403` means it is valid but the user lacks the permission; a `404` on an endpoint you expect to exist usually means the token and the `{tenantUid}` in the path belong to different tenants.

## How resources are organised

Understanding this hierarchy saves a lot of guessing about which path a resource lives under.

**Client level** — shared across every store under the client:

* Stores
* Users
* Products

**Store level** — specific to one store:

* Warehouses
* Orders
* Purchase orders

A store is either physical or online. One client can hold many stores, as single or shared legal entities. Access to client-level resources is still governed by user roles and permissions, so a client-level resource is not automatically visible to every user.

## Conventions

Four rules apply across the whole API. Getting any of them wrong produces bugs that are quiet rather than loud.

| Rule                                    | Detail                                                                                                |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| Amounts are integers                    | All money, percentages and quantities use two implied decimals. `1299` is 12.99. There are no floats. |
| Identifiers end in `Uid`                | They are strings, and a reference reuses the target's field name — `productUid`, `orderUid`.          |
| Lists return `items` + `paging`         | No cursors. Default `pageSize` is 1000.                                                               |
| Errors are `code` + `message` + `logId` | Branch on `code`. Quote `logId` to support.                                                           |

## Where to go next

1. [Authentication](/docs/developers/authentication.md) — pick a token type and get one.
2. [Quantity & price representation](/docs/developers/quantity-and-price-representation.md) — the integer rule in full.
3. [Field naming & data structure](/docs/developers/field-naming-and-data-structure.md) — how fields are named and cleared.
4. [Pagination & sorting](/docs/developers/pagination-and-sorting.md) — working through list endpoints.
5. [Errors & troubleshooting](/docs/developers/errors-and-troubleshooting.md) — the error envelope and what each code means.
6. [Webhooks](/docs/developers/webhooks.md) — receiving events instead of polling.
7. [Field deprecation & removal policy](/docs/developers/field-deprecation-and-removal-policy.md) — how we change things under you.
8. [API documentation](/docs/developers/api-documentation.md) — every endpoint, generated from the live specification.

Integrating with an AI coding agent? Send it to [For AI agents](/docs/developers/for-ai-agents.md) first.

## Talk to us

We have a lot of endpoints, and several that do almost the same thing. An hour with one of our engineers early on will save you more than it costs — ask, and we will work out which ones fit your use case.

Every integration partner gets direct access to the developers who build this API. Email <integration@flowretail.no>, or reach your usual contact.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.flowretail.com/docs/developers/introduction.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.