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"` on cloud Bitrix24 accounts)
`personTypeId`	number	Payer type identifier
`currency`	string	Order currency. List: `GET /v1/currencies`
`price`	number	Total order amount. Accepted only on creation: on update a write is rejected with `400 READONLY_FIELD`, because Bitrix24 recalculates the amount from the basket items. Flagged `readonlyOnUpdate` in the `/fields` response
`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. A write is rejected with `400 READONLY_FIELD`
`canceled`	boolean	Whether the order is canceled
`marked`	boolean	Whether the order is marked as problematic. Accepted only on creation: on update a write is rejected with `400 READONLY_FIELD`. Flagged `readonlyOnUpdate` in the `/fields` response
`deducted`	boolean	Whether the goods have been deducted 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. Accepted only on creation: on update a write is rejected with `400 READONLY_FIELD`. Flagged `readonlyOnUpdate` in the `/fields` response
`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 system. `null` if the order is not synchronized with an ERP system
`version1c`	string \| null	Version in the ERP system. `null` if the order is not synchronized with an ERP system
`updated1c`	boolean	Whether the order was updated through the ERP system
`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 are returned as true/false, and dates are in the UTC …Z format.

For arrays with a known element shape, the /fields response contains itemSchema. The schema recursively uses type, readonly, nullable, properties, and itemSchema, so it also describes basketItems[].properties[]. The separate items key is not an element schema: it continues to contain the raw Bitrix24 value directory for enumeration fields.

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), read-only. `[]` when unset

Response example

Besides type and readonly, every field carries a label (short name) and a description (explanation), both in English. Request headers do not switch the language. They are omitted from the example below for brevity. Nested itemSchema.properties maps are also shortened to a few representative fields; the live response contains the full entity-schema set.

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 },
      "basketItems": {
        "type": "array",
        "readonly": true,
        "itemSchema": {
          "type": "object",
          "properties": {
            "id": { "type": "number" },
            "name": { "type": "string" },
            "properties": {
              "type": "array",
              "itemSchema": {
                "type": "object",
                "properties": {
                  "code": { "type": "string", "nullable": true },
                  "value": { "type": "string" }
                }
              }
            }
          }
        }
      }
    },
    "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: