## Replace the pipeline stages (tenant:crm:admin)

`PUT /api/crm/v1/stages`

Module: CRM · operationId: `replaceStages` · Tag: Pipeline · Auth: access token (`Authorization: Bearer <accessToken>`)

Saves the whole list; its order is the order of the pipeline. Every phase needs at least one
active stage and keys must be unique (`400`, `invalid_stages`); a key that opportunities use
cannot be left out, only archived (`400`, `stage_in_use`). The phase of a stage that opportunities use
cannot change (`400`, field `items.<n>.phase`); add a new stage instead. Emits `crm.stages.updated`.

### Request body

`application/json` (required)

- `items` (array of StageInput, required): In pipeline order.
  - `key` (string, required): Stable key of the stage. (max length 64)
  - `label` (string, required): Display name. (max length 100)
  - `phase` (string, required): Phase the stage belongs to. (one of `open`, `won`, `lost`)
  - `archived` (boolean): Archived stages cannot be chosen for opportunities. (default `false`)
  - `probability` (integer): Default win probability of an opportunity entering the stage. (default `0`; max 100)

Example:

```json
{
  "items": [
    {
      "key": "PROSPECTING",
      "label": "Akquise",
      "phase": "open",
      "probability": 10
    },
    {
      "key": "PROPOSAL",
      "label": "Angebot",
      "phase": "open",
      "probability": 50
    },
    {
      "key": "CLOSED_WON",
      "label": "Gewonnen",
      "phase": "won",
      "probability": 100
    },
    {
      "key": "CLOSED_LOST",
      "label": "Verloren",
      "phase": "lost",
      "probability": 0
    }
  ]
}
```

### Responses

- **200** The saved stages (`application/json`)
- **400** Invalid input (`invalid`): `field` names the first invalid field, `details.fields` every one (JSON paths for
bodies, parameter names for the query). Some refusals have their own code (`invalid_sort`,
`invalid_stages`, `invalid_custom_fields`, `convert_target_required`, `invalid_csv`, …).
 (`application/json`)
- **401** Missing, invalid or expired token (no body).
- **403** The token lacks the permission (`insufficient permissions`) or has no active tenant.
 (`application/json`)
- **500** Unexpected error; details are only logged. (`application/json`)

Fields of the 200 answer:

- `default` (boolean, required): The tenant has not saved its own stages; these are the defaults.
- `items` (array of Stage, required): Stages in pipeline order.
  - `archived` (boolean, required): Archived stages cannot be chosen for opportunities.
  - `key` (string, required): Stable key of the stage (stored on opportunities). (max length 64)
  - `label` (string, required): Display name. (max length 100)
  - `phase` (string, required): Phase the stage belongs to. (one of `open`, `won`, `lost`)
  - `position` (integer, required): Order in the pipeline.
  - `probability` (integer, required): Default win probability of an opportunity entering the stage. (max 100)
  - `used` (boolean, required, read-only): Opportunities are in the stage; it can then only be archived, not removed.

Example 200 answer:

```json
{
  "default": false,
  "items": [
    {
      "archived": false,
      "key": "PROSPECTING",
      "label": "Erstkontakt",
      "phase": "open",
      "position": 1,
      "probability": 10,
      "used": true
    },
    {
      "archived": false,
      "key": "QUALIFICATION",
      "label": "Qualifizierung",
      "phase": "open",
      "position": 2,
      "probability": 30,
      "used": true
    },
    {
      "archived": false,
      "key": "PROPOSAL",
      "label": "Angebot",
      "phase": "open",
      "position": 3,
      "probability": 50,
      "used": true
    },
    {
      "archived": false,
      "key": "NEGOTIATION",
      "label": "Verhandlung",
      "phase": "open",
      "position": 4,
      "probability": 75,
      "used": false
    },
    {
      "archived": false,
      "key": "CLOSED_WON",
      "label": "Gewonnen",
      "phase": "won",
      "position": 5,
      "probability": 100,
      "used": true
    },
    {
      "archived": false,
      "key": "CLOSED_LOST",
      "label": "Verloren",
      "phase": "lost",
      "position": 6,
      "probability": 0,
      "used": true
    }
  ]
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/crm/v1/stages' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"items":[{"key":"PROSPECTING","label":"Akquise","phase":"open","probability":10},{"key":"PROPOSAL","label":"Angebot","phase":"open","probability":50},{"key":"CLOSED_WON","label":"Gewonnen","phase":"won","probability":100},{"key":"CLOSED_LOST","label":"Verloren","phase":"lost","probability":0}]}'
```
