> ## 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 style categories

> Create and maintain the style categories that organise a brand's styles by product type — the optional but recommended classification layer applied across the style library.

<Info>
  **When to use this.** Style categories are reusable library entities for a brand: you define
  them once in Admin and then assign one or more categories to each style. They are optional,
  but Delogue recommends mirroring your webshop category structure so downstream systems and
  integrations receive consistent classification data. A style can carry multiple categories;
  use these endpoints to build and maintain that library.
</Info>

## The workflow

Style categories sit alongside seasons and groups as the key classification dimensions for a
brand's style library. The usual path is to create the categories that reflect your product
types, assign them to styles, and deactivate or delete them when they are no longer needed.

<Steps>
  <Step title="Create categories">
    `POST /api/style-categories` with the category name and optional user-defined ID. One or
    many categories are created in a single all-or-nothing transaction.
  </Step>

  <Step title="Find categories">
    `GET /api/style-categories` with filters (name, user-defined ID, state) to look categories
    up or verify that they exist before assigning them to styles.
  </Step>

  <Step title="Assign to styles">
    Styles reference categories on creation and update — see your styles endpoints. A style
    can carry multiple categories, separated by the caller.
  </Step>

  <Step title="Retire a category">
    `PUT /api/style-categories/{id}` to set `state` to `inactive` so the category is no
    longer offered for new styles (existing styles are unaffected), or
    `DELETE /api/style-categories/{id}` to soft-delete it.
  </Step>
</Steps>

```mermaid theme={"dark"}
sequenceDiagram
  participant D as Designer
  participant API as Delogue API
  D->>API: POST /api/style-categories
  API-->>D: style category id
  D->>API: GET /api/style-categories  (verify / search)
  API-->>D: matching categories
  D->>API: POST /api/styles  (referencing category id)
  API-->>D: style id
```

## Walkthrough

Create a style category. The body is an array — one or many categories are created in a
single all-or-nothing transaction.

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl -X POST "https://service.my.delogue.com/api/style-categories" \
    -H "Accept: application/json" \
    -H "X-Auth-Token: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '[
    {
      "name": "Knitwear",
      "userDefinedId": "KNT",
      "state": "active"
    }
  ]'
  ```

  ```js JavaScript theme={"dark"}
  const res = await fetch("https://service.my.delogue.com/api/style-categories", {
    method: "POST",
    headers: {
      "Accept": "application/json",
      "X-Auth-Token": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify([
    {
      "name": "Knitwear",
      "userDefinedId": "KNT",
      "state": "active"
    }
  ]),
  });
  const { data } = await res.json();
  ```
</CodeGroup>

```json theme={"dark"}
{
  "status": "success",
  "code": "style_categories_created",
  "data": [
    {
      "id": 6,
      "name": "Knitwear",
      "state": "active",
      "usedInStyles": 0,
      "beginDate": "2026-01-01T00:00:00Z",
      "endDate": "2026-12-31T00:00:00Z",
      "userDefinedId": "KNT",
      "properties": []
    }
  ]
}
```

The response wraps the created categories in the standard envelope. Hold onto each `id` —
styles reference categories by it.

## Field reference

The fields that matter most when creating or updating a style category:

| Field           | What it means at Delogue                      |
| --------------- | --------------------------------------------- |
| `name`          | Display name of the style category. Required. |
| `state`         | Initial lifecycle state. Defaults to active.  |
| `userDefinedId` | Customer-defined identifier.                  |

<Note>
  `PUT` is a full replace and requires `name` and `state` on every item — include the current
  value of any field you don't intend to change.
</Note>

<Note>
  For a partial update, `PATCH /api/style-categories/{id}` accepts an RFC 6902 JSON Patch document
  (`Content-Type: application/json-patch+json`) and touches only the paths you send (`/name`,
  `/userDefinedId`, `/state`). To remove several categories at once,
  `DELETE /api/style-categories?ids=1&ids=2` (repeated `ids`) soft-deletes them in one call; each
  deleted category comes back with `state: "inactive"`.
</Note>

## Roles & permissions

Managing style categories requires the **`company`** permission on a **designer (brand)**
account — typically `CompanyAdmin`. Regular designer users (`CompanyUser`) can read categories
but cannot create or modify them. Supplier accounts cannot manage a brand's style categories.

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

## What to call next

<CardGroup cols={2}>
  <Card title="Seasons" href="/guides/seasons">
    Another top-level classification for styles: create seasons before assigning categories.
  </Card>

  <Card title="Colors" href="/guides/colors">
    Build the brand's colour library that styles and items reference as colourways.
  </Card>

  <Card title="Styles" href="/api-reference/styles/creates-multiple-styles">
    Create and update styles that reference categories: `POST /api/styles`.
  </Card>

  <Card title="Authentication" href="/authentication">
    How to get and send your `X-Auth-Token` API key.
  </Card>
</CardGroup>