Cliento API reference: Colour bar

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

The Colour bar APIs are for hair salons. They let an integration manage a salon's stock of hair colour and keep it correct as the colour is used.

Hair colour is not sold to the customer. It is used a little at a time: a tube is opened, and each mix takes some grams from it. The colour bar keeps track of both the packs in stock and how much is left in the open one.

There are three APIs:

Colour bar ranges. A range is a supplier's series, such as one brand's permanent colours.
Colour bar items. An item is one shade in a range. Each item has its own stock.
Colour bar mixes. A mix is what a staff member mixed for one customer. Registering a mix takes the grams used from each item's stock.

Deliveries are recorded through the Stock movements API.

Colour bar ranges

Industry: hair and beauty. The Colour bar ranges API lets an integration read a salon's ranges and create, change and delete them.

A range is a supplier's series, such as one brand's permanent colours. It has an id of the form cbr_... and belongs to a location. The items of a range share three settings, which are set on the range: kind, packSize and listPrice.

Ranges are under /v1/locations/{locationId}/colour-bar-ranges. A range is also read by its id, without its location, at /v1/colour-bar-ranges/{colourBarRangeId}. Reading needs the scope products:read. Writing needs stock:write.

kind is a lower-case word such as colour, bleach or developer. The list is open: send the word that fits.
A range without a packSize is one whose items are used a whole pack at a time, such as a treatment. Its items have no open pack, except an item with a packSize of its own.
listPrice is the supplier's list price of one pack, VAT excluded. It is what the location values its use of the range's items at, and is not what the location paid.
An item can have a packSize and a listPrice of its own. Changing the range's packSize or listPrice changes what applies to every item without a value of its own.
A range that still has items cannot be deleted. Delete its items first.

List colour bar ranges

GET /v1/locations/{locationId}/colour-bar-ranges

Scope: products:read

Stability: preview

The location's colour bar ranges by name, one page at a time.

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.

Responses

Status	Description	Body
200	OK	ColourBarRangeList
default	Any failure. See the Errors section.	Error

Create a colour bar range

POST /v1/locations/{locationId}/colour-bar-ranges

Scope: stock:write

Stability: preview

Adds a range to the location's colour bar. It holds no items until they are created. Send an Idempotency-Key so that a repeat of the call does not add the range twice.

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: ColourBarRangeCreate

Responses

Status	Description	Body
201	Created	ColourBarRange
default	Any failure. See the Errors section.	Error

Get a colour bar range

GET /v1/locations/{locationId}/colour-bar-ranges/{colourBarRangeId}

Scope: products:read

Stability: preview

Parameters

Name	In	Type	Required	Description
`locationId`	path	string	Yes
`colourBarRangeId`	path	string	Yes

Responses

Status	Description	Body
200	OK	ColourBarRange
default	Any failure. See the Errors section.	Error

Get a colour bar range by id

GET /v1/colour-bar-ranges/{colourBarRangeId}

Scope: products:read

Stability: preview

The same colour bar range 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
`colourBarRangeId`	path	string	Yes

Responses

Status	Description	Body
200	OK	ColourBarRange
default	Any failure. See the Errors section.	Error

Update a colour bar range

PATCH /v1/locations/{locationId}/colour-bar-ranges/{colourBarRangeId}

Scope: stock:write

Stability: preview

Changes only the fields in the request. Either all of them are changed or none. See ColourBarRangeUpdate for how to clear a field.

Parameters

Name	In	Type	Required	Description
`locationId`	path	string	Yes
`colourBarRangeId`	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: ColourBarRangeUpdate

Responses

Status	Description	Body
200	OK	ColourBarRange
default	Any failure. See the Errors section.	Error

Delete a colour bar range

DELETE /v1/locations/{locationId}/colour-bar-ranges/{colourBarRangeId}

Scope: stock:write

Stability: preview

Deleting a range that still has items is refused with not_allowed. Delete its items first.

Parameters

Name	In	Type	Required	Description
`locationId`	path	string	Yes
`colourBarRangeId`	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`.

Responses

Status	Description	Body
204	No Content
default	Any failure. See the Errors section.	Error

Colour bar items

Industry: hair and beauty. The Colour bar items API lets an integration read a salon's colour bar items and create, change and delete them.

An item is one shade in a range. It can also be one strength of a developer or one tub of bleach. It has an id of the form cbi_... and belongs to its range's location.

Each item has its own stock. The stock is counted in packs. The item also keeps how many grams have been taken from the open pack.

An item is not a product. A product is sold at a point of sale and is read through the Products API. An item is used in the salon and is never sold.

Items are under /v1/locations/{locationId}/colour-bar-items. An item is also read by its id, without its location, at /v1/colour-bar-items/{colourBarItemId}. Reading needs the scope products:read. Writing needs stock:write.

Stock is counted in packs, and the open pack counts as one. packs is 4 for three unopened tubes and one that is open. openUsed is the grams that have been taken from the open pack, and 0 when none is open.
unopenedPacks, openLeft and gramsLeft are worked out from packs, openUsed and the pack size, and are read-only.
packs and openUsed are read-only here. A delivery adds packs and a withdrawal takes them: record both through the Stock movements API, on a line with the item's colourBarItemId and the quantity in whole packs. openUsed changes when a colour bar mix is registered, in Cliento or through the Colour bar mixes API.
An item follows its range's packSize and listPrice unless it has its own. The item's own values are packSize and listPrice; packSizeInUse and listPriceInUse are what applies.
eans holds the item's barcodes. An item made from an article in a supplier's catalogue also has that article's barcodes, which catalogueEans lists. Only the item's own barcodes are added and removed here.
To find the item for a scanned barcode or a row of a delivery note, list with ean or articleNumber. Look up the barcode first: a supplier can change its article numbers, and a barcode stays with the pack.
A range holds a shade once: a second item with the same shade is refused with duplicate.
An item without a name of its own is called by its shade.

List colour bar items

GET /v1/locations/{locationId}/colour-bar-items

Scope: products:read

Stability: preview

The location's colour bar items, range by range and shade by shade, one page at a time. With ean or articleNumber it is a lookup: the item a scanned barcode or a delivery note row belongs to, at most 20 items. Send one of rangeId, ean and articleNumber, or none.

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.
`rangeId`	query	string	No	Only the items of this colour bar range.
`ean`	query	string	No	Only items with this barcode: their own, or that of the supplier's article they were made from.
`articleNumber`	query	string	No	Only items with exactly this article number.

Responses

Status	Description	Body
200	OK	ColourBarItemList
default	Any failure. See the Errors section.	Error

Create a colour bar item

POST /v1/locations/{locationId}/colour-bar-items

Scope: stock:write

Stability: preview

Adds an item to a colour bar range. It starts with no stock. Send an Idempotency-Key so that a repeat of the call does not add the item twice. A shade the range already holds, or a barcode that another item or a product of the location has, is refused with duplicate.

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: ColourBarItemCreate

Responses

Status	Description	Body
201	Created	ColourBarItem
default	Any failure. See the Errors section.	Error

Get a colour bar item

GET /v1/locations/{locationId}/colour-bar-items/{colourBarItemId}

Scope: products:read

Stability: preview

Parameters

Name	In	Type	Required	Description
`locationId`	path	string	Yes
`colourBarItemId`	path	string	Yes

Responses

Status	Description	Body
200	OK	ColourBarItem
default	Any failure. See the Errors section.	Error

Get a colour bar item by id

GET /v1/colour-bar-items/{colourBarItemId}

Scope: products:read

Stability: preview

The same colour bar item 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
`colourBarItemId`	path	string	Yes

Responses

Status	Description	Body
200	OK	ColourBarItem
default	Any failure. See the Errors section.	Error

Update a colour bar item

PATCH /v1/locations/{locationId}/colour-bar-items/{colourBarItemId}

Scope: stock:write

Stability: preview

Changes only the fields in the request. Either all of them are changed or none. See ColourBarItemUpdate for how to clear a field. An item stays in its range, and its stock is not changed here.

Parameters

Name	In	Type	Required	Description
`locationId`	path	string	Yes
`colourBarItemId`	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: ColourBarItemUpdate

Responses

Status	Description	Body
200	OK	ColourBarItem
default	Any failure. See the Errors section.	Error

Delete a colour bar item

DELETE /v1/locations/{locationId}/colour-bar-items/{colourBarItemId}

Scope: stock:write

Stability: preview

Removes the item from the colour bar with whatever stock it holds, and frees its own barcodes.

Parameters

Name	In	Type	Required	Description
`locationId`	path	string	Yes
`colourBarItemId`	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`.

Responses

Status	Description	Body
204	No Content
default	Any failure. See the Errors section.	Error

Add a barcode to a colour bar item

POST /v1/locations/{locationId}/colour-bar-items/{colourBarItemId}/eans

Scope: stock:write

Stability: preview

Gives the item a barcode of its own, as when a delivery row was matched by its article number and its barcode is new. A barcode that another item or a product of the location has is refused with duplicate.

Parameters

Name	In	Type	Required	Description
`locationId`	path	string	Yes
`colourBarItemId`	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: ColourBarBarcode

Responses

Status	Description	Body
200	OK	ColourBarItem
default	Any failure. See the Errors section.	Error

Remove a barcode from a colour bar item

DELETE /v1/locations/{locationId}/colour-bar-items/{colourBarItemId}/eans/{ean}

Scope: stock:write

Stability: preview

Removes one of the item's own barcodes. Removing one of its catalogueEans is refused with not_allowed.

Parameters

Name	In	Type	Required	Description
`locationId`	path	string	Yes
`colourBarItemId`	path	string	Yes
`ean`	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`.

Responses

Status	Description	Body
200	OK	ColourBarItem
default	Any failure. See the Errors section.	Error

Colour bar mixes

Industry: hair and beauty. The Colour bar mixes API lets an integration register what staff mix, read it, undo it and total it per staff member. It is for an integration that weighs or doses colour itself and wants Cliento's stock and totals to follow.

A mix is what a staff member mixed for one customer. It has an id of the form cbm_... and belongs to a location. A mix has one or more bowls. A bowl has components. A component names one colour bar item and how many grams were taken from it.

Registering a mix takes the grams used from each item's stock. The grams are added to the item's openUsed. When a pack is finished, the item's packs goes down by one. That change is recorded as a stock movement of the type withdrawal.

Mixes are under /v1/locations/{locationId}/colour-bar-mixes. A mix is also read by its id, without its location, at /v1/colour-bar-mixes/{colourBarMixId}. Reading needs the scope products:read. Registering needs stock:write. Undoing needs stock:correct.

Amounts are whole grams, as weighed. For an item with no pack size the amount is whole packs.
A pack leaves the stock when it is finished. The caller says so with openedNewPack: true on the component for which a new pack was opened. If the finished pack ran out midway, fromFinishedPack says how many grams of the amount still came out of it. What was never taken from the finished pack is kept on the component as residue.
A pack also counts as finished without the caller saying so, when more has been taken from it than it holds, unless the location has switched that off in Cliento. That setting is not readable through the API: read packsFinished on each component of the answer to see what the mix took from stock.
A mix is never refused because an item is out of stock. What was mixed has been mixed; the item's packs stays at 0.
listValue is what the mix took at the supplier's list price, VAT excluded, worked out when the mix is registered and kept. A later change of a list price does not change it. A component's listValue has up to four decimals; the mix's is their sum rounded to two.
Give the mix your own externalReference. Sending the same reference again changes nothing and answers 200 with the mix made the first time, also when that mix has been undone. A reference already used for a mix by another staff member is refused with not_allowed. To find the mix for a reference, list with externalReference.
staffId names the staff member who mixed. Read it from the Staff API.
personId also saves the mix on that person as a recipe, in the same call, and the mix then carries its recipeId. It needs the scope customers:write as well.
A mix is not changed. A mistake is undone: every pack the mix took is put back, the grams it added to each item's openUsed are taken off again, and its recipe is removed. The mix is then registered again under a new externalReference. An undone mix stays readable, with undoneAt.
The summary totals the mixes of a period per staff member at listValue, leaving out the ones that were undone. A location uses these totals to charge the colour used to a staff member who rents a chair.
A location that keeps medical records, such as a clinic, has no colour bar mixes: every call is refused with not_allowed.

List colour bar mixes

GET /v1/locations/{locationId}/colour-bar-mixes

Scope: products:read

Stability: preview

The location's mixes, newest first, one page at a time, including those that were undone. With staffId, one staff member's. With externalReference, the mix registered under that reference, if there is one; it is sent without staffId and after.

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.
`staffId`	query	string	No	Only the mixes of this staff member.
`externalReference`	query	string	No	Only the mix with this external reference. Not together with `staffId` or `after`.

Responses

Status	Description	Body
200	OK	ColourBarMixList
default	Any failure. See the Errors section.	Error

Register a colour bar mix

POST /v1/locations/{locationId}/colour-bar-mixes

Scope: stock:write

Stability: preview

Registers what was mixed and changes the colour bar items it names. It is never refused because an item is out of stock: what was mixed has been mixed. Send an externalReference, your own id for the mix, to make the call safe to repeat: when the location already has a mix under it, that mix is returned unchanged with 200, and a reference used for another staff member's mix is refused with not_allowed. With personId the mix is also saved on that person as a recipe, which needs the scope customers:write as well. Not available at a location that keeps medical records.

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: ColourBarMixCreate

Responses

Status	Description	Body
200	A mix with this `externalReference` already existed.	ColourBarMix
201	The mix was registered.	ColourBarMix
default	Any failure. See the Errors section.	Error

Get a colour bar mix

GET /v1/locations/{locationId}/colour-bar-mixes/{colourBarMixId}

Scope: products:read

Stability: preview

Parameters

Name	In	Type	Required	Description
`locationId`	path	string	Yes
`colourBarMixId`	path	string	Yes

Responses

Status	Description	Body
200	OK	ColourBarMix
default	Any failure. See the Errors section.	Error

Get a colour bar mix by id

GET /v1/colour-bar-mixes/{colourBarMixId}

Scope: products:read

Stability: preview

The same colour bar mix as under its location, found from its id. For a caller that holds an id and not the location it belongs to, such as one read from a stock movement. The answer carries locationId.

Parameters

Name	In	Type	Required	Description
`colourBarMixId`	path	string	Yes

Responses

Status	Description	Body
200	OK	ColourBarMix
default	Any failure. See the Errors section.	Error

Total colour bar mixes per staff member

GET /v1/locations/{locationId}/colour-bar-mixes/summary

Scope: products:read

Stability: preview

What was mixed from from to to, both days included, in the location's time zone, per staff member, at list price. Mixes that were undone are left out. The period is at most 366 days. A location uses these totals to charge the colour used to a staff member who rents a chair.

Parameters

Name	In	Type	Required	Description
`locationId`	path	string	Yes
`from`	query	string (date)	Yes	The first day, as `YYYY-MM-DD`.
`to`	query	string (date)	Yes	The last day, as `YYYY-MM-DD`.
`staffId`	query	string	No	Only this staff member.

Responses

Status	Description	Body
200	OK	ColourBarMixSummary
default	Any failure. See the Errors section.	Error

Undo a colour bar mix

POST /v1/locations/{locationId}/colour-bar-mixes/{colourBarMixId}/undo

Scope: stock:correct

Stability: preview

Undoes the whole mix, once: every pack it took is put back, the grams it added to each item's openUsed are taken off again, and the recipe it was saved as is removed. The mix stays, with undoneAt. A mix that is already undone is refused with not_allowed.

Parameters

Name	In	Type	Required	Description
`locationId`	path	string	Yes
`colourBarMixId`	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: ColourBarMixUndo

Responses

Status	Description	Body
200	OK	ColourBarMix
default	Any failure. See the Errors section.	Error

Schemas

ColourBarBarcode

Field	Type	Required	Description
`ean`	string	Yes	The barcode, at most 50 characters. Example: `4064666230412`.

ColourBarItem

Represents one thing a location mixes from at its colour bar: one shade of a colour, one strength of a developer, one tub of bleach. Belongs to a colour bar range and to the range's location. Holds its own balance in the location's stock, counted in packs, and how much has been taken from the pack that is open. It is not a product: it is never sold at a point of sale.

Field	Type	Required	Description
`articleNumber`	string	No	The supplier's article number, as read from a delivery note. Example: `99350118254`.
`catalogueEans`	array of string	Yes	Read-only. Those of `eans` that the item has from the article in a supplier's catalogue it was made from. They are not the item's own and cannot be removed from it. Can be empty. Example: `[]`.
`createdAt`	string (date-time)	Yes	Example: `2026-10-12T08:15:30Z`.
`eans`	array of string	Yes	The item's barcodes: its own, and those in `catalogueEans`. Can be empty. Example: `["4064666230412"]`.
`gramsLeft`	integer (int64)	No	Read-only. Grams left in all the item's packs together. Left out when the item has no pack size. Example: `203`.
`id`	string	Yes	Colour bar item id. Example: `cbi_3Vn8Kq5TzL1xWc7PdM2RbJ`.
`listPrice`	string	No	The list price of one pack, VAT excluded, where the item differs from its range. Left out when the item follows the range's `listPrice`. Example: `137.00`.
`listPriceInUse`	string	No	Read-only. The list price that applies: the item's own, otherwise its range's. Example: `137.00`.
`locationId`	string	Yes	Example: `loc_4fK9xQ2mLr8TzB1vNc7HdW`.
`name`	string	Yes	What the item is called. An item without a name of its own is called by its `shade`, and follows it when the shade is changed. Example: `7/10`.
`openLeft`	integer (int32)	No	Read-only. Grams left in the open pack. Left out when no pack is open or the item has no pack size. Example: `23`.
`openUsed`	integer (int32)	Yes	Read-only. Grams taken from the open pack. `0` when no pack is open. Example: `37`.
`packSize`	integer (int32)	No	Grams in one pack, where the item differs from its range. Left out when the item follows the range's `packSize`. Example: `60`.
`packSizeInUse`	integer (int32)	No	Read-only. The pack size that applies: the item's own, otherwise its range's. Left out for an item used a whole pack at a time. Example: `60`.
`packs`	integer (int32)	Yes	Read-only. The packs in stock, the open one included. Never negative. Example: `4`.
`rangeId`	string	Yes	The range the item belongs to. Set when the item is created. Example: `cbr_7Hc2Lm9QxT4vBn6KdR1WsP`.
`shade`	string	No	The shade of a colour, as the supplier writes it. Example: `7/10`.
`strengthPercent`	string	No	The strength of a developer in per cent, as a decimal string. Example: `6`.
`unopenedPacks`	integer (int32)	Yes	Read-only. The packs that are not opened. Example: `3`.
`updatedAt`	string (date-time)	Yes	When the item last changed, which includes its stock and its own barcodes. Example: `2026-10-12T08:15:30Z`.

ColourBarItemCreate

Field	Type	Required	Description
`articleNumber`	string	No	Example: `99350118254`.
`eans`	array of string	No	The item's own barcodes. A barcode that another item or a product of the location has is refused. Example: `["4064666230412"]`.
`listPrice`	string	No	The list price of one pack, VAT excluded, when the item differs from its range. Example: `149.00`.
`name`	string	No	What the item is called. Required when there is no `shade`. Example: `Blondor Multi Blonde`.
`packSize`	integer (int32)	No	Grams in one pack, when the item differs from its range. Example: `60`.
`rangeId`	string	Yes	The range the item belongs to. Example: `cbr_7Hc2Lm9QxT4vBn6KdR1WsP`.
`shade`	string	No	The shade of a colour, at most 50 characters. A range holds a shade once. Example: `7/10`.
`strengthPercent`	string	No	The strength of a developer in per cent, greater than 0, at most 100. Example: `6`.

ColourBarItemList

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

ColourBarItemUpdate

A JSON merge patch: send only what changes. A field you leave out keeps its value; a field set to null is cleared, but an item must keep a name or a shade. A name equal to the shade is not a name of its own: the item is called by its shade and follows it. Clearing packSize or listPrice makes the item follow its range again.

Field	Type	Required	Description
`articleNumber`	string	No	Example: `99350118254`.
`listPrice`	string	No	Example: `149.00`.
`name`	string	No	Example: `Blondor Multi Blonde`.
`packSize`	integer (int32)	No	Example: `60`.
`shade`	string	No	Example: `7/10`.
`strengthPercent`	string	No	Example: `6`.

ColourBarMix

Represents what one staff member mixed at a location's colour bar at one time: one or more bowls, each with the colour bar items it took from and how much of each. Belongs to a location. Registering it changes the items it names: what was taken is added to an item's openUsed, and a pack is taken from stock when one is finished. A mix is not changed afterwards; it can be undone.

Field	Type	Required	Description
`bowls`	array of ColourBarMixBowl	Yes
`createdAt`	string (date-time)	Yes	Example: `2026-10-12T08:15:30Z`.
`externalReference`	string	No	Your own id for the mix. Example: `mix-2026-10-12-0042`.
`id`	string	Yes	Colour bar mix id. Example: `cbm_8Wq3Nd6HtY1mKx4LcP9RvB`.
`listValue`	string	Yes	What the mix took, at the list prices then, VAT excluded: its components' `listValue` together, rounded to two decimals, as a decimal string in the location's currency. Example: `91.33`.
`locationId`	string	Yes	Example: `loc_4fK9xQ2mLr8TzB1vNc7HdW`.
`note`	string	No	Example: `35 min`.
`recipeId`	string	No	The recipe the mix was saved as on a person, when it was. Example: `rcp_6Jn2Xw8QdT5bVh3ZmK7LsF`.
`registeredBy`	string	No	The name of who mixed: the staff member, or the API key when none was named. Example: `Anna`.
`staffId`	string	No	The staff member who mixed. Left out when none was named. Example: `stf_2Hs7Bq4MnX9cLk1VtR6PzD`.
`title`	string	No	Example: `Roots and lengths`.
`undoneAt`	string (date-time)	No	When the mix was undone. Left out for a mix that stands. Example: `2026-10-12T09:02:11Z`.
`undoneBy`	string	No	The name of who undid the mix. Example: `Anna`.
`updatedAt`	string (date-time)	Yes	When the mix last changed: when it was undone, otherwise `createdAt`. Example: `2026-10-12T08:15:30Z`.

ColourBarMixBowl

One bowl of a mix.

Field	Type	Required	Description
`components`	array of ColourBarMixComponent	Yes
`ratio`	string	No	Colour to developer, as it was sent. Kept as it is. Example: `1:1`.
`title`	string	No	Example: `Roots`.

ColourBarMixBowlCreate

Field	Type	Required	Description
`components`	array of ColourBarMixComponentCreate	Yes
`ratio`	string	No	Colour to developer, such as `1:1` or `1:1.5`. Stored as it is. Example: `1:1`.
`title`	string	No	Example: `Roots`.

ColourBarMixComponent

What a mix took from one colour bar item, and how that left the item.

Field	Type	Required	Description
`amount`	integer (int32)	Yes	How much was taken: grams, or whole packs of an item that has no pack size. Example: `30`.
`colourBarItemId`	string	Yes	Example: `cbi_3Vn8Kq5TzL1xWc7PdM2RbJ`.
`fromFinishedPack`	integer (int32)	No	The grams of `amount` that came out of the finished pack before it ran out, when a new pack was opened midway. Example: `12`.
`listValue`	string	No	What `amount` was worth at the list price then, VAT excluded, as a decimal string with up to four decimals. Left out when the item had no list price. Example: `68.5000`.
`name`	string	Yes	What the item was called when the mix was registered. Example: `7/10`.
`openUsed`	integer (int32)	Yes	The item's `openUsed` after this component. Example: `30`.
`openedNewPack`	boolean	Yes	Whether a new pack was opened for this component. Example: `false`.
`packs`	integer (int32)	Yes	The item's `packs` after this component. Example: `4`.
`packsFinished`	integer (int32)	Yes	The packs this component finished, which is what it took from stock. Example: `0`.
`residue`	integer (int32)	No	Set only when `openedNewPack` is `true`: the pack size less the grams that had been taken from the finished pack. Example: `3`.
`shade`	string	No	The item's shade when the mix was registered. Example: `7/10`.

ColourBarMixComponentCreate

Field	Type	Required	Description
`amount`	integer (int32)	Yes	How much was taken, as a whole number greater than 0: grams as weighed, or whole packs of an item that has no pack size. Example: `30`.
`colourBarItemId`	string	Yes	Example: `cbi_3Vn8Kq5TzL1xWc7PdM2RbJ`.
`fromFinishedPack`	integer (int32)	No	With `openedNewPack`: the grams of `amount` that still came out of the finished pack before it ran out. Leave out when the whole amount came from the new pack. Refused with `validation_failed` for an item that has no pack size. Example: `12`.
`openedNewPack`	boolean	No	`true` when a new pack was opened for this component: the pack that was open before is then finished and leaves the stock. Example: `false`.

ColourBarMixCreate

Field	Type	Required	Description
`bowls`	array of ColourBarMixBowlCreate	Yes
`externalReference`	string	No	Your own id for the mix, at most 100 characters. A mix the location already has under it is returned unchanged. Example: `mix-2026-10-12-0042`.
`note`	string	No	Example: `35 min`.
`personId`	string	No	A person to save the mix on as a recipe, in the same call. Needs the scope `customers:write` as well. Example: `per_9Tk4Yc1WvN7pQe2XhB5MdG`.
`staffId`	string	No	The staff member who mixed. Read it from the Staff API. Example: `stf_2Hs7Bq4MnX9cLk1VtR6PzD`.
`title`	string	No	Example: `Roots and lengths`.

ColourBarMixList

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

ColourBarMixStaffTotal

What one staff member mixed over the period, mixes that were undone left out.

Field	Type	Required	Description
`listValue`	string	Yes	Their `listValue` together, as a decimal string. Example: `3480.25`.
`mixes`	integer (int32)	Yes	How many mixes. Example: `42`.
`name`	string	No	Example: `Anna`.
`staffId`	string	No	The staff member. Left out for mixes registered with no staff member. Example: `stf_2Hs7Bq4MnX9cLk1VtR6PzD`.

ColourBarMixSummary

What was mixed at a location from one day to another, per staff member, at list price.

Field	Type	Required	Description
`from`	string (date)	Yes	Example: `2026-10-01`.
`listValue`	string	Yes	The `listValue` of all `staff` together, as a decimal string. Example: `12940.75`.
`staff`	array of ColourBarMixStaffTotal	Yes	One total per staff member who mixed.
`to`	string (date)	Yes	Example: `2026-10-31`.

ColourBarMixUndo

Field	Type	Required	Description
`staffId`	string	No	The staff member who undoes the mix. Read it from the Staff API. Example: `stf_2Hs7Bq4MnX9cLk1VtR6PzD`.

ColourBarRange

Represents a supplier's series as a location keeps it at its colour bar, such as one brand's permanent colours. Belongs to a location. Holds what its items have in common: their kind, the size of a pack and its list price. Colour bar items belong to it.

Field	Type	Required	Description
`brand`	string	No	Example: `Wella`.
`createdAt`	string (date-time)	Yes	Example: `2026-10-12T08:15:30Z`.
`id`	string	Yes	Colour bar range id. Example: `cbr_7Hc2Lm9QxT4vBn6KdR1WsP`.
`kind`	string	Yes	What the range's items are used as, such as `colour` or `developer`. A lower-case word; the list is open. Example: `colour`.
`listPrice`	string	No	The supplier's list price of one pack, VAT excluded, as a decimal string in the location's currency. Example: `137.00`.
`locationId`	string	Yes	Example: `loc_4fK9xQ2mLr8TzB1vNc7HdW`.
`name`	string	Yes	What the range is called at the location. Example: `Koleston Perfect ME+`.
`packSize`	integer (int32)	No	Grams in one pack of the range's items. Left out for a range whose items are used a whole pack at a time. Example: `60`.
`series`	string	No	The supplier's name of the series. Example: `KP ME+`.
`updatedAt`	string (date-time)	Yes	When the range itself was last changed. Example: `2026-10-12T08:15:30Z`.

ColourBarRangeCreate

Field	Type	Required	Description
`brand`	string	No	Example: `Wella`.
`kind`	string	Yes	What the range's items are used as, such as `colour` or `developer`: a lower-case word of at most 30 characters. Example: `colour`.
`listPrice`	string	No	The supplier's list price of one pack, VAT excluded. Example: `137.00`.
`name`	string	Yes	What the range is called at the location, at most 255 characters. Example: `Koleston Perfect ME+`.
`packSize`	integer (int32)	No	Grams in one pack. Leave out for a range whose items are used a whole pack at a time. Example: `60`.
`series`	string	No	The supplier's name of the series. Example: `KP ME+`.

ColourBarRangeList

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

ColourBarRangeUpdate

A JSON merge patch: send only what changes. A field you leave out keeps its value; a field set to null is cleared. name and kind cannot be cleared.

Field	Type	Required	Description
`brand`	string	No	Example: `Wella`.
`kind`	string	No	Example: `colour`.
`listPrice`	string	No	Example: `137.00`.
`name`	string	No	Example: `Koleston Perfect ME+`.
`packSize`	integer (int32)	No	Grams in one pack. Changing it changes the pack size of every item of the range that has none of its own. Example: `60`.
`series`	string	No	Example: `KP ME+`.

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.