# Cliento API reference: Products and stock

Base URL: `https://api.cliento.com`

The Products and stock APIs are for an integration that keeps track of a location's stock. It
can read the products and their balances, and record deliveries and withdrawals.

A location has one product list and one stock. All the location's merchants share them.

- **Products.** A product is an article the location sells or uses. A product with stock tracking
  has a balance: the number of units the location has.
- **Stock movements.** A stock movement is one change to a balance. The movements are the history
  behind every balance.

A balance changes in several ways. These are the common ones:

- A sale at a point of sale takes out what is sold, whichever merchant sells it.
- A delivery adds to it.
- Staff take out what they use.
- A stocktake counts the stock and corrects the balance to what was counted.

A hair salon's colours, developers and bleaches are not products. They are colour bar items,
described under Colour bar. Their balances are in the same stock, so a stock movement names
either a product or a colour bar item.

The Products API reads the product list and the balances. The Stock movements API reads the
history and records deliveries and withdrawals. The APIs for points of sale, sales and stocktakes
are coming soon.

## Products

The Products API lists a location's products, each with its current stock balance. Use it to show
what a location sells and has in stock, or to look a product up from a scanned barcode or a
delivery note.

A product is an article the location sells or uses. A product with stock tracking has a balance.
The Products API returns only the current balance. What changed it is read from the Stock
movements API.

A product belongs to one location and has an id of the form `prd_...`.
`GET /v1/locations/{locationId}/products` lists the products a page at a time. Reading needs the
scope `products:read`.

- **To look one product up**, add `ean` or `articleNumber` to the list.
- **Quantities are whole numbers**: ten bottles are a `stockQuantity` of 10.
- **`stockQuantity` is there only for a product the location keeps stock of** (`stockTracked`).
- **Purchase prices** (`latestPurchasePrice`, `averageCost`) are returned only to a key that also
  has the scope `stock:cost`.

### List products

`GET /v1/locations/{locationId}/products`

Scope: `products:read`

Stability: preview

The location's products, one page at a time, including those that are not shown on the point-of-sale screen as products that can be sold. To read them all, repeat the call with `after` set to the `nextCursor` of the previous page until a page has none. With `ean` or `articleNumber` it is a lookup: the product a scanned barcode or a delivery note row belongs to.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `limit` | query | integer (int32) | No | Page size, 1 to 200. Default 50. |
| `after` | query | string | No | The `nextCursor` of the previous page. |
| `ean` | query | string | No | Only products with this barcode. Normally one; Two can match, because a product also has the barcodes of the supplier's article it is linked to; see `eans`. |
| `articleNumber` | query | string | No | Only products with exactly this article number. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | ProductList |
| default | Any failure. See the Errors section. | Error |

### Get a product

`GET /v1/locations/{locationId}/products/{productId}`

Scope: `products:read`

Stability: preview

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `productId` | path | string | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | Product |
| default | Any failure. See the Errors section. | Error |

### Get a product by id

`GET /v1/products/{productId}`

Scope: `products:read`

Stability: preview

The same product as under its location, found from its id. For a caller that holds an id and not the location it belongs to. The answer carries `locationId`.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `productId` | path | string | Yes |  |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | Product |
| default | Any failure. See the Errors section. | Error |

## Stock movements

The Stock movements API lets an integration read every change to a location's stock, and record
deliveries and withdrawals of its own. Use it when you need to know what changed a balance and
why, or when you keep your own copy of the balances. The Products API returns only the current
balance.

A location has one stock. Every product with stock tracking has a balance in it. A balance is
never set directly. It changes when something happens, such as:

- A merchant sells the product at a point of sale.
- A delivery arrives.
- Staff take out what they use.
- A stocktake corrects the balance to what was counted.

A stock movement is the record of one such change to one balance. A movement is never changed or
removed. A mistake is undone by a new movement that corrects it.

Movements made by a sale or a stocktake are read here too. The Sales API and the Stocktakes API
are coming soon.

A colour bar item has a balance in the same stock, counted in packs. A change to it is a stock
movement too. A movement has a `productId` or a `colourBarItemId`, never both. When a colour bar
mix finishes a pack, the pack leaves the stock as a `withdrawal` with the mix's `colourBarMixId`.
Such a movement is not corrected on its own; the mix is undone.

A stock movement belongs to one location and has an id of the form `mov_...`.
`GET /v1/locations/{locationId}/stock-movements` lists the movements oldest first. Reading needs
the scope `stock:read`.

The list can be followed. Keep the id of the last movement you have read and pass it as `after`
to get what has happened since. That is how to keep your own copy of the balances up to date
without reading every product again. A movement appears in the list about ten seconds after it is
made.

### Recording movements

`POST /v1/locations/{locationId}/stock-movements` records a stock document: one or more stock
changes that belong together, such as the rows of a delivery note, or products taken from the
shelf for the location's own use. It needs the scope `stock:write`.

- **A `delivery` or `withdrawal` line names a product or a colour bar item**, with `productId` or
  `colourBarItemId`. For a colour bar item the quantity is whole packs: a delivery of twelve tubes
  is `12`. A `correction` line names neither, only the movement it undoes.
- **Every line is applied, or none.** A line that takes out more than is in stock gets the whole
  document refused with `insufficient_stock`; `details` names the product or the colour bar item,
  its balance and the quantity asked for.
- **`listValue`** is what a withdrawal is worth at the supplier's list price, VAT excluded. It is
  there when what was taken is linked to an article in a supplier's catalogue that has a list
  price. A location uses it to charge staff for what they take for themselves, with the `reason`
  `own-use`.
- **Give the document your own `externalReference`**, such as the delivery note number. Sending
  the same reference again changes nothing and answers `200` with the movements made the first
  time, however long ago.
- **`staffId` names the staff member who made the change.** Read it from the Staff API: from the
  staff list, or from the PIN check.
- **Two line types need a further scope.** A `correction` undoes a withdrawal and needs
  `stock:correct`. A `delivery` sets what the goods cost and needs `stock:cost`. A key for a
  screen where staff record what they use needs neither.

### List stock movements

`GET /v1/locations/{locationId}/stock-movements`

Scope: `stock:read`

Stability: preview

Every change of a stock balance at the location, oldest first, including sales at the point of sale. The list can be followed: keep the id of the last movement you have read and pass it as `after` to get what has happened since. A movement appears in the list about ten seconds after it is made.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `limit` | query | integer (int32) | No | Page size, 1 to 200. Default 50. |
| `after` | query | string | No | Only movements made after this one: a `nextCursor` or the id of any movement. |
| `productId` | query | string | No | Only this product's movements. |
| `colourBarItemId` | query | string | No | Only this colour bar item's movements. |
| `type` | query | string | No | Only movements of this `type`. |
| `externalReference` | query | string | No | Only movements with this external reference. |

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | OK | StockMovementList |
| default | Any failure. See the Errors section. | Error |

### Record stock movements

`POST /v1/locations/{locationId}/stock-movements`

Scope: `stock:write`

Stability: preview

Records a document of stock changes: a delivery note, products taken from the shelf for the location's own use. Every line is applied, or none: a line that takes out more than is in stock gets the whole document refused with `insufficient_stock`. Answers `201` with the movements made, and `200` with the movements made the first time when `externalReference` was used before. A `correction` line needs the scope `stock:correct` as well, and a `delivery` line the scope `stock:cost`, since it sets what the goods cost.

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `locationId` | path | string | Yes |  |
| `Idempotency-Key` | header | string | No | A value you make up for this one request, such as a UUID. Send the same value when you retry and the first answer is returned; see Retrying safely. Example: `8e03978e-40d5-43e8-bc93-6894a57f9324`. |

**Request body**: StockDocument

**Responses**

| Status | Description | Body |
| --- | --- | --- |
| 200 | The `externalReference` was used before. Nothing in this request was applied; the movements made then are returned. | StockDocumentResult |
| 201 | The movements were made. | StockDocumentResult |
| default | Any failure. See the Errors section. | Error |

## Stocktakes

**Coming soon.** Start a count of a location's stock, send what was counted and read the differences.

## Schemas

### Error

The body of every non-2xx response.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code` | string | Yes | Stable, machine-readable error code. Values today: `invalid_request`, `validation_failed`, `entity_not_found`, `duplicate`, `merchant_required`, `code_already_used`, `gift_card_already_used`, `pin_not_recognised`, `insufficient_stock`, `not_allowed`, `request_in_progress`, `idempotency_key_reused`, `unauthenticated`, `forbidden`, `account_blocked`, `rate_limited`, `route_not_found`, `method_not_allowed`, `internal_error`. |
| `details` | object of any value | No | Extra detail. For `validation_failed`, `fieldErrors` maps each rejected field to the reason. |
| `message` | string | Yes | Human-readable explanation. Not stable; do not parse it. |

### Product

Represents an article a location sells or uses: an entry in its product list. Belongs to that location. Amounts are decimal strings in the location's currency. Quantities are whole numbers of the product.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `articleNumber` | string | No | The supplier's article number, as read from a delivery note. Not unique: two suppliers can use the same one. Example: `81650673`. |
| `averageCost` | string | No | The average cost of those in stock, VAT excluded. Only with the scope `stock:cost`. Example: `61.2311`. |
| `brand` | string | No | Example: `Wella`. |
| `createdAt` | string (date-time) | No | When it was created, in UTC. Left out when that is not known. Example: `2026-03-02T08:15:00Z`. |
| `eans` | array of string | Yes | The product's barcodes. A product can be linked to an article in a supplier's catalogue, and then that article's barcodes are included. Can be empty. Example: `["4064666230412"]`. |
| `id` | string | Yes | Product id. Example: `prd_5Tg8mPq1Xc7Jd2Ls9WbNrK`. |
| `latestPurchasePrice` | string | No | What one cost at the latest delivery, VAT excluded. Only with the scope `stock:cost`. Example: `62.4500`. |
| `locationId` | string | Yes | Example: `loc_4fK9xQ2mLr8TzB1vNc7HdW`. |
| `name` | string | Yes | Example: `Color Touch 7/0`. |
| `notForSale` | boolean | Yes | Marked as not sold to customers, such as colour used in a treatment. It is a mark only: the point of sale does not refuse to sell the product. Example: `true`. |
| `price` | string | No | The sale price, VAT included. Left out when none is set. Example: `149.00`. |
| `stockQuantity` | integer (int32) | No | The stock balance. Never negative. Left out when the product is not stock-tracked. Example: `12`. |
| `stockTracked` | boolean | Yes | Whether the location keeps a stock balance for the product. Example: `true`. |
| `updatedAt` | string (date-time) | Yes | When it last changed, in UTC. Example: `2026-10-12T09:24:31.512Z`. |
| `vatPercent` | string | No | VAT rate in per cent. Example: `25`. |

### ProductList

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of Product | Yes |  |
| `nextCursor` | string | No | Pass as `after` to fetch the next page. Absent on the last page. Example: `prd_5Tg8mPq1Xc7Jd2Ls9WbNrK`. |

### StockDocument

Stock changes that belong together, such as the rows of a delivery note or what one treatment used. Every line is applied, or none.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `comment` | string | No | A note, at most 500 characters. Stored on every movement. Example: `Colour for Anna, 14:00`. |
| `externalReference` | string | No | Your own reference for the document, such as a delivery note number, 1 to 100 characters. A document whose reference has been used at the location changes nothing and is answered with the movements made the first time, so it is safe to send again at any time. Example: `DN-2026-10412`. |
| `lines` | array of StockMovementLine | Yes | 1 to 100 lines, applied in order. |
| `staffId` | string | No | The staff member who did it. Shown as who made the movements. Example: `stf_7Qm2xLd9Kc4Vb1Ts8HpWzE`. |

### StockDocumentResult

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of StockMovement | Yes | The movements made, in the order of the lines. |

### StockMovement

One change of the stock balance of a product or of a colour bar item. A movement is never changed or removed: a mistake is undone by a new movement that corrects it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `balanceAfter` | integer (int32) | Yes | The balance after this movement. Example: `505`. |
| `colourBarItemId` | string | No | The colour bar item whose balance changed, in packs. Left out when the movement is a product's. Example: `cbi_3Vn8Kq5TzL1xWc7PdM2RbJ`. |
| `colourBarMixId` | string | No | The colour bar mix that made the movement, by finishing a pack or by being undone. Such a movement is not corrected on its own: the mix is undone. Example: `cbm_8Wq3Nd6HtY1mKx4LcP9RvB`. |
| `comment` | string | No | Example: `Colour for Anna, 14:00`. |
| `correctedByMovementId` | string | No | On a movement that has been corrected: its correction. Example: `mov_6Wr3tYu8Io1Pa4Sd7FgHjK`. |
| `correctsMovementId` | string | No | On a correction: the movement it undoes. Example: `mov_9Bd2fHk4Mn7Pq1Sv6XzCtA`. |
| `createdAt` | string (date-time) | Yes | Example: `2026-10-11T09:24:31.512Z`. |
| `externalReference` | string | No | The caller's own reference for what the movement belongs to. Example: `visit-88213`. |
| `id` | string | Yes | Movement id. Example: `mov_3Lp6vRt9Yx2Kc5Ng8QwEzH`. |
| `listValue` | string | No | On a withdrawal: what was taken, at the list price then of the article in a supplier's catalogue that it is linked to, VAT excluded, as a decimal string. Left out when there is no such list price. It is kept as it was: a later change of the list price does not change it. Example: `304.00`. |
| `productId` | string | No | The product whose balance changed. Left out when the movement is a colour bar item's. Example: `prd_5Tg8mPq1Xc7Jd2Ls9WbNrK`. |
| `quantity` | integer (int32) | Yes | The change applied to the balance: negative when stock left. Example: `-2`. |
| `reason` | string | No | Why stock was taken out: a lower-case word such as `consumption` or `damaged`. The list is open, so accept a value you do not know. Example: `consumption`. |
| `residue` | integer (int32) | No | On a withdrawal made by a colour bar mix: the grams that were never taken from the pack it finished. Example: `3`. |
| `shortfall` | integer (int32) | Yes | How much of what was asked for was not in stock; the balance never goes below 0. A sale of 3 with 1 in stock has `quantity` -1 and `shortfall` 2. 0 when everything was in stock. Example: `0`. |
| `staffId` | string | No | Who made it, when a staff member did: look the name up in the staff list. Left out for a movement made without one, such as by an administrator in Cliento. Example: `stf_7Qm2xLd9Kc4Vb1Ts8HpWzE`. |
| `type` | string | Yes | `sale` and `refund`: at the point of sale. `delivery`: goods received, or the adjustment made when a delivery is changed afterwards. `withdrawal`: taken out by hand. `correction`: undoes the movement in `correctsMovementId`. `stocktake`: the difference found by a count. `opening_balance`: the balance when movements began to be recorded for the product. More values may be added. Example: `withdrawal`. |

### StockMovementLine

One line of a stock document.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `colourBarItemId` | string | No | The colour bar item, in place of `productId`. Its `quantity` is in whole packs. Example: `cbi_3Vn8Kq5TzL1xWc7PdM2RbJ`. |
| `movementId` | string | No | For a `correction`: the withdrawal to undo. Example: `mov_9Bd2fHk4Mn7Pq1Sv6XzCtA`. |
| `productId` | string | No | The product. A `delivery` or `withdrawal` line names a product or a colour bar item, never both. Example: `prd_5Tg8mPq1Xc7Jd2Ls9WbNrK`. |
| `quantity` | integer (int32) | No | How many, as a whole number greater than 0. Required for all types but `correction`. Example: `2`. |
| `reason` | string | No | For a `withdrawal`: why, as one lower-case word such as `consumption` or `damaged`. The list is open. Example: `consumption`. |
| `type` | string | Yes | `delivery`: goods received. `withdrawal`: stock taken out. `correction`: undoes the withdrawal in `movementId`. Example: `withdrawal`. |
| `unitCost` | string | No | For a `delivery`: what one cost, VAT excluded, as a decimal string with at most four decimals. 0 when left out. Example: `62.4500`. |

### StockMovementList

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of StockMovement | Yes |  |
| `nextCursor` | string | No | Pass as `after` to fetch the next page. Absent when there is nothing more yet; to follow new movements, call again later with the id of the last movement you have read. Example: `mov_3Lp6vRt9Yx2Kc5Ng8QwEzH`. |