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

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

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.

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.

See also