> For the complete documentation index, see [llms.txt](https://docs.flowretail.com/api/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/api/introduction.md). # Introduction **The Flow Retail API is how you integrate with the Flow Retail platform.** 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 listed 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. 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 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](/api/introduction/authentication.md) — pick a token type and get one. 2. [Quantity & Price Representation](/api/introduction/quantity-and-price-representation.md) — the integer rule in full. 3. [Field Naming & Data Structure Guidelines](/api/introduction/field-naming-and-data-structure-guidelines.md) — how fields are named and cleared. 4. [Pagination & sorting](/api/introduction/pagination.md) — working through list endpoints. 5. [Errors & troubleshooting](/api/introduction/errors-and-troubleshooting.md) — the error envelope and what each code means. 6. [Webhooks](/api/introduction/webhooks.md) — receiving events instead of polling. 7. [Field Deprecation & Removal Policy](/api/introduction/field-deprecation-and-removal-policy.md) — how we change things under you. Integrating with an AI coding agent? Send it to [For AI agents](/api/introduction/for-ai-agents.md) first. ## Talk to us If something is missing, unclear, or you have an integration need the API does not cover, email . Every integration partner gets direct access to the developers who build this API — see [Talk directly to our developers](/api/introduction/talk-directly-to-our-developers.md). --- # 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/api/introduction.md?ask=&goal= ``` `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.