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

Create an order property

POST /v1/order-properties

Creates an online store order field definition for entering additional information at checkout.

Pass fields at the root of the JSON body, without a fields wrapper.

Request body fields

Field Type Required Description
FieldpersonTypeId Typenumber Requiredyes DescriptionPayer type ID. List: GET /v1/person-types
Fieldtype Typestring Requiredyes DescriptionProperty type: STRING, Y/N, NUMBER, ENUM, FILE, DATE, LOCATION, ADDRESS
Fieldname Typestring Requiredyes DescriptionOrder field name
FieldpropsGroupId Typenumber Requiredyes DescriptionProperty group ID for the selected payer type. Source: GET /v1/order-properties, the propsGroupId field
Fieldcode Typestring | null Requiredno DescriptionSymbolic code
Fieldsort Typenumber Requiredno DescriptionSort order
FielddefaultValue Typeany Requiredno DescriptionDefault value. A scalar or structure depending on the type and multiple. For FILE, upload using { "fileData": ["filename", "base64"] }
Fielddescription Typestring | null Requiredno DescriptionField description
Fieldsettings Typeobject Requiredno DescriptionProperty type settings. A JSON object. Pass the property fields at the top level of the request body
FieldxmlId Typestring | null Requiredno DescriptionExternal ID
FieldinputFieldLocation Typenumber Requiredno DescriptionDeprecated field. Bitrix24 does not use it
Fieldactive Typeboolean Requiredno DescriptionThe property is active
Fieldrequired Typeboolean Requiredno DescriptionA value is required at checkout
Fieldmultiple Typeboolean Requiredno DescriptionThe property holds multiple values
FielduserProps Typeboolean Requiredno DescriptionSave the value in the buyer profile
Fieldutil Typeboolean Requiredno DescriptionInternal property
FieldisAddress Typeboolean Requiredno DescriptionThe property contains an address
FieldisAddressFrom Typeboolean Requiredno DescriptionOrigin address
FieldisAddressTo Typeboolean Requiredno DescriptionDestination address
FieldisEmail Typeboolean Requiredno DescriptionThe property contains an email address
FieldisFiltered Typeboolean Requiredno DescriptionUse the property in a filter
FieldisLocation Typeboolean Requiredno DescriptionThe property contains a location
FieldisLocation4tax Typeboolean Requiredno DescriptionLocation used to calculate taxes
FieldisPayer Typeboolean Requiredno DescriptionPayer name
FieldisPhone Typeboolean Requiredno DescriptionPhone number
FieldisProfileName Typeboolean Requiredno DescriptionBuyer profile name
FieldisZip Typeboolean Requiredno DescriptionPostal code

The server assigns id.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/order-properties" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "personTypeId": 5,
  "type": "STRING",
  "name": "Comment for the courier",
  "propsGroupId": 9,
  "code": "DELIVERY_COMMENT",
  "sort": 500,
  "active": false,
  "required": false,
  "defaultValue": "Call before delivery",
  "settings": {
    "maxlength": 200
  }
}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/order-properties" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "personTypeId": 5,
  "type": "STRING",
  "name": "Comment for the courier",
  "propsGroupId": 9,
  "code": "DELIVERY_COMMENT",
  "sort": 500,
  "active": false,
  "required": false,
  "defaultValue": "Call before delivery",
  "settings": {
    "maxlength": 200
  }
}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/order-properties', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "personTypeId": 5,
    "type": "STRING",
    "name": "Comment for the courier",
    "propsGroupId": 9,
    "code": "DELIVERY_COMMENT",
    "sort": 500,
    "active": false,
    "required": false,
    "defaultValue": "Call before delivery",
    "settings": {
      "maxlength": 200
    }
  }),
})

const { success, data } = await res.json()

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/order-properties', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "personTypeId": 5,
    "type": "STRING",
    "name": "Comment for the courier",
    "propsGroupId": 9,
    "code": "DELIVERY_COMMENT",
    "sort": 500,
    "active": false,
    "required": false,
    "defaultValue": "Call before delivery",
    "settings": {
      "maxlength": 200
    }
  }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success. HTTP status: 201
Fielddata Typeobject DescriptionCreated order property. Full field list: Order property fields

Response example

The main fields are shown. Full list: Order property fields.

JSON 
{
  "success": true,
  "data": {
    "id": 125,
    "personTypeId": 5,
    "type": "STRING",
    "name": "Comment for the courier",
    "propsGroupId": 9,
    "code": "DELIVERY_COMMENT",
    "active": false,
    "defaultValue": "Call before delivery",
    "settings": {
      "maxlength": 200,
      "multiline": "N"
    }
  }
}

Error response example

400 — settings was set to null:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Order property settings must be an object."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionpersonTypeId, type, name, or propsGroupId is missing; personTypeId, name, or propsGroupId is null; or name is an empty string
HTTP400 CodeINVALID_PARAMS Descriptiontype is not an allowed property type, is null, or is an empty string. Message: Invalid order property type.
HTTP400 CodeREADONLY_FIELD DescriptionThe request contains id, relations or variants, including inside settings
HTTP400 CodeINVALID_PARAMS DescriptionAn object or array was passed to a scalar field
HTTP400 CodeINVALID_PARAMS DescriptionA nonnumeric string, an empty string, or a boolean was passed to a numeric field
HTTP400 CodeINVALID_PARAMS DescriptionA flag is neither boolean true/false nor one of the strings "Y"/"N", "yes"/"no", "1"/"0", "true"/"false" (case-insensitive, ignoring surrounding whitespace)
HTTP400 CodeINVALID_PARAMS Descriptionsettings is not a JSON object
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the operation. The reason is in message
HTTP422 CodeBITRIX_ERROR DescriptionThe key's user does not have permission in Bitrix24. The Bitrix24 code is in error.b24Code: 200040300020
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe portal credentials do not have the sale scope (insufficient_scope)
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the sale scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

For the full list of shared API errors, see Error codes.

See also