Manage colours

When to use this. Colours are reusable library entities for your organisation: you create them once, optionally organise them into colour groups, and then reference them as colourways on styles. Use these endpoints to build, maintain and retire that library.

The workflow

A colour is an organisation-level record in the colour library. The usual path is to (optionally) set up colour groups for organisation, create the colours, then reference them from styles further along the product lifecycle, and update or retire them as the palette changes.

Group (optional)

POST /api/color-groups to create groups (e.g. “Blues”, “Core”) you’ll file colours under.

Create colours

POST /api/colors with the colour details, attaching colorGroupIds to file them.

Find colours

GET /api/colors with filters (name, reference, state, group) to look colours up later, or GET /api/colors/{id} to read one colour by its id.

Reference on products

Styles assign library colours as colourways, and GET /api/styles/{styleId}/items/{styleItemId}/colors shows the master colour behind each colour card on a style item. An item’s own colour cards come from GET /api/items/{itemId}/colors.

Update or retire colours

PATCH /api/colors/{id} changes only the fields you send; PUT /api/colors/{id} replaces the colour in full, and PUT /api/colors replaces many colours in one all-or-nothing request. Set state to inactive to retire a colour, or DELETE /api/colors/{id} to soft-delete one that no style colour or item colour card still uses.

Walkthrough

Create a colour and file it under a colour group. The body is an array: one or many colours are created in a single all-or-nothing transaction.

curl -X POST "https://service.my.delogue.com/api/colors" \
  -H "Accept: application/json" \
  -H "X-Auth-Token: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
  {
    "name": "Sky Blue",
    "userDefinedId": "SB-01",
    "userDefinedId2": null,
    "colorReference": "14-4318 TCX",
    "colorNote": "Spring palette",
    "state": "active",
    "colorGroupIds": [
      12
    ],
    "languageIds": [
      1
    ]
  }
]'

const res = await fetch("https://service.my.delogue.com/api/colors", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "X-Auth-Token": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify([
  {
    "name": "Sky Blue",
    "userDefinedId": "SB-01",
    "userDefinedId2": null,
    "colorReference": "14-4318 TCX",
    "colorNote": "Spring palette",
    "state": "active",
    "colorGroupIds": [
      12
    ],
    "languageIds": [
      1
    ]
  }
]),
});
const { data } = await res.json();

{
  "status": "success",
  "code": "colors_created",
  "data": [
    {
      "id": 2579,
      "name": "Sky Blue",
      "userDefinedId": "SB-01",
      "userDefinedId2": null,
      "colorReference": "14-4318 TCX",
      "state": "active",
      "colorNote": "Spring palette",
      "colorGroups": [
        {
          "id": 12,
          "name": "Greens",
          "userDefinedId": "GRN",
          "state": "active"
        }
      ],
      "languageNames": [],
      "properties": []
    }
  ]
}

The response wraps the created colours in the standard envelope. Hold onto each id: styles reference colours by it.

Field reference

The fields that matter most when creating or updating a colour:

Field	What it means at Delogue
`colorGroupIds`	IDs of the colour groups to associate with the new colour.
`colorNote`	Free-text note describing the colour.
`colorReference`	Colour reference code, e.g. a Pantone code.
`languageIds`	IDs of the languages to link the colour to. The translated text per language is managed by a separate endpoint.
`name`	Display name of the colour. Required.
`state`	Initial lifecycle state. Defaults to active.
`userDefinedId`	Customer-defined identifier (ID1).
`userDefinedId2`	Secondary customer-defined identifier (ID2).

Updating a colour: PUT vs PATCH

PUT is a full replace: send every field you want to keep, because an omitted optional field or collection is cleared. PATCH takes an RFC 6902 JSON Patch document (Content-Type: application/json-patch+json) and changes only the paths you send.

Field	`PUT /api/colors/{id}` and `PUT /api/colors`	`PATCH /api/colors/{id}`
`id`	Single `PUT` takes the id from the route; an `id` in the body returns 400. Each bulk `PUT` item must carry the `id` of the colour it replaces.	Taken from the route. A `replace /id` to a different value returns 409.
`name`, `state`	Required. Missing or `null` returns 400.	Kept unless you replace them. `name` cannot be cleared.
`userDefinedId`, `userDefinedId2`, `colorReference`, `colorNote`	Sending `null` or omitting the field clears it.	Kept when omitted; a `replace` with `null` clears the field.
`colorGroupIds`	A populated list replaces the memberships; `[]`, `null` or omitting the field clears them all.	Kept when no operation touches it. Once touched, the resulting array is the full set: ids not in it are removed, and `replace /colorGroupIds []` clears them all.
`languageIds`	As `colorGroupIds`, when your organisation has the multiple-language feature on. With it off, a populated list returns 400 and an empty, `null` or omitted one leaves the existing links untouched.	As `colorGroupIds`, subject to the same multiple-language feature.

An unknown colour group or language id is rejected with an error pointing at its position (colorGroupIds[i], languageIds[k]; items[n].… in a bulk PUT). A PATCH path that is not on the update body (e.g. /organizationId) returns 422, and a failed test operation returns 409. In a bulk PUT, sending state: "deleted" on an item soft-deletes that colour.

Roles & permissions

Managing the colour library requires admin-level colors permission on a designer (brand) account: typically CompanyAdmin. Supplier accounts collaborate on styles but do not manage a brand’s colour library: reading a colour by id with GET /api/colors/{id} is open to any designer user, and a supplier caller receives 403.

When things go wrong

Errors use the standard envelope (status: "error", a code, and error.details[]). See Errors & responses for the full list of codes and how to resolve them. Cases specific to reading, updating and deleting a colour by id:

403 authorization_error.color_access_denied: GET, PUT or PATCH on a colour that belongs to another organisation.
404 resource_error.color_not_found: the id exists in no organisation. DELETE also returns 404 for a colour in another organisation.
409 resource_conflict_error (detail color_deleted_conflict): DELETE on a colour still used by a style colour or an item colour card. Set it to inactive instead, or remove those references first.

What to call next

Colour groups

Organise colours into groups for filtering and reuse.

Style colours

Assign library colours to a style as its colourways.

Item colours

Read an item’s own colour cards: GET /api/items/{itemId}/colors.

Style-item colours

Colours on a style’s items: GET /api/styles/{styleId}/items/{styleItemId}/colors.

Authentication

How to get and send your X-Auth-Token API key.

Getting Started

Concepts

Guides

The workflow

Walkthrough

Field reference

Updating a colour: PUT vs PATCH

Roles & permissions

When things go wrong

What to call next

Colour groups

Style colours

Item colours

Style-item colours

Authentication

​The workflow

​Walkthrough

​Field reference

​Updating a colour: PUT vs PATCH

​Roles & permissions

​When things go wrong

​What to call next

Colour groups

Style colours

Item colours

Style-item colours

Authentication

The workflow

Walkthrough

Field reference

Updating a colour: PUT vs PATCH

Roles & permissions

When things go wrong

What to call next