---
title: How the API fits together | Colleqtive Developer
description: What each part of the Colleqtive Public API is for, and which endpoints to use for a given task.
---

Most integration problems come from picking the wrong resource, not from getting the HTTP wrong. This page explains what each part of the API is for and how the parts relate, so you can find the right endpoint quickly.

## Two levels: catalogue and store

The single most important distinction in the API.

**The catalogue is organisation-wide.** A product exists once for your whole organisation. It holds what the product *is*: description, barcodes, units, category. You manage it through `/products`.

**Store products are per store.** A product only becomes sellable in a store once it is ranged there. The store product record holds the settings that differ per store: minimum and maximum levels, shelf capacity, replenishment behaviour, and stock. You manage these through `/stores/{store_number}/storeproducts` and read stock through `/storeproducts/stock`.

If you create a product and cannot find its stock, this is almost always why. The product exists, but it has not been ranged in the store yet.

| You want to                                      | Use                                         |
| ------------------------------------------------ | ------------------------------------------- |
| Add a product to the catalogue                   | `POST /products`                            |
| Change a product’s description or barcode        | `POST /products`                            |
| Range that product in a store                    | `POST /stores/{store_number}/storeproducts` |
| Change its minimum or maximum level in one store | `PUT /stores/{store_number}/storeproducts`  |
| Read how much of it is in a store                | `GET /storeproducts/stock`                  |

## Stores and locations

A store is a physical shop or a warehouse. `GET /stores` returns both, and the `store_number` values it returns are what every store-scoped path expects.

Locations are positions inside a store: shelves, bins, back-room positions. Read them with `GET /stores/{store_number}/locations`. The `location_code` values are what you use when booking a movement to a specific place, or when asking what sits at a given spot.

There are two endpoints for products at locations, and the names are close together:

- `/stores/{store_number}/locations/{location_code}/products` addresses exactly one location.
- `/stores/{store_number}/locations/products` addresses several, either by `location_code` or by `jsonTag`.

## Stock movements

Stock never changes by itself. Every change is a movement, and every movement carries a reason code. The log of those movements is `/products/stock/storeproductlogs`.

This is the endpoint to use when you want to replicate stock changes into another system, because it tells you what changed and why, rather than just the current total. See [Keeping stock in sync](/guides/syncing-stock/index.md) for how to read it incrementally.

Reason codes come from `GET /reasoncodes`. A reason code says why stock moved, and it also carries the rules the app enforces when it is used, such as whether a comment or a photo is mandatory. Read the list once and cache it. You need the codes before you can book a movement.

## Orders

“Order” covers several different flows, which is worth knowing before you go looking:

| Flow           | Direction                     | Endpoint family          |
| -------------- | ----------------------------- | ------------------------ |
| Delivery       | Goods coming in to a store    | `/orders/deliveries`     |
| Receipt        | What was actually received    | `/orders/receipts`       |
| Transfer       | Goods moving between stores   | `/orders/transfer`       |
| Replenishment  | Refilling the shop floor      | `/orders/replenishment`  |
| Customer order | Goods reserved for a customer | `/orders/customerorders` |

A delivery is an announcement: you tell Colleqtive what is coming so store staff can receive it against an expected order instead of blind. A receipt is the record of what actually arrived. The two are separate on purpose, because they often differ.

## Product lists

A product list is a named selection of products that drives a task in the app, such as a loss list, a count list or a replenishment list. The type decides how the app behaves with it.

Types are organisation-wide and come from `GET /productlisttypes`. Lists themselves are per store. Create the type first, then the list, then add lines to it.

## A typical first integration

1. `GET /stores` to learn your store numbers.
2. `GET /reasoncodes` and cache them.
3. `POST /products` to load your catalogue.
4. `POST /stores/{store_number}/storeproducts` to range products per store.
5. `GET /storeproducts/stock` to read stock, or poll `/products/stock/storeproductlogs` to follow changes as they happen.