> 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

Start here. Flow Retail's REST API at a glance: base URLs, authentication, conventions, an API map by domain, and guides for ERP, webshop and order management integrations.

**Flow Retail is built API-first.** Every feature in the product runs on the same endpoints you get, so anything the apps can do, your integration can do too.

<a href="https://docs.flowretail.com/docs/developers/api-documentation.md" class="button primary">Open the API reference</a> <a href="https://api.flowretail.com/v2/spec" class="button secondary">OpenAPI specification</a> <a href="https://docs.flowretail.com/docs/developers/for-ai-agents.md" class="button secondary">For AI agents</a>

![Your ERP, webshop, order management system and tools call the Flow Retail API and receive webhook events. Flow Admin, Flow Client and Flow Assistant run on the same API.](https://593715853-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0GCVniU8V4PZKEK4axWz%2Fuploads%2F4Mhample9B7DWYW3YCKv%2Fdevelopers-platform-map.svg?alt=media)

It is a REST API, modelled around resources, speaking JSON in both directions, with standard HTTP status codes. The parts that will feel unfamiliar are under [Conventions](#conventions), and they are worth five minutes.

## What do you want to do?

| You want to…                             | Start here                                                                                                                          |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Make a first call                        | [Your first request](#your-first-request)                                                                                           |
| Connect an ERP or accounting system      | [ERP integration](https://docs.flowretail.com/docs/integrations/erp.md)                                                             |
| Connect a webshop                        | [E-commerce integration](https://docs.flowretail.com/docs/integrations/e-commerce.md)                                               |
| Connect an order management system       | [Order management integration](https://docs.flowretail.com/docs/integrations/order-management.md)                                   |
| Receive events instead of polling        | [Webhooks](https://docs.flowretail.com/docs/developers/webhooks.md)                                                                 |
| Understand how Flow Retail fits together | [Platform overview](https://docs.flowretail.com/docs/developers/platform-overview.md)                                               |
| Let an AI coding agent build it          | [For AI agents](https://docs.flowretail.com/docs/developers/for-ai-agents.md)                                                       |
| Look up an endpoint                      | [API reference](https://docs.flowretail.com/docs/developers/api-documentation.md), or the [API by domain](#the-api-by-domain) below |

## 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 live on that environment. The [API reference](https://docs.flowretail.com/docs/developers/api-documentation.md) in this section is generated from it. Use it to generate clients, drive tests, or feed an AI agent. 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 for 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 are resources organised?

The path tells you the scope. Knowing it saves a lot of guessing about where a resource lives.

| Scope           | Path begins with                                                    | Examples                                                                                                                 |
| --------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Client (tenant) | `/tenants/{tenantUid}/`                                             | products, brands, price lists, customers, suppliers, users, webhooks, delivery providers, payment methods, return orders |
| Store           | `/tenants/{tenantUid}/stores/{storeUid}/`                           | orders, receipts, purchase orders, goods receipts, tills, warehouses, accounting configuration                           |
| Warehouse       | `/tenants/{tenantUid}/stores/{storeUid}/warehouses/{warehouseUid}/` | stock, stocktakings                                                                                                      |
| Organization    | `/tenants/{tenantUid}/organizations/{organizationUid}/`             | reports, internal 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. The [Platform overview](https://docs.flowretail.com/docs/developers/platform-overview.md) shows how the pieces relate.

## 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.                                                           |

## The API by domain

The API reference has one group per resource. These are the groups, sorted by what you want to do.

| Domain                        | Use it for                                                                          | API groups                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ----------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Catalog**                   | Products, brands, categories, properties, media, product packages and groups        | [Product](https://docs.flowretail.com/docs/developers/api-documentation/product), [Product Group](https://docs.flowretail.com/docs/developers/api-documentation/product-group), [Product Media](https://docs.flowretail.com/docs/developers/api-documentation/product-media), [Product Package](https://docs.flowretail.com/docs/developers/api-documentation/product-package), [Product Properties](https://docs.flowretail.com/docs/developers/api-documentation/product-properties), [Product Warranty](https://docs.flowretail.com/docs/developers/api-documentation/product-warranty), [Properties](https://docs.flowretail.com/docs/developers/api-documentation/properties), [Categories](https://docs.flowretail.com/docs/developers/api-documentation/categories), [Asset](https://docs.flowretail.com/docs/developers/api-documentation/asset)                                                                                                                                                                                                                                                                                                                                                       |
| **Prices and promotions**     | Price lists, campaigns, loyalty, subsidies and compensations                        | [Prices](https://docs.flowretail.com/docs/developers/api-documentation/prices), [Campaign](https://docs.flowretail.com/docs/developers/api-documentation/campaign), [Loyalty Program](https://docs.flowretail.com/docs/developers/api-documentation/loyalty-program), [SOA](https://docs.flowretail.com/docs/developers/api-documentation/soa), [Compensation](https://docs.flowretail.com/docs/developers/api-documentation/compensation), [Currency](https://docs.flowretail.com/docs/developers/api-documentation/currency)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **Stock and warehouses**      | Warehouses, stock levels, stock moves and stocktaking                               | [Warehouse](https://docs.flowretail.com/docs/developers/api-documentation/warehouse), [Stock Info](https://docs.flowretail.com/docs/developers/api-documentation/stock-info), [Stocktaking](https://docs.flowretail.com/docs/developers/api-documentation/stocktaking)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| **Orders and sales**          | Orders, items, settlement, receipts, deliveries, handling, returns and pre-payments | [Order](https://docs.flowretail.com/docs/developers/api-documentation/order), [Order Discount](https://docs.flowretail.com/docs/developers/api-documentation/order-discount), [Order Settlement](https://docs.flowretail.com/docs/developers/api-documentation/order-settlement), [Receipt](https://docs.flowretail.com/docs/developers/api-documentation/receipt), [Order Delivery](https://docs.flowretail.com/docs/developers/api-documentation/order-delivery), [Order Handling](https://docs.flowretail.com/docs/developers/api-documentation/order-handling), [Handling](https://docs.flowretail.com/docs/developers/api-documentation/handling), [RMA Order](https://docs.flowretail.com/docs/developers/api-documentation/rma-order), [Pre Payment](https://docs.flowretail.com/docs/developers/api-documentation/pre-payment)                                                                                                                                                                                                                                                                                                                                                                         |
| **Delivery**                  | Delivery providers, methods and time slots                                          | [Delivery Method](https://docs.flowretail.com/docs/developers/api-documentation/delivery-method), [Delivery Provider](https://docs.flowretail.com/docs/developers/api-documentation/delivery-provider), [Timeslots](https://docs.flowretail.com/docs/developers/api-documentation/timeslots)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| **Purchasing and receiving**  | Suppliers, purchase orders, goods receipt and internal purchase orders              | [Supplier](https://docs.flowretail.com/docs/developers/api-documentation/supplier), [Purchase](https://docs.flowretail.com/docs/developers/api-documentation/purchase), [Receivement](https://docs.flowretail.com/docs/developers/api-documentation/receivement), [Internal Purchase Order](https://docs.flowretail.com/docs/developers/api-documentation/internal-purchase-order)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| **Customers**                 | Customers, addresses, contacts, groups and consents                                 | [Customer](https://docs.flowretail.com/docs/developers/api-documentation/customer), [Customer Address](https://docs.flowretail.com/docs/developers/api-documentation/customer-address), [Customer Contact](https://docs.flowretail.com/docs/developers/api-documentation/customer-contact), [Customer Group](https://docs.flowretail.com/docs/developers/api-documentation/customer-group), [Customer Consent](https://docs.flowretail.com/docs/developers/api-documentation/customer-consent)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| **Payments and tills**        | Payment methods and their setup, tills, gift cards                                  | [Payment Method](https://docs.flowretail.com/docs/developers/api-documentation/payment-method), [Payment Method Agreements](https://docs.flowretail.com/docs/developers/api-documentation/payment-method-agreements), [Payment Method Mappings](https://docs.flowretail.com/docs/developers/api-documentation/payment-method-mappings), [Payment Method Parameters](https://docs.flowretail.com/docs/developers/api-documentation/payment-method-parameters), [Till](https://docs.flowretail.com/docs/developers/api-documentation/till), [Giftcard](https://docs.flowretail.com/docs/developers/api-documentation/giftcard)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| **Accounting and reports**    | Accounting configuration, accounting reports, reports and budgets                   | [Accounting Configs](https://docs.flowretail.com/docs/developers/api-documentation/accounting-configs), [Accounting Reports](https://docs.flowretail.com/docs/developers/api-documentation/accounting-reports), [Reports](https://docs.flowretail.com/docs/developers/api-documentation/reports), [Reports External](https://docs.flowretail.com/docs/developers/api-documentation/reports-external), [Budget](https://docs.flowretail.com/docs/developers/api-documentation/budget)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| **Events and bulk data**      | Webhooks, bulk import and notifications                                             | [Webhooks](https://docs.flowretail.com/docs/developers/api-documentation/webhooks), [Import](https://docs.flowretail.com/docs/developers/api-documentation/import), [Notifications](https://docs.flowretail.com/docs/developers/api-documentation/notifications), [Broadcast](https://docs.flowretail.com/docs/developers/api-documentation/broadcast)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| **Tenant, stores and access** | Tenant, stores, users, permissions, extensions, devices and printers                | [Tenant](https://docs.flowretail.com/docs/developers/api-documentation/tenant), [Store](https://docs.flowretail.com/docs/developers/api-documentation/store), [User](https://docs.flowretail.com/docs/developers/api-documentation/user), [Permission](https://docs.flowretail.com/docs/developers/api-documentation/permission), [Organization](https://docs.flowretail.com/docs/developers/api-documentation/organization), [Extensions](https://docs.flowretail.com/docs/developers/api-documentation/extensions), [Config](https://docs.flowretail.com/docs/developers/api-documentation/config), [Templates](https://docs.flowretail.com/docs/developers/api-documentation/templates), [Device](https://docs.flowretail.com/docs/developers/api-documentation/device), [Printer](https://docs.flowretail.com/docs/developers/api-documentation/printer), [Store Printer](https://docs.flowretail.com/docs/developers/api-documentation/store-printer), [Poster](https://docs.flowretail.com/docs/developers/api-documentation/poster), [Flowbox](https://docs.flowretail.com/docs/developers/api-documentation/flowbox), [Reasons](https://docs.flowretail.com/docs/developers/api-documentation/reasons) |
| **Service**                   | Service orders, the customer portal and shipments                                   | [Service](https://docs.flowretail.com/docs/developers/api-documentation/service), [Service Portal](https://docs.flowretail.com/docs/developers/api-documentation/service-portal), [Service Shipment](https://docs.flowretail.com/docs/developers/api-documentation/service-shipment)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

## Common jobs

The calls integrations make most often. Paths are relative to `https://api.flowretail.com/v2`.

| Job                                       | Call                                                                                                                    |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Create a product                          | `POST /tenants/{tenantUid}/products`                                                                                    |
| Update a product                          | `PUT /tenants/{tenantUid}/products/{productUid}`                                                                        |
| Create many prices at once                | `POST /tenants/{tenantUid}/pricelists/{pricelistUid}/prices/batch`                                                      |
| Set many stock levels at once             | `PUT /tenants/{tenantUid}/stores/{storeUid}/warehouses/{warehouseUid}/stock/batch`                                      |
| Read stock for products and locations     | `POST /tenants/{tenantUid}/products/stock`                                                                              |
| Read stock changed since a timestamp      | `POST /tenants/{tenantUid}/stores/{storeUid}/stock`                                                                     |
| Bring in an order from an external source | `POST /tenants/{tenantUid}/stores/{storeUid}/orders/import`                                                             |
| Create an order                           | `POST /tenants/{tenantUid}/stores/{storeUid}/orders`                                                                    |
| Find orders across stores                 | `POST /tenants/{tenantUid}/orders/search`                                                                               |
| Listen for events                         | `POST /tenants/{tenantUid}/httptransports`, then `POST /tenants/{tenantUid}/httptransports/{httpTransportUid}/webhooks` |
| Load a file in bulk                       | `POST /tenants/{tenantUid}/imports/files`                                                                               |

The batch endpoints take many items per call. Stock accepts up to 1000 entries and rolls everything back if one fails. Prices take `create`, `update`, `delete` and `upsert` lists.

## Where to go next

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

Integrating with an AI coding agent? Send it to [For AI agents](https://docs.flowretail.com/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.

*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/introduction.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.
