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

The table describes the response envelope and the fields in the data.fields schema. For order fields, the types shown are the types of their values. Each schema field is an object with the keys type, readonly, label, and description. Some fields also include the flags required, nullable, and readonlyOnUpdate, as well as the nested schemas properties and itemSchema.

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionOrder schema and available operations
Fielddata.fields Typeobject DescriptionDictionary of order fields: the key is the field name, and the value is an object describing it. The dictionary fields are listed below
Fielddata.aggregatable Typearray DescriptionFields allowed in groupBy when aggregating orders
Fielddata.batch Typearray DescriptionWrite operations available in batch calls: create, update, delete
Fieldid Typenumber DescriptionOrder identifier (read-only)
FieldaccountNumber Typestring DescriptionThe order's sequential number in the Bitrix24 account. Read-only — assigned automatically. A write is rejected with 400 READONLY_FIELD
Fieldlid Typestring DescriptionSource site identifier (always "s1" on cloud Bitrix24 accounts)
FieldpersonTypeId Typenumber DescriptionPayer type identifier
Fieldcurrency Typestring DescriptionOrder currency. List: GET /v1/currencies
Fieldprice Typenumber DescriptionTotal 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
FielddiscountValue Typenumber DescriptionDiscount value
FieldtaxValue Typenumber DescriptionTax amount
FieldstatusId Typestring DescriptionCurrent order status. Source: GET /v1/order-statuses?filter[type]=O
FielduserId Typenumber DescriptionBitrix24 user identifier — the buyer in the online store. Source: GET /v1/users
FieldresponsibleId Typenumber DescriptionResponsible employee. Source: GET /v1/users
Fieldpayed Typeboolean DescriptionWhether the order is fully paid. Read-only — managed by the payments subsystem. A write is rejected with 400 READONLY_FIELD
Fieldcanceled Typeboolean DescriptionWhether the order is canceled
Fieldmarked Typeboolean DescriptionWhether 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
Fielddeducted Typeboolean DescriptionWhether the goods have been deducted from stock
FieldreasonCanceled Typestring | null DescriptionCancellation reason. null if the order is not canceled
FieldreasonMarked Typestring | null DescriptionReason 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
FieldadditionalInfo Typestring | null DescriptionAdditional information. null if not set
Fieldcomments Typestring | null DescriptionManager's comment on the order. null if not set
FielduserDescription Typestring | null DescriptionBuyer's comment on the order. null if not set
FieldorderTopic Typestring | null DescriptionOrder subject. null if not set
FieldxmlId Typestring DescriptionExternal identifier for synchronization
Fieldid1c Typestring | null DescriptionIdentifier in the ERP system. null if the order is not synchronized with an ERP system
Fieldversion1c Typestring | null DescriptionVersion in the ERP system. null if the order is not synchronized with an ERP system
Fieldupdated1c Typeboolean DescriptionWhether the order was updated through the ERP system
FieldexternalOrder Typeboolean DescriptionWhether the order was created in an external system
FieldrecountFlag Typeboolean DescriptionAutomatic recalculation flag
FieldaffiliateId Typenumber | null DescriptionAffiliate partner identifier. null if not set
FieldlockedBy Typenumber | null DescriptionIdentifier of the user who locked the order (relevant for on-premise portals). null if the order is not locked
FielddateLock Typedatetime | null DescriptionLock time. null if the order is not locked
FieldrecurringId Typenumber | null DescriptionSubscription identifier (if the order was created from a recurring template). null if the order is not from a subscription
FielddateInsert Typedatetime DescriptionCreation date (read-only)
FielddateUpdate Typedatetime DescriptionLast modification date (read-only)
FielddateCanceled Typedatetime | null DescriptionCancellation date (read-only). null if the order is not canceled
FielddateStatus Typedatetime DescriptionDate the current status was set (read-only)
FieldempCanceledId Typenumber | null DescriptionEmployee who canceled the order (read-only). null if the order is not canceled
FieldempMarkedId Typenumber | null DescriptionEmployee who set the mark (read-only). null if there is no mark
FieldempStatusId Typenumber | null DescriptionEmployee 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 still contains the raw Bitrix24 lookup values for enumeration fields.

Field Type Description
FieldcompanyId Typenumber | null DescriptionIdentifier of the linked CRM company. null if no company is set. Writable and filterable. List: GET /v1/companies
FielddateMarked Typedatetime | null DescriptionDate of the order's last mark (read-only)
FieldpersonTypeXmlId Typestring | null DescriptionExternal identifier of the payer type (read-only)
FieldstatusXmlId Typestring | null DescriptionExternal identifier of the status (read-only)
Fieldversion Typenumber DescriptionInternal record version number (read-only)
Fieldclients Typearray DescriptionThe 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)
Fieldpayments Typearray | null DescriptionThe order's payments, read-only. Payment fields — Payments. null if there are no payments
FieldbasketItems Typearray DescriptionBasket items, read-only. Item fields — Basket items
FieldpropertyValues Typearray DescriptionOrder property values — full name, e-mail, phone, delivery address, read-only. The set depends on the Bitrix24 account configuration
FieldrequisiteLink Typeobject DescriptionRecipient 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:

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 common API errors, see Errors.

See also