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 colour 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 default quantity, and file it under one or more categories (e.g. Fabric, Zipper, Button).

Add sizes and colour cards

Sizes and colour 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-colour 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, or GET /api/items/{itemId} to read one item with its brand, supplier, categories, custom fields, unit and logo.

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": "Harbour & Pine",
      "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": "Harbour & Pine",
      "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": "Harbour & Pine"
      },
      "organization": {
        "id": 165,
        "name": "Harbour & Pine ApS"
      },
      "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. Supply the supplier id; its name and customId are echoed back unchanged.
`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. Creating and deleting items is designer-only: supplier users receive 403. On an update, a supplier user may change only description (and custom fields marked supplier-editable); touching any other field returns 403. DELETE /api/items/{itemId} returns 409 Conflict if the item is still used in a 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, a brand, supplier, contact-person or category id is not found, or readyForExport: true was sent while one or more mandatory custom fields are empty (business_rule_error).
403: the itemId belongs to another organisation, or your account is not allowed to make the change.
404: the itemId does not exist.
409: the item’s identifiers clash with an existing item, or you are deleting an item that is still used in a style.
422: a PATCH operation cannot be applied to the item.

What to call next

Item categories

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

Colours

Build the colour library that item colour 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

Colours

Size ranges

Style items

​The workflow

​Walkthrough

​Field reference

​Roles & permissions

​When things go wrong

​What to call next

Item categories

Colours

Size ranges

Style items

The workflow

Walkthrough

Field reference

Roles & permissions

When things go wrong

What to call next