For AI agents: markdown of this page — /docs-content-en/entities/order-statuses.md documentation index — /llms.txt

Order statuses

Manage the order and delivery statuses of an online store: create, get, update, delete, search, aggregate. Statuses are a reference list that the orders.statusId field points to. Each status has a type: O — order status, D — delivery status.

Bitrix24 API: sale.status.* Scope: sale

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.

Request fields (body)

Parameter Type Required 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 notify the customer when an order or delivery moves to this status. If not passed, stored as false
color string no HEX color code for display, for example #FFA500. At most 10 characters — the database column width; a longer value is refused with 400 INVALID_PARAMS rather than silently truncated. 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

Terminal 
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

Terminal 
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

Field Type Description
success boolean Always true on success
data object The created status with all fields
data.id string Character code passed in the request
data.type string Status type: O — order, D — delivery
data.sort number | null Sort order. null if not passed
data.notify boolean Customer notification. false if not passed
data.color string | null HEX color code. null if not passed
data.xmlId string | null External identifier. Generated automatically if not passed

Response example

Minimal request — only id and type are passed:

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

When omitted, the optional fields sort, color and notify stay null, 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
400 INVALID_PARAMS accepts at most 10 characters The color value is longer than 10 characters
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.

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 a status, check that the code is not taken by calling GET /v1/order-statuses.

See also