## 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

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

### curl — OAuth application

```bash
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`](/docs/entities/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`](../order-statuses/list.md) |
| `userId` | number | Bitrix24 user identifier — the buyer in the online store. Source: [`GET /v1/users`](/docs/entities/users) |
| `responsibleId` | number | Responsible employee. Source: [`GET /v1/users`](/docs/entities/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`](./get.md) — they are absent from the [`GET /v1/orders`](./list.md) 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`](/docs/entities/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`](/docs/entities/contacts)), `4` — company ([`GET /v1/companies`](/docs/entities/companies)) |
| `payments` | array \| null | The order's payments, read-only. Payment fields — [Payments](../payments.md). `null` if there are no payments |
| `basketItems` | array | Basket items, read-only. Item fields — [Basket items](../basket-items.md) |
| `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](/docs/errors).

## See also

- [List orders](./list.md)
- [Create an order](./create.md)
- [Aggregate orders](./aggregate.md)
- [Entity API](/docs/entity-api)
- [Limits and optimization](/docs/optimization)