> ## Documentation Index
> Fetch the complete documentation index at: https://integration.delogue.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage color groups

> Create and maintain the color groups that organise your colour library for e-commerce searchability and ERP integration.

<Info>
  **When to use this.** Color groups are a **Professional-license** feature that let you bucket
  your colours into broad searchable categories — Blues, Reds, Neutrals — so that e-commerce
  platforms and downstream systems can expose a simplified color filter to end customers. You
  must create the groups here before you can assign individual colours to them in
  `POST /api/colors`. Color groups are visible under **Admin > Colors > Color Groups** in
  the Delogue UI.
</Info>

## The workflow

<Steps>
  <Step title="Create the color groups">
    `POST /api/color-groups` with one or more groups in a single all-or-nothing request. The
    call returns a 409 Conflict if any name or `userDefinedId` already exists, even within
    the same request batch.
  </Step>

  <Step title="Assign colours to the groups">
    `POST /api/colors` (or `PUT /api/colors/{id}`) — pass `colorGroupIds` containing the ids
    returned above to file colours under their groups.
  </Step>

  <Step title="List and filter groups">
    `GET /api/color-groups/filter` to search by name, state, or user-defined ID with
    page-based pagination, or `GET /api/color-groups/cursor` for cursor-based pagination
    suited to infinite-scroll UIs.
  </Step>

  <Step title="Update or retire groups">
    `PUT /api/color-groups/{id}` to rename a group or change its state to `inactive`.
    `DELETE /api/color-groups/{id}` permanently removes a group — only possible when
    no colours are still assigned to it (returns 409 otherwise).
  </Step>
</Steps>

```mermaid theme={"dark"}
sequenceDiagram
  participant D as Designer
  participant API as Delogue API
  D->>API: POST /api/color-groups  (bulk create)
  API-->>D: [{id: 561, name: "Blues"}, {id: 562, name: "Reds"}]
  D->>API: POST /api/colors  (colorGroupIds: [561])
  API-->>D: color id
  D->>API: GET /api/color-groups/filter?State=active
  API-->>D: paginated list of groups
  D->>API: PUT /api/color-groups/556  (rename or deactivate)
  API-->>D: updated group
```

## Walkthrough

Create two colour groups in a single request. The body is an array — all items are created
atomically or none at all.

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST "https://service.my.delogue.com/api/color-groups" \
    -H "Accept: application/json" \
    -H "X-Auth-Token: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '[
    {
      "name": "Blues",
      "userDefinedId": "BLU",
      "state": "active"
    },
    {
      "name": "Reds",
      "userDefinedId": "RED",
      "state": "active"
    }
  ]'
  ```

  ```js JavaScript theme={"dark"}
  const res = await fetch("https://service.my.delogue.com/api/color-groups", {
    method: "POST",
    headers: {
      "Accept": "application/json",
      "X-Auth-Token": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify([
    {
      "name": "Blues",
      "userDefinedId": "BLU",
      "state": "active"
    },
    {
      "name": "Reds",
      "userDefinedId": "RED",
      "state": "active"
    }
  ]),
  });
  const { data } = await res.json();
  ```
</CodeGroup>

```json theme={"dark"}
{
  "status": "success",
  "code": "color_groups_created",
  "data": [
    {
      "id": 561,
      "name": "Blues",
      "userDefinedId": "BLU",
      "state": "active",
      "properties": []
    },
    {
      "id": 562,
      "name": "Reds",
      "userDefinedId": "RED",
      "state": "active",
      "properties": []
    }
  ]
}
```

The response wraps the created groups in the standard envelope. Hold onto each `id` — you
pass it as a `colorGroupIds` entry when creating or updating individual colours.

## Field reference

| Field           | What it means at Delogue                                                                                            |
| --------------- | ------------------------------------------------------------------------------------------------------------------- |
| `name`          | Display name of the color group. Required and must be unique within the organisation (combined with userDefinedId). |
| `state`         | Initial lifecycle state of the color group. Defaults to active if omitted.                                          |
| `userDefinedId` | Customer-defined identifier for the color group. Optional; used to align with ERP or external system codes.         |

<Note>
  A color group can only be deleted when no colours are assigned to it. If colours are still
  linked, `DELETE /api/color-groups/{id}` returns **409 Conflict**. Reassign or remove those
  colours first, then retry the delete.
</Note>

## Roles & permissions

Managing color groups requires the **`colors`** permission on a **designer (brand)** account —
typically `CompanyAdmin` or a user with the Color Admin role. Supplier accounts collaborate on
styles but do not manage a brand's colour library or its groups. The color group feature is
only available on the **Professional license**.

## When things go wrong

Errors use the standard envelope (`status: "error"`, a `code`, and `error.details[]`). See
[Errors & responses](/concepts/errors) for the full list of codes and how to resolve them.

Common scenarios:

| Situation                                                   | HTTP | Code                                   |
| ----------------------------------------------------------- | ---- | -------------------------------------- |
| Duplicate name or `userDefinedId` (within request or in DB) | 409  | `resource_conflict_error.*`            |
| Delete a group that still has colours assigned              | 409  | `resource_conflict_error.*`            |
| Group id not found                                          | 404  | `resource_error.color_group_not_found` |
| `name` missing or too long                                  | 400  | `validation_error.*`                   |

## What to call next

<CardGroup cols={2}>
  <Card title="Colours" href="/guides/colors">
    Create individual colours and file them under these groups using `colorGroupIds`.
  </Card>

  <Card title="Seasons" href="/guides/seasons">
    Seasons are another top-level admin entity you set up before creating styles.
  </Card>

  <Card title="Size ranges" href="/guides/size-ranges">
    Define the size ranges your colours are offered in.
  </Card>

  <Card title="Color Groups API reference" href="/api-reference/color-groups/get-color-groups-by-filter">
    Full endpoint reference for `GET`, `POST`, `PUT`, and `DELETE` on `/api/color-groups`.
  </Card>
</CardGroup>