## Order property fields `GET /v1/order-properties/fields` Describes order property fields for creation, updates, selection, and filtering, along with the fields available for grouping. ## Parameters | Parameter | Type | Default | Description | |----------|-----|-----------|---------| | `refresh` (query) | string | `false` | Pass `true` to bypass the metadata cache. Example: `?refresh=true` | ## Examples ### curl — personal key ```bash curl "https://vibecode.bitrix24.com/v1/order-properties/fields" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth application ```bash curl "https://vibecode.bitrix24.com/v1/order-properties/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-properties/fields', { headers: { 'X-Api-Key': 'YOUR_API_KEY', }, }) const { data } = await res.json() console.log('Order property fields:', Object.keys(data.fields)) ``` ### JavaScript — OAuth application ```javascript const res = await fetch('https://vibecode.bitrix24.com/v1/order-properties/fields', { headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', }, }) const { data } = await res.json() ``` ## Response fields | Field | Type | Description | |------|-----|---------| | `success` | boolean | Always `true` on success | | `data.fields` | object | Field definitions. Each key is a field name, and its value describes the field | | `data.fields..type` | string | Value type: `number`, `string`, `any`, `object`, or `boolean` | | `data.fields..readonly` | boolean | `true` for read-only fields | | `data.fields..createOnly` | boolean | Present as `true` for `personTypeId`, `type`, and `propsGroupId`. These fields are set at creation and cannot be updated | | `data.fields..required` | boolean | Present as `true` for `personTypeId`, `type`, `name`, and `propsGroupId`, which are required at creation | | `data.fields..nullable` | boolean | Present as `true` for `code`, `description`, and `xmlId`, which accept `null` | | `data.fields..label` | string | Field label | | `data.fields..description` | string | Field description | | `data.fields.type.enum` | array | Allowed property types. Each item contains `value` and `label` | | `data.aggregatable` | array | Fields for `groupBy` in [order property aggregation](./aggregate.md): `personTypeId`, `type`, `required`, `active` | | `data.batch` | array | Batch write operations: `create`, `update`, `delete` | ### Order property fields The complete set of fields from the schema. RO marks fields that are read-only. | Field | Type | RO | Description | |------|-----|:--:|---------| | `id` | number | yes | Property ID. List: [`GET /v1/order-properties`](./list.md) | | `personTypeId` | number | no | Payer type ID. List: [`GET /v1/person-types`](/docs/entities/person-types/list). Required at creation and cannot be updated | | `type` | string | no | Property type: `STRING`, `Y/N`, `NUMBER`, `ENUM`, `FILE`, `DATE`, `LOCATION`, `ADDRESS`. Required at creation and cannot be updated | | `name` | string | no | Field name. Required at creation | | `propsGroupId` | number | no | Property group ID. Get it from a property with the same payer type through [`GET /v1/order-properties`](./list.md). Required at creation and cannot be updated | | `code` | string \| null | no | Symbolic code. `null` when unset | | `sort` | number | no | Sort order | | `defaultValue` | any | no | Default value. Its format depends on the property type. See [create](./create.md) and [update](./update.md) for file values | | `description` | string \| null | no | Field description. `null` when unset | | `settings` | object | no | Settings for the property type. See [update](./update.md) for the format and how to save settings | | `xmlId` | string \| null | no | External ID. `null` when unset | | `inputFieldLocation` | number | no | Deprecated field. Bitrix24 does not use it | | `active` | boolean | no | Whether the property is active | | `required` | boolean | no | Whether the field is required when placing an order | | `multiple` | boolean | no | Whether the field accepts multiple values | | `userProps` | boolean | no | Save the value in the buyer profile | | `util` | boolean | no | Internal property | | `isAddress` | boolean | no | Address field | | `isAddressFrom` | boolean | no | Origin address field | | `isAddressTo` | boolean | no | Destination address field | | `isEmail` | boolean | no | Email field | | `isFiltered` | boolean | no | Use the property in filters | | `isLocation` | boolean | no | Location field | | `isLocation4tax` | boolean | no | Location for tax calculation | | `isPayer` | boolean | no | Payer name field | | `isPhone` | boolean | no | Phone field | | `isProfileName` | boolean | no | Buyer profile name field | | `isZip` | boolean | no | Postal code field | ## Response example ```json { "success": true, "data": { "fields": { "id": { "type": "number", "readonly": true, "label": "ID", "description": "ID." }, "personTypeId": { "type": "number", "readonly": false, "createOnly": true, "required": true, "label": "Payer type ID", "description": "Payer type ID." }, "type": { "type": "string", "readonly": false, "createOnly": true, "required": true, "label": "Property type", "description": "Property type.", "enum": [ { "value": "STRING", "label": "STRING" }, { "value": "Y/N", "label": "Y/N" }, { "value": "NUMBER", "label": "NUMBER" }, { "value": "ENUM", "label": "ENUM" }, { "value": "FILE", "label": "FILE" }, { "value": "DATE", "label": "DATE" }, { "value": "LOCATION", "label": "LOCATION" }, { "value": "ADDRESS", "label": "ADDRESS" } ] }, "name": { "type": "string", "readonly": false, "required": true, "label": "Name", "description": "Name." }, "propsGroupId": { "type": "number", "readonly": false, "createOnly": true, "required": true, "label": "Property group ID", "description": "Property group ID." }, "code": { "type": "string", "readonly": false, "nullable": true, "label": "Code", "description": "Code." }, "sort": { "type": "number", "readonly": false, "label": "Sort order", "description": "Sort order." }, "defaultValue": { "type": "any", "readonly": false, "label": "Default value (type dependent)", "description": "Scalar or structured default, depending on type. FILE uploads use {fileData:[filename,base64]}; a stored FILE default requires an explicit replacement on update." }, "description": { "type": "string", "readonly": false, "nullable": true, "label": "Description", "description": "Description." }, "settings": { "type": "object", "readonly": false, "label": "Type-specific settings", "description": "Type-specific settings." }, "xmlId": { "type": "string", "readonly": false, "nullable": true, "label": "External ID", "description": "External ID." }, "inputFieldLocation": { "type": "number", "readonly": false, "label": "Input field location", "description": "Input field location." }, "active": { "type": "boolean", "readonly": false, "label": "Active", "description": "Active." }, "required": { "type": "boolean", "readonly": false, "label": "Required", "description": "Required." }, "multiple": { "type": "boolean", "readonly": false, "label": "Multiple", "description": "Multiple." }, "userProps": { "type": "boolean", "readonly": false, "label": "Save in profile", "description": "Save in profile." }, "util": { "type": "boolean", "readonly": false, "label": "Service property", "description": "Service property." }, "isAddress": { "type": "boolean", "readonly": false, "label": "Address", "description": "Address." }, "isAddressFrom": { "type": "boolean", "readonly": false, "label": "Origin address", "description": "Origin address." }, "isAddressTo": { "type": "boolean", "readonly": false, "label": "Destination address", "description": "Destination address." }, "isEmail": { "type": "boolean", "readonly": false, "label": "Email", "description": "Email." }, "isFiltered": { "type": "boolean", "readonly": false, "label": "Filterable", "description": "Filterable." }, "isLocation": { "type": "boolean", "readonly": false, "label": "Location", "description": "Location." }, "isLocation4tax": { "type": "boolean", "readonly": false, "label": "Tax location", "description": "Tax location." }, "isPayer": { "type": "boolean", "readonly": false, "label": "Payer name", "description": "Payer name." }, "isPhone": { "type": "boolean", "readonly": false, "label": "Phone", "description": "Phone." }, "isProfileName": { "type": "boolean", "readonly": false, "label": "Profile name", "description": "Profile name." }, "isZip": { "type": "boolean", "readonly": false, "label": "Postal code", "description": "Postal code." } }, "aggregatable": [ "personTypeId", "type", "required", "active" ], "batch": [ "create", "update", "delete" ] } } ``` ## Error response example 401 — the API key is missing: ```json { "success": false, "error": { "code": "MISSING_API_KEY", "message": "API key required. Pass via X-Api-Key header." } } ``` ## Errors | HTTP | Code | Description | |------|-----|---------| | 403 | `SCOPE_DENIED` | The API key lacks the `sale` scope | | 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing | | 401 | `TOKEN_MISSING` | No tokens are configured for the API key | | 429 | `RATE_LIMITED` | The request rate limit was exceeded. The effective limit is in the `x-ratelimit-limit` header. Retry after the interval in the `Retry-After` header | For the full list of common API errors, see [Error codes](/docs/errors). ## See also - [List order properties](./list.md) - [Get an order property](./get.md) - [Create an order property](./create.md) - [Update an order property](./update.md) - [Aggregate order properties](./aggregate.md) - [Order properties](/docs/entities/order-properties) - [Batch](/docs/batch) - [Entity API](/docs/entity-api)