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
Parameterrefresh (query) Typestring Defaultfalse DescriptionPass 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionOrder property metadata. The property's own fields are listed in the "Order property fields" table below
Fielddata.fields Typeobject DescriptionField definitions. Each key is a field name, and its value describes the field
Fielddata.fields.<field>.type Typestring DescriptionValue type: number, string, any, object, or boolean
Fielddata.fields.<field>.readonly Typeboolean Descriptiontrue for read-only fields
Fielddata.fields.<field>.createOnly Typeboolean DescriptionPresent as true for personTypeId, type, and propsGroupId. These fields are set at creation and cannot be updated
Fielddata.fields.<field>.required Typeboolean DescriptionPresent as true for personTypeId, type, name, and propsGroupId, which are required at creation
Fielddata.fields.<field>.nullable Typeboolean DescriptionPresent as true for code, description, and xmlId, which accept null
Fielddata.fields.<field>.label Typestring DescriptionField label
Fielddata.fields.<field>.description Typestring DescriptionField description
Fielddata.fields.type.enum Typearray DescriptionAllowed property types. Each item contains value and label
Fielddata.aggregatable Typearray DescriptionFields for groupBy in order property aggregation: personTypeId, type, required, active
Fielddata.batch Typearray DescriptionBatch 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
Fieldid Typenumber ROyes DescriptionProperty ID. List: GET /v1/order-properties
FieldpersonTypeId Typenumber ROno DescriptionPayer type ID. List: GET /v1/person-types. Required at creation and cannot be updated
Fieldtype Typestring ROno DescriptionProperty type: STRING, Y/N, NUMBER, ENUM, FILE, DATE, LOCATION, ADDRESS. Required at creation and cannot be updated
Fieldname Typestring ROno DescriptionField name. Required at creation
FieldpropsGroupId Typenumber ROno DescriptionProperty group ID. Get it from a property with the same payer type through GET /v1/order-properties. Required at creation and cannot be updated
Fieldcode Typestring | null ROno DescriptionSymbolic code. null when unset
Fieldsort Typenumber ROno DescriptionSort order
FielddefaultValue Typeany ROno DescriptionDefault value. Its format depends on the property type. See create and update for file values
Fielddescription Typestring | null ROno DescriptionField description. null when unset
Fieldsettings Typeobject ROno DescriptionSettings for the property type. See update for the format and how to save settings
FieldxmlId Typestring | null ROno DescriptionExternal ID. null when unset
FieldinputFieldLocation Typenumber ROno DescriptionDeprecated field. Bitrix24 does not use it
Fieldactive Typeboolean ROno DescriptionWhether the property is active
Fieldrequired Typeboolean ROno DescriptionWhether the field is required when placing an order
Fieldmultiple Typeboolean ROno DescriptionWhether the field accepts multiple values
FielduserProps Typeboolean ROno DescriptionSave the value in the buyer profile
Fieldutil Typeboolean ROno DescriptionInternal property
FieldisAddress Typeboolean ROno DescriptionAddress field
FieldisAddressFrom Typeboolean ROno DescriptionOrigin address field
FieldisAddressTo Typeboolean ROno DescriptionDestination address field
FieldisEmail Typeboolean ROno DescriptionEmail field
FieldisFiltered Typeboolean ROno DescriptionUse the property in filters
FieldisLocation Typeboolean ROno DescriptionLocation field
FieldisLocation4tax Typeboolean ROno DescriptionLocation for tax calculation
FieldisPayer Typeboolean ROno DescriptionPayer name field
FieldisPhone Typeboolean ROno DescriptionPhone field
FieldisProfileName Typeboolean ROno DescriptionBuyer profile name field
FieldisZip Typeboolean ROno DescriptionPostal 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
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the sale scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionNo tokens are configured for the API key
HTTP429 CodeRATE_LIMITED DescriptionThe 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