> ## 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 items
> Build and maintain the reusable item library — the fabrics, trims, packaging, and other components that styles reference on their item list.
**When to use this.** Items are the reusable components of your styles: fabrics, zippers,
buttons, labels, packaging, and more. You create them once in the item library (with a brand,
supplier, sizes, quality details, and color cards), then reference them across as many styles
as needed. Use these endpoints to build and maintain that library.
## The workflow
An item lives independently of any particular style, which lets you start sourcing before a
design is finalised. The typical path is to create the item, enrich its specifications, and
then add it to style item lists.
`POST /api/items` with at minimum a name and a brand. Assign a supplier and contact persons,
set the admin unit and default quantity, and file it under one or more categories (e.g.
Fabric, Zipper, Button). The supplier cannot be changed after saving — copy the item if you
need a different supplier.
Sizes and color cards are managed via the Delogue Classic / 2.0 UI today. Read them back with
`GET /api/items/{itemId}/sizes` and `GET /api/items/{itemId}/colors` to verify or cross-reference.
`GET /api/items/{itemId}/parts` returns the material composition (percentage + material) and
per-color specifications. `GET /api/items/{itemId}/prices` returns the agreed cost price with
currency and lead time — useful for feeding cost calculations.
`PUT /api/items/{itemId}` for a full replace, `PATCH /api/items/{itemId}` for targeted field
changes (RFC 6902 JSON Patch). `GET /api/items` with filters (name, category, supplier,
brand, custom fields, active flag) to page through the library.
```mermaid theme={"dark"}
sequenceDiagram
participant D as Designer
participant API as Delogue API
D->>API: POST /api/items (name, brand, supplier, categories)
API-->>D: item id + full ItemDto
D->>API: GET /api/items/{itemId}/sizes
API-->>D: size list
D->>API: GET /api/items/{itemId}/colors
API-->>D: color card list
D->>API: GET /api/items/{itemId}/prices
API-->>D: price header + per color/size details
D->>API: PUT /api/items/{itemId} (update description, readyForExport, etc.)
API-->>D: updated ItemDto
```
## Walkthrough
Create an item and file it under a category. The body is an array — one or many items are
created in a single all-or-nothing transaction.
```bash cURL theme={"dark"}
curl -X POST "https://service.my.delogue.com/api/items" \
-H "Accept: application/json" \
-H "X-Auth-Token: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '[
{
"id": null,
"name": "CREST WOVEN LABEL CAP",
"customId": "WL-CAP-001",
"description": "WOVEN LABEL",
"brand": {
"id": 2916,
"customId": null,
"name": "kastform",
"contactPersonId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"contactPersonName": null
},
"supplier": {
"id": 1024,
"customId": null,
"name": null,
"contactPersonId": "b2c3d4e5-f6a7-8901-bcde-f01234567891",
"contactPersonName": null
},
"companyContactPerson": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Jamie Rivera"
},
"supplierContactPerson": {
"id": "b2c3d4e5-f6a7-8901-bcde-f01234567891",
"name": "Alex Kim"
},
"defaultQty": 1.0,
"nameGeneratorExtraText": null,
"readyForExport": false,
"categories": [
{
"id": 3885,
"customId": null,
"name": null
}
],
"customFields": [
{
"id": 12,
"value": {
"value": "TR-2024-88"
}
}
]
}
]'
```
```js JavaScript theme={"dark"}
const res = await fetch("https://service.my.delogue.com/api/items", {
method: "POST",
headers: {
"Accept": "application/json",
"X-Auth-Token": "Bearer YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify([
{
"id": null,
"name": "CREST WOVEN LABEL CAP",
"customId": "WL-CAP-001",
"description": "WOVEN LABEL",
"brand": {
"id": 2916,
"customId": null,
"name": "kastform",
"contactPersonId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"contactPersonName": null
},
"supplier": {
"id": 1024,
"customId": null,
"name": null,
"contactPersonId": "b2c3d4e5-f6a7-8901-bcde-f01234567891",
"contactPersonName": null
},
"companyContactPerson": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Jamie Rivera"
},
"supplierContactPerson": {
"id": "b2c3d4e5-f6a7-8901-bcde-f01234567891",
"name": "Alex Kim"
},
"defaultQty": 1.0,
"nameGeneratorExtraText": null,
"readyForExport": false,
"categories": [
{
"id": 3885,
"customId": null,
"name": null
}
],
"customFields": [
{
"id": 12,
"value": {
"value": "TR-2024-88"
}
}
]
}
]),
});
const { data } = await res.json();
```
```json theme={"dark"}
{
"status": "success",
"code": "items_created",
"data": [
{
"id": 310974,
"name": "CREST WOVEN LABEL CAP",
"customId": "WL-CAP-001",
"description": "WOVEN LABEL",
"brand": {
"id": 2916,
"name": "kastform"
},
"organization": {
"id": 165,
"name": "KASTFORM A/S"
},
"supplier": {
"id": 1024,
"name": "Global Trim Co."
},
"companyContactPerson": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Jamie Rivera"
},
"supplierContactPerson": {
"id": "b2c3d4e5-f6a7-8901-bcde-f01234567891",
"name": "Alex Kim"
},
"adminUnit": {
"id": 45,
"name": "pcs",
"properties": []
},
"logo": null,
"lastUpdated": "2026-06-30T13:00:00.000Z",
"deadline": null,
"etd": null,
"erpItemId": null,
"defaultQty": 1.0,
"nameGeneratorExtraText": null,
"physicalReferenceNumber": null,
"categories": [
{
"id": 3885,
"name": "ARTWORK",
"state": "active",
"usedInItems": 0,
"beginDate": "0001-01-01T00:00:00Z",
"endDate": "0001-01-01T00:00:00Z",
"properties": []
}
],
"customFields": [
{
"id": 12,
"customId1": "CF-001",
"type": "Text",
"name": "Supplier Article No.",
"value": {
"id": 0,
"value": "TR-2024-88"
},
"values": null,
"perColorValues": null
}
],
"properties": [
"active"
]
}
]
}
```
The response wraps the created items in the standard envelope. Hold onto each `id` — style item
lists reference items by it.
## Field reference
The fields that matter most when creating or updating an item:
| Field | What it means at Delogue |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `brand` | The brand to associate with this item. The brand id is required; name and customId are echo-only. |
| `categories` | Category associations to create. Each entry must carry the category id; name and customId are ignored by the server. |
| `companyContactPerson` | The brand-side contact person. Provide the user id (GUID string). |
| `customFields` | Custom field values to set. Single-value fields use value; multi-select fields use values. |
| `customId` | Customer-defined item number. |
| `defaultQty` | Default consumption quantity when the item is added to a style item list. |
| `description` | Free-text description of the item. |
| `id` | Optional client-assigned id. Ignored by the server on create; omit or send null. |
| `name` | Display name of the item. Required. |
| `nameGeneratorExtraText` | Extra text for the item number generator if a generation rule is configured. |
| `readyForExport` | When true, the item is validated against mandatory custom fields and marked ready for export. Defaults to false. |
| `supplier` | The supplier organisation to assign. Once saved, the supplier cannot be changed — copy the item to use a different supplier. |
| `supplierContactPerson` | The supplier-side contact person. Provide the user id (GUID string). |
`PUT /api/items/{itemId}` is a full replace — send all fields you want to keep. Use
`PATCH /api/items/{itemId}` (RFC 6902 JSON Patch) for targeted changes such as updating a
single field, e.g. `[{ "op": "replace", "path": "/description", "value": "new value" }]`.
Bulk update is available via `PUT /api/items` (array body).
**Breaking change — item `customFields` request shape.** Each entry in a `customFields` array
now uses:
* `id` (**required**) — the custom-field definition id. This replaces the former
`customFieldId`. Note the repurposing: on the old update shape `id` was the existing
custom-field value **row** id (nullable, `null` to add a new value); that row identifier is
gone, and `id` now always means the **definition** id. An update that keeps sending the old
row id in `id` will silently target the wrong custom field with no error — send the definition
id.
* `value` — a single value for text, date, numeric, or single-select fields. For an
allowed-value field, set `value.id` to the allowed-value id (this replaces the former
`itemCustomFieldAllowedValueId`).
* `values` — an array of values for multi-select allowed-value fields; a given field `id` must
appear only once, so send multiple selections here rather than repeating the entry.
The removed properties `customFieldId`, `itemCustomFieldAllowedValueId`, and
`customFieldAllowedValueUserDefinedID` are no longer accepted on the request; the allowed-value
user-defined id is now resolved server-side. Existing integrations must migrate to the `id` /
`value` / `values` shape.
## Roles & permissions
Managing the item library requires the **`items`** permission on a **designer (brand)** account
— typically `CompanyAdmin` or `CompanyUser`. Supplier accounts can view items assigned to them
via style item lists but do not create or update items in the library. Deleting an item returns
**409 Conflict** if it is still referenced by a non-deleted style.
## 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 for items:
* **400** — a required field (e.g. `name`, `brand.id`) is missing or too long.
* **404** — the `itemId`, brand id, supplier id, or category id does not exist in your organisation.
* **409** — attempting to delete an item that is referenced by an active style item list.
* **422** — `readyForExport: true` was sent but one or more mandatory custom fields are empty.
## What to call next
Set up the category taxonomy (Fabric, Zipper, Button…) before creating items.
Build the colour library that item color cards reference.
Manage the size sets available to items and styles.
Add items from the library to a style's item list.