Skip to main content
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.
1

Create categories

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.
2

Browse categories

GET /api/item-categories with optional filters (Search, State, Names) to look up existing categories or build a picker list.
3

Reference on items

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.
4

Retire or rename

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).

​
Walkthrough

Create two item categories in a single request. The body is an array — all items are created atomically.
The response wraps the created categories in the standard envelope. Hold onto each id — items reference categories by it.

​
Field reference

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

Style categories

Organise styles by product type — a parallel taxonomy to item categories.

Size ranges

Set up size ranges before creating items that carry size-level data.

Colors

Build the colour library that item colourways reference.

Items

Create items that reference category IDs: POST /api/items.