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

> Create and maintain the seasons that every style is filed under — the top-level structure for a brand's collections.

<Info>
  **When to use this.** A season is the top-level parameter every style is organised by, and a
  brand can have as many as it needs. A style cannot be created without one, so seasons are
  usually the first admin data you set up. Use these endpoints to create seasons, group them by
  project, and retire them once a collection closes.
</Info>

## The workflow

Seasons sit at the top of the product structure: you create a season, file styles under it, and
later deactivate or lock it when the collection is done. Many brands also use the **project**
field to sub-divide a season into drops or collaboration collections.

<Steps>
  <Step title="Create the season">
    `POST /api/seasons` with the season name (and optionally a project and custom ID). Only
    designer users can create seasons.
  </Step>

  <Step title="Create styles in it">
    `POST /api/styles` references the season — a style cannot be created without one.
  </Step>

  <Step title="Find styles by season">
    `GET /api/styles` with `season.id` (or `season.name` / `season.project`) to pull everything
    in a season later.
  </Step>

  <Step title="Retire the season">
    `PUT /api/seasons/{id}` to set `state` to `inactive` so it is no longer offered for new
    styles, or `DELETE /api/seasons/{id}` to soft-delete it.
  </Step>
</Steps>

```mermaid theme={"dark"}
sequenceDiagram
  participant D as Designer
  participant API as Delogue API
  D->>API: POST /api/seasons
  API-->>D: season id
  D->>API: POST /api/styles  (referencing the season)
  API-->>D: style id
  D->>API: GET /api/styles?season.id=...
  API-->>D: styles in the season
```

## Walkthrough

Create a season for next spring/summer. The body is an array — one or many seasons are created
in a single all-or-nothing transaction.

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

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

```json theme={"dark"}
{
  "status": "success",
  "code": "seasons_created",
  "data": [
    {
      "id": 4821,
      "name": "SS29",
      "project": "Main collection",
      "customId": "SS29",
      "state": "active",
      "properties": []
    }
  ]
}
```

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

## Field reference

The fields that matter most when creating or updating a season:

| Field      | What it means at Delogue                                                                                   |
| ---------- | ---------------------------------------------------------------------------------------------------------- |
| `customId` | Customer-defined season identifier, useful for ERP alignment. Optional, up to 100 characters.              |
| `name`     | Display name of the season, e.g. SS29. Required, up to 200 characters.                                     |
| `project`  | Project within the season for seasonal drops or collaboration collections. Optional, up to 100 characters. |
| `state`    | Initial lifecycle state. Defaults to active. deleted is not accepted.                                      |

<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>
  Prefer a partial update? `PATCH /api/seasons/{id}` accepts an RFC 6902 JSON Patch document
  (`Content-Type: application/json-patch+json`) and touches only the paths you send — `/name`,
  `/project`, `/customId`, and `/state`. `state` still cannot be set to `deleted` (use
  `DELETE /api/seasons/{id}`), and `name` cannot be cleared.
</Note>

## Roles & permissions

Managing seasons requires the **`seasons`** permission on a **designer (brand)** account —
typically `CompanyAdmin` or `CompanyUser`. Supplier accounts collaborate on styles but do not
manage a brand's seasons. Locking a season is a Professional-tier feature.

## 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="Styles" href="/api-reference/styles/creates-multiple-styles">
    Create styles in the season: `POST /api/styles`, then filter with `GET /api/styles?season.id=`.
  </Card>

  <Card title="Sample types" href="/api-reference/sampletypes/list-sample-types">
    Season milestone deadlines are driven by sample types: `GET /api/sample-types`.
  </Card>

  <Card title="Groups" href="/api-reference/groups/get-groups">
    Another way to organise styles: `GET /api/groups`.
  </Card>

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