Manage items

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.

Create the item

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.

Add sizes and color cards

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.

Check quality details and prices

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.

Update or search

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.

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.

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"
        }
      }
    ]
  }
]'

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();

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

Item categories

Set up the category taxonomy (Fabric, Zipper, Button…) before creating items.

Colors

Build the colour library that item color cards reference.

Size ranges

Manage the size sets available to items and styles.

Style items

Add items from the library to a style’s item list.

Getting Started

Concepts

Guides

The workflow

Walkthrough

Field reference

Roles & permissions

When things go wrong

What to call next

Item categories

Colors

Size ranges

Style items

​The workflow

​Walkthrough

​Field reference

​Roles & permissions

​When things go wrong

​What to call next

Item categories

Colors

Size ranges

Style items

The workflow

Walkthrough

Field reference

Roles & permissions

When things go wrong

What to call next