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

Order status fields

GET /v1/order-statuses/fields

Returns a static map of status fields: the type of each field, the read-only flag, a name and an explanation, the list of aggregatable fields, and the available batch operations. The schema is fixed — Bitrix24 exposes no field metadata for order statuses, so the names and explanations come from the wrapper itself.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/order-statuses/fields" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/order-statuses/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/order-statuses/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { data } = await res.json()
console.log('Status fields:', Object.keys(data.fields))

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/order-statuses/fields', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()

Response fields

Field label and description values are returned in English. Request headers do not switch the language.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.fields Typeobject DescriptionStatus field schema: field name → type, readonly, label, description. The fields are listed below
Fielddata.aggregatable Typearray DescriptionFields accepted in groupBy of order status aggregation: type, notify
Fielddata.batch Typearray DescriptionStatus operations available in POST /v1/batch: create, update, delete

Order status fields

Field Type RO Description
Fieldid Typestring ROno DescriptionStatus code. Set by the user on creation
Fieldtype Typestring ROno DescriptionStatus type: O — order, D — delivery
Fieldsort Typenumber | null ROno DescriptionSort order. Can be null in query results
Fieldnotify Typeboolean ROno DescriptionWhether to send a notification to the customer
Fieldcolor Typestring | null ROno DescriptionHEX color code. Can be null in query results
FieldxmlId Typestring | null ROno DescriptionExternal identifier. Can be null in query results

Response example

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "string", "readonly": false, "label": "Status code", "description": "Character code of the status, set by the caller on creation — Bitrix24 does not generate it." },
      "type": { "type": "string", "readonly": false, "label": "Status type", "description": "Status type: O — order status, D — delivery status. Bitrix24 requires the field on every update, so the wrapper resends the stored value when the request omits it." },
      "sort": { "type": "number", "readonly": false, "label": "Sort index", "description": "Sort index that orders statuses in the Bitrix24 interface — the lower the value, the earlier the status." },
      "notify": { "type": "boolean", "readonly": false, "label": "Notify customer", "description": "Whether Bitrix24 notifies the customer when the order enters this status. Bitrix24 stores the flag as Y or N; the wrapper returns and accepts a boolean." },
      "color": { "type": "string", "readonly": false, "label": "Color", "description": "HEX color code Bitrix24 uses to paint the status in the interface, for example #ACE9FB. Limited to 10 characters — the database column width; a longer value is refused rather than silently truncated." },
      "xmlId": { "type": "string", "readonly": false, "label": "External ID", "description": "External identifier of the status, used to synchronize it with other systems." }
    },
    "aggregatable": ["type", "notify"],
    "batch": ["create", "update", "delete"]
  }
}

Error response example

403 — no scope:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'sale' scope"
  }
}

Errors

HTTP Code Description
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the sale scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens
HTTP429 CodeRATE_LIMITED DescriptionRate limit exceeded: 300 requests per minute per portal. All API keys of the portal share one limit. The current limit is returned in the x-ratelimit-limit header. Retry after the delay in the Retry-After header

For the full list of general API errors, see Errors.

See also