## Create order status

`POST /v1/order-statuses`

Creates a new status for an order or delivery. The character code `id` is set by the user — it is used as a reference in [`orders.statusId`](../orders/fields.md).

## Request fields (body)

| Parameter | Type | Req. | Description |
|----------|-----|:-----:|---------|
| `id` | string | yes | Status character code (1-2 characters). For example: `N`, `IP`, `DT`. Must be unique regardless of type |
| `type` | string | yes | Status type: `O` — order status, `D` — delivery status |
| `sort` | number | no | Sort order in lists. If not passed, stored as `null` |
| `notify` | boolean | no | Whether to send a notification to the customer when moving into this status. If not passed, stored as `false` |
| `color` | string | no | HEX color code for display, for example `#FFA500`. If not passed, stored as `null` |
| `xmlId` | string | no | External identifier. If not passed, generated automatically in the form `bx_<hash>` |

## Examples

### curl — personal key

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/order-statuses" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "ZZ",
    "type": "O"
  }'
```

### curl — OAuth application

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/order-statuses" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "ZZ",
    "type": "O"
  }'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/order-statuses', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    id: 'ZZ',
    type: 'O',
  }),
})

const { success, data } = await res.json()
console.log('Status created:', data.id)
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/order-statuses', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    id: 'ZZ',
    type: 'O',
  }),
})

const { success, data } = await res.json()
```

## Response fields

Returns the full object of the created status. Passed fields are stored as is, omitted optional fields stay `null` or `false`.

| Field | Type | Description |
|------|-----|---------|
| `id` | string | Character code passed in the request |
| `type` | string | Status type |
| `sort` | number \| null | Sort order. `null` if not passed |
| `notify` | boolean | Customer notification. `false` if not passed |
| `color` | string \| null | HEX color code. `null` if not passed |
| `xmlId` | string \| null | External identifier. Generated automatically if not passed |

## Response example

Minimal creation — only `id` and `type` passed:

```json
{
  "success": true,
  "data": {
    "id": "ZZ",
    "type": "O",
    "sort": null,
    "color": null,
    "notify": false,
    "xmlId": "bx_6a3e47867ed3b"
  }
}
```

The optional fields `sort`, `color` and `notify` without a value stay `null` and `false` — no default values are substituted. The `xmlId` field is generated automatically. Pass these fields in the request body to set them.

## Error response example

422 — required fields not passed:

```json
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Required fields: id, type"
  }
}
```

## Errors

| HTTP | `error.code` | Marker in `error.message` | Description |
|------|--------------|--------------------------|---------|
| 422 | `BITRIX_ERROR` | `Required fields: id, type` | Required fields `id` or `type` not passed |
| 400 | `BITRIX_ERROR` | `Duplicate entry` | A status with this `id` already exists — `id` must be unique regardless of type |
| 400 | `BITRIX_ERROR` | — | The length of `id` exceeds 2 characters |
| 400 | `BITRIX_ERROR` | — | An empty `id` value was passed |
| 403 | `SCOPE_DENIED` | — | The API key does not have the `sale` scope |
| 401 | `TOKEN_MISSING` | — | The API key has no configured tokens |

Full list of general API errors — [Errors](/docs/errors).

## Known specifics

**`id` uniqueness is global.** You cannot create an order status and a delivery status with the same `id` — the code is unique regardless of type. Before creating, verify that the code is not taken via [`GET /v1/order-statuses`](./list.md).

## See also

- [List statuses](./list.md)
- [Get status](./get.md)
- [Update status](./update.md)
- [Status fields](./fields.md)
- [Update order](../orders/update.md)
- [Batch](/docs/batch)
- [Limits and optimization](/docs/optimization)