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

Order fields

GET /v1/orders/fields

Returns the order field schema: types, read-only flags, and the list of aggregatable fields.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/orders/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/orders/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

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

JavaScript — OAuth application

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

const { data } = await res.json()

Response fields

Field Type Description
id number Order identifier (read-only)
accountNumber string The order's sequential number in the Bitrix24 account. Read-only — assigned automatically, a write is rejected with 400 READONLY_FIELD
lid string Source site identifier (always "s1" for cloud portals)
personTypeId number Payer type identifier
currency string Order currency. List: GET /v1/currencies
price number Total order amount. Set on creation; on update it is recalculated from the basket items — a manually passed value is ignored (empty basket → 0)
discountValue number Discount value
taxValue number Tax amount
statusId string Current order status. Source: GET /v1/order-statuses?filter[type]=O
userId number Bitrix24 user identifier — the buyer in the online store. Source: GET /v1/users
responsibleId number Responsible employee. Source: GET /v1/users
payed boolean Whether the order is fully paid (read-only — managed by the payments subsystem; write → 400 READONLY_FIELD)
canceled boolean Whether the order is canceled
marked boolean Whether the order is marked as problematic. Set on creation; ignored on update
deducted boolean Whether the goods have been written off from stock
reasonCanceled string | null Cancellation reason. null if the order is not canceled
reasonMarked string | null Reason for the mark. null if there is no mark
additionalInfo string | null Additional information. null if not set
comments string | null Manager's comment on the order. null if not set
userDescription string | null Buyer's comment on the order. null if not set
orderTopic string | null Order subject. null if not set
xmlId string External identifier for synchronization
id1c string | null Identifier in the ERP. null if the order is not synchronized with the ERP
version1c string | null Version in the ERP. null if the order is not synchronized with the ERP
updated1c boolean Whether the order was updated via the ERP
externalOrder boolean Whether the order was created in an external system
recountFlag boolean Automatic recalculation flag
affiliateId number | null Affiliate partner identifier. null if not set
lockedBy number | null Identifier of the user who locked the order (relevant for on-premise portals). null if the order is not locked
dateLock datetime | null Lock time. null if the order is not locked
recurringId number | null Subscription identifier (if the order was created from a recurring template). null if the order is not from a subscription
dateInsert datetime Creation date (read-only)
dateUpdate datetime Last modification date (read-only)
dateCanceled datetime | null Cancellation date (read-only). null if the order is not canceled
dateStatus datetime Date the current status was set (read-only)
empCanceledId number | null Employee who canceled the order (read-only). null if the order is not canceled
empMarkedId number | null Employee who set the mark (read-only). null if there is no mark
empStatusId number | null Employee who last changed the status (read-only). null if the status has not changed

Additional fields and nested arrays

These fields are also part of the GET /v1/orders/fields schema. companyId is readable, writable, and filterable; the rest are read-only. The clients, payments, basketItems, propertyValues arrays are returned only by GET /v1/orders/:id — they are absent from the GET /v1/orders list response. Boolean fields inside the nested objects come as true/false, and dates are in the UTC …Z format.

Field Type Description
companyId number | null Identifier of the linked CRM company. null if no company is set. Writable and filterable. List: GET /v1/companies
dateMarked datetime | null Date of the order's last mark (read-only)
personTypeXmlId string | null External identifier of the payer type (read-only)
statusXmlId string | null External identifier of the status (read-only)
version number Internal record version number (read-only)
clients array The order's CRM bindings, read-only. Each element: {entityTypeId, entityId, isPrimary, roleId, sort}, where isPrimary is true/false. entityTypeId equals 3 — contact (GET /v1/contacts), 4 — company (GET /v1/companies)
payments array | null The order's payments, read-only. Payment fields — Payments. null if there are no payments
basketItems array Basket items, read-only. Item fields — Basket items
propertyValues array Order property values — full name, e-mail, phone, delivery address, read-only. The set depends on the Bitrix24 account configuration
requisiteLink object Recipient requisites link (requisiteId/bankDetailId/mcRequisiteId/mcBankDetailId); [] when unset; read-only

Response example

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true },
      "accountNumber": { "type": "string", "readonly": true },
      "price": { "type": "number", "readonly": false },
      "currency": { "type": "string", "readonly": false },
      "statusId": { "type": "string", "readonly": false },
      "userId": { "type": "number", "readonly": false },
      "dateInsert": { "type": "datetime", "readonly": true },
      "dateUpdate": { "type": "datetime", "readonly": true },
      "payed": { "type": "boolean", "readonly": true },
      "canceled": { "type": "boolean", "readonly": false }
    },
    "aggregatable": ["price", "statusId", "payed", "canceled", "personTypeId", "responsibleId", "userId"],
    "batch": ["create", "update", "delete"]
  }
}

The most important fields are shown. The full set is described in the table above — the same set is returned by a live GET /v1/orders/fields call.

Error response example

403 — no scope:

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

Errors

HTTP Code Description
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 common API errors — Errors.

See also