How the API fits together

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