---
title: "Register a colour bar mix"
method: POST
path: "/v1/locations/{locationId}/colour-bar-mixes"
tags: ["Colour bar mixes"]
---

# Register a colour bar mix

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

## Request

- Base URL: `https://api.cliento.com`
- URL: `https://api.cliento.com/v1/locations/{locationId}/colour-bar-mixes`
- Auth: HTTP bearer

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.

## Path parameters

- `locationId` string, required

## Headers

- `Idempotency-Key` string

## Request body

- ColourBarMixCreate
  - `bowls` ColourBarMixBowlCreate[], required
    - `components` ColourBarMixComponentCreate[], required
      - `amount` integer, required: 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.
      - `colourBarItemId` string, required
      - `fromFinishedPack` integer: 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.
      - `openedNewPack` boolean: `true` when a new pack was opened for this component: the pack that was open before is then finished and leaves the stock.
    - `ratio` string: Colour to developer, such as `1:1` or `1:1.5`. Stored as it is.
    - `title` string
  - `externalReference` string: Your own id for the mix, at most 100 characters. A mix the location already has under it is returned unchanged.
  - `note` string
  - `personId` string: A person to save the mix on as a recipe, in the same call. Needs the scope `customers:write` as well.
  - `staffId` string: The staff member who mixed. Read it from the Staff API.
  - `title` string

## Response `200`

A mix with this `externalReference` already existed.

- 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.
  - `bowls` ColourBarMixBowl[], required
    - `components` ColourBarMixComponent[], required
      - `amount` integer, required: How much was taken: grams, or whole packs of an item that has no pack size.
      - `colourBarItemId` string, required
      - `fromFinishedPack` integer: The grams of `amount` that came out of the finished pack before it ran out, when a new pack was opened midway.
      - `listValue` string: 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.
      - `name` string, required: What the item was called when the mix was registered.
      - `openUsed` integer, required: The item's `openUsed` after this component.
      - `openedNewPack` boolean, required: Whether a new pack was opened for this component.
      - `packs` integer, required: The item's `packs` after this component.
      - `packsFinished` integer, required: The packs this component finished, which is what it took from stock.
      - `residue` integer: Set only when `openedNewPack` is `true`: the pack size less the grams that had been taken from the finished pack.
      - `shade` string: The item's shade when the mix was registered.
    - `ratio` string: Colour to developer, as it was sent. Kept as it is.
    - `title` string
  - `createdAt` string, date-time, required
  - `externalReference` string: Your own id for the mix.
  - `id` string, required: Colour bar mix id.
  - `listValue` string, required: 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.
  - `locationId` string, required
  - `note` string
  - `recipeId` string: The recipe the mix was saved as on a person, when it was.
  - `registeredBy` string: The name of who mixed: the staff member, or the API key when none was named.
  - `staffId` string: The staff member who mixed. Left out when none was named.
  - `title` string
  - `undoneAt` string, date-time: When the mix was undone. Left out for a mix that stands.
  - `undoneBy` string: The name of who undid the mix.
  - `updatedAt` string, date-time, required: When the mix last changed: when it was undone, otherwise `createdAt`.

## Other responses

- `201`: The mix was registered.
- `default`: Any failure. See the Errors section.

---

[API](https://skmtc.dev/cliento/apis/cliento-api.md) · [All operations](https://skmtc.dev/cliento/apis/cliento-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cliento/apis/cliento-api/revisions/29ca811bc061?raw)