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

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

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

curl — OAuth application

Terminal 
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.<field>.type string Value type: number, string, any, object, or boolean
data.fields.<field>.readonly boolean true for read-only fields
data.fields.<field>.createOnly boolean Present as true for personTypeId, type, and propsGroupId. These fields are set at creation and cannot be updated
data.fields.<field>.required boolean Present as true for personTypeId, type, name, and propsGroupId, which are required at creation
data.fields.<field>.nullable boolean Present as true for code, description, and xmlId, which accept null
data.fields.<field>.label string Field label
data.fields.<field>.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: 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
personTypeId number no Payer type ID. List: GET /v1/person-types. 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. 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 and update for file values
description string | null no Field description. null when unset
settings object no Settings for the property type. See update 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.

See also