لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/entities/order-statuses.md فهرس التوثيق — /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
Parameterid Typestring Requiredyes DescriptionStatus character code (1-2 characters). For example: N, IP, DT. Must be unique regardless of type
Parametertype Typestring Requiredyes DescriptionStatus type: O — order status, D — delivery status
Parametersort Typenumber Requiredno DescriptionSort order in lists. If not passed, stored as null
Parameternotify Typeboolean Requiredno DescriptionWhether to notify the customer when an order or delivery moves to this status. If not passed, stored as false
Parametercolor Typestring Requiredno DescriptionHEX 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
ParameterxmlId Typestring Requiredno DescriptionExternal 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe created status with all fields
Fielddata.id Typestring DescriptionCharacter code passed in the request
Fielddata.type Typestring DescriptionStatus type: O — order, D — delivery
Fielddata.sort Typenumber | null DescriptionSort order. null if not passed
Fielddata.notify Typeboolean DescriptionCustomer notification. false if not passed
Fielddata.color Typestring | null DescriptionHEX color code. null if not passed
Fielddata.xmlId Typestring | null DescriptionExternal 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
HTTP422 error.codeBITRIX_ERROR Marker in error.messageRequired fields: id, type DescriptionRequired fields id or type not passed
HTTP400 error.codeBITRIX_ERROR Marker in error.messageDuplicate entry DescriptionA status with this id already exists — id must be unique regardless of type
HTTP400 error.codeBITRIX_ERROR Marker in error.message— DescriptionThe length of id exceeds 2 characters
HTTP400 error.codeBITRIX_ERROR Marker in error.message— DescriptionAn empty id value was passed
HTTP400 error.codeINVALID_PARAMS Marker in error.messageaccepts at most 10 characters DescriptionThe color value is longer than 10 characters
HTTP403 error.codeSCOPE_DENIED Marker in error.message— DescriptionThe API key does not have the sale scope
HTTP401 error.codeTOKEN_MISSING Marker in error.message— DescriptionThe 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