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

# Platform overview

How Flow Retail fits together: the apps, how data is scoped to client, store and warehouse, how a sale becomes an order and a receipt, and which events announce each change.

**Flow Retail is one API with three apps on top. Data is scoped to a client, a store or a warehouse, and every sale starts as an order.**

This page is the map. The [API reference](https://docs.flowretail.com/docs/developers/api-documentation.md) has the detail for each endpoint.

![Data is scoped to the client, a store or a warehouse. An order has items, settlements, deliveries and handling, and webhook events announce changes to each.](https://593715853-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0GCVniU8V4PZKEK4axWz%2Fuploads%2FrAq9XXLluJ8R7NoxLjFi%2Fdevelopers-data-model.svg?alt=media)

## What is Flow Retail made of?

| Part               | What it is                                                                                                                                                                |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API**            | The REST API at `https://api.flowretail.com/v2`. The apps below run on it, and so can your integration.                                                                   |
| **Flow Admin**     | The web back office: products, prices, users, settings and reports. See [Admin](https://docs.flowretail.com/docs/getting-started/software-clients/admin.md).              |
| **Flow Client**    | The till, for Windows, Mac and iPad. See [Client](https://docs.flowretail.com/docs/getting-started/software-clients/client.md).                                           |
| **Flow Assistant** | The mobile app for iOS and Android: sales, receiving goods, stocktaking. See [Assistant](https://docs.flowretail.com/docs/getting-started/software-clients/assistant.md). |
| **Extensions**     | Opt-in modules such as Flow Gift Card, Campaign and Loyalty Points. See [Extensions / addons](https://docs.flowretail.com/docs/extensions-addons/introduction.md).        |

## How is data organised?

**By scope: client, store and warehouse. The API path tells you which.**

* **Client** (called a *tenant* in the API): shared by every store. Products, brands, price lists, customers, suppliers, users, webhooks and payment methods live here, under `/tenants/{tenantUid}/`.
* **Store**: belongs to one store, under `/stores/{storeUid}/`. Orders, receipts, purchase orders, goods receipts and tills live here. A store is either physical or online, so a webshop is a store.
* **Warehouse**: stock is kept per warehouse, under `/warehouses/{warehouseUid}/`. A store can have several.
* **Organization**: reports and internal purchase orders, under `/organizations/{organizationUid}/`.

Access to client-level data is still governed by user roles and permissions.

## How does a sale move through Flow Retail?

**Every sale starts as an order. Paying for items on it creates a receipt.**

An order keeps four things apart, each with its own endpoints under `…/orders/{orderUid}/`:

| Part                          | Endpoint       | Webhook that announces it                 |
| ----------------------------- | -------------- | ----------------------------------------- |
| Items                         | `/items`       | `ORDER_LINE_RESERVATION_CHANGE`           |
| Settlements and payments      | `/settlements` | `ORDER_SETTLED`                           |
| Deliveries                    | `/deliveries`  | `ORDER_LINE_DELIVERED`, `ORDER_DELIVERED` |
| Handling (picking, follow-up) | `/handlings`   | `ORDER_HANDLING_STATE_CHANGED`            |

Items on an order reserve stock until they are delivered. An offer does not reserve stock.

An order is in one of five states:

| State                | Meaning                                                                               |
| -------------------- | ------------------------------------------------------------------------------------- |
| <kbd>OPEN</kbd>      | Being worked on. A new order starts here.                                             |
| <kbd>PARKED</kbd>    | Saved for later. Can expire.                                                          |
| <kbd>CONFIRMED</kbd> | Set manually, or automatically when an order with a payment is parked. Never expires. |
| <kbd>COMPLETE</kbd>  | Fully paid. Cannot be changed.                                                        |
| <kbd>CANCELED</kbd>  | Deleted or expired. Spelled with one L.                                               |

`ORDER_STATE_CHANGE` announces opened, parked, confirmed and cancelled. Full payment fires `ORDER_SETTLED` instead. Creating an order and letting a parked order expire fire nothing. See [Webhooks](https://docs.flowretail.com/docs/developers/webhooks.md) for the full rules.

For the end-user view, see [Order states](https://docs.flowretail.com/docs/day-to-day-operations/selling/order-states.md) and [Order vs Receipt vs Offer](https://docs.flowretail.com/docs/day-to-day-operations/selling/order-vs-receipt-vs-offer.md).

## Which system should own what?

**One owner per kind of data. Everything else follows from that choice.**

| Data                             | Typical owner                                                 |
| -------------------------------- | ------------------------------------------------------------- |
| Products and prices              | Your ERP if you have one, otherwise Flow Retail. Never both   |
| Stock                            | One owner per warehouse                                       |
| Online orders                    | The shop or OMS creates them. Flow Retail owns fulfilment     |
| POS sales, receipts and payments | Flow Retail                                                   |
| Purchase orders                  | The ERP creates them. Stores receive the goods in Flow Retail |
| Customers                        | Shared. Agree one stable key                                  |

Each guide below turns this into a flow, with the endpoints:

* [ERP integration](https://docs.flowretail.com/docs/integrations/erp.md)
* [E-commerce integration](https://docs.flowretail.com/docs/integrations/e-commerce.md)
* [Order management integration](https://docs.flowretail.com/docs/integrations/order-management.md)

*Last updated 30.10.2026*


---

# 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/platform-overview.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.
