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 records owned by your organisation. 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. Read a single category with GET /api/item-categories/{id}.
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. DELETE /api/item-categories/{id} hard-deletes the category and returns 409 if items still use it.

​
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 is required on every call, and an omitted state defaults to active. 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) hard-deletes them in one all-or-nothing call: if any id is unknown or still used by items, the whole batch rolls back.
Breaking change. The request state on PUT /api/item-categories and PUT /api/item-categories/{id} no longer accepts null or deleted: both return 400. Send active or inactive, or omit state to default it to active. Integrations that previously sent null must send an explicit state or omit the field; use DELETE to delete.

​
Roles & permissions

Creating, updating and deleting item categories requires admin-level items permission on a designer (brand) account: typically CompanyAdmin. Supplier users receive 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. Common cases:
  • 400: name was omitted, blank or longer than 200 characters, or state was sent as null or deleted (use DELETE instead).
  • 403: on a read or update, the {id} belongs to another organisation.
  • 404 resource_error.item_category_not_found: the {id} does not exist (on DELETE, also when it belongs to another organisation).
  • 409: deleting a category that items still use.

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

Colours

Build the colour library that item colourways reference.

Items

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