> ## 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 item categories
> Build and maintain the item category library that classifies your component items — fabrics, buttons, labels, packaging, and more.
**When to use this.** Item categories are admin-level reference data that organise your
item library by component type. Every item in Delogue can be filed under a category (e.g.
Fabric, Buttons, Packaging) so that designers can filter items when building style BOMs.
Set up your category list before creating items — items reference categories by ID at
creation time. Use these endpoints to create, rename, activate, and retire categories.
## The workflow
Item categories are reusable organisation records scoped to your brand. The usual flow is
to create the category taxonomy once, then reference categories when creating items. Inactive
categories stay on existing items but are hidden from the picker for new ones.
`POST /api/item-categories` with one or more category objects — name and optional initial
state. A single request creates all categories in one all-or-nothing transaction.
`GET /api/item-categories` with optional filters (`Search`, `State`, `Names`) to look up
existing categories or build a picker list.
When creating or updating items, supply the category ID in the item body. Use
`GET /api/item-categories` to resolve a name to an ID if needed.
`PUT /api/item-categories/{id}` to rename or change state. Set `state` to `inactive` to
hide from the picker while keeping history. Use
`DELETE /api/item-categories/{id}` for a soft-delete (sets the record inactive).
```mermaid theme={"dark"}
sequenceDiagram
participant D as Designer
participant API as Delogue API
D->>API: POST /api/item-categories (Packaging, Labels)
API-->>D: category ids [9801, 9802]
D->>API: GET /api/item-categories?Search=Pack
API-->>D: [{ id: 9801, name: "Packaging", state: "active" }]
D->>API: POST /api/items (referencing categoryId: 9801)
API-->>D: item id
```
## Walkthrough
Create two item categories in a single request. The body is an array — all items are
created atomically.
```bash cURL theme={"dark"}
curl -X POST "https://service.my.delogue.com/api/item-categories" \
-H "Accept: application/json" \
-H "X-Auth-Token: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '[
{
"name": "Packaging",
"state": "active"
},
{
"name": "Labels",
"state": "active"
}
]'
```
```js JavaScript theme={"dark"}
const res = await fetch("https://service.my.delogue.com/api/item-categories", {
method: "POST",
headers: {
"Accept": "application/json",
"X-Auth-Token": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify([
{
"name": "Packaging",
"state": "active"
},
{
"name": "Labels",
"state": "active"
}
]),
});
const { data } = await res.json();
```
```json theme={"dark"}
{
"status": "success",
"code": "item_categories_created",
"data": [
{
"id": 9801,
"name": "Packaging",
"state": "active",
"usedInItems": 0,
"beginDate": "2026-06-30T10:00:00.000Z",
"endDate": "9999-12-31T23:59:59.999Z",
"properties": []
},
{
"id": 9802,
"name": "Labels",
"state": "active",
"usedInItems": 0,
"beginDate": "2026-06-30T10:00:00.000Z",
"endDate": "9999-12-31T23:59:59.999Z",
"properties": []
}
]
}
```
The response wraps the created categories in the standard envelope. Hold onto each `id` —
items reference categories by it.
## Field reference
| Field | What it means at Delogue |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Display name of the item category. Required; maximum 200 characters. |
| `state` | Initial lifecycle state. Omit or pass active for an immediately selectable category; inactive creates a deactivated category. Passing deleted is rejected with 400 — use DELETE after creating. |
`PUT /api/item-categories/{id}` is a full replace — `name` and `state` are required on
every call. Use `PUT /api/item-categories` (bulk) to
update multiple categories in a single all-or-nothing transaction.
For a partial update, `PATCH /api/item-categories/{id}` accepts an RFC 6902 JSON Patch document
(`Content-Type: application/json-patch+json`) and touches only the paths you send (`/name`,
`/state`). To delete several categories at once, `DELETE /api/item-categories?ids=1&ids=2`
(repeated `ids`) soft-deletes them in one call; each deleted category comes back with
`state: "inactive"`.
**Breaking change.** The request `state` on `PUT /api/item-categories` and
`PUT /api/item-categories/{id}` is now a required, non-nullable enum
(`active` / `inactive` / `deleted`); it no longer accepts `null`. On the full-replace `PUT`,
omitting `state` defaults it to `active`. Integrations that previously sent `null` must send an
explicit state.
## Roles & permissions
Managing item categories requires the **`items`** permission on a **designer (brand)**
account — typically `CompanyAdmin` or `CompanyUser`. Supplier accounts work with items on
styles but do not manage a brand's item category library.
## 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 cases:
* **400 `validation_error.required_field`** — `name` was omitted or blank.
* **400 `validation_error.too_long`** — `name` exceeds 200 characters.
* **404 `resource_error.item_category_not_found`** — the `{id}` does not belong to your
organisation.
* **409** — attempting to set `state` to `deleted` via a create or update body (use
`DELETE` instead).
## What to call next
Organise styles by product type — a parallel taxonomy to item categories.
Set up size ranges before creating items that carry size-level data.
Build the colour library that item colourways reference.
Create items that reference category IDs: `POST /api/items`.