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
`personTypeId`	number	yes	Payer type ID. List: `GET /v1/person-types`
`type`	string	yes	Property type: `STRING`, `Y/N`, `NUMBER`, `ENUM`, `FILE`, `DATE`, `LOCATION`, `ADDRESS`
`name`	string	yes	Order field name
`propsGroupId`	number	yes	Property group ID for the selected payer type. Source: `GET /v1/order-properties`, the `propsGroupId` field
`code`	string \| null	no	Symbolic code
`sort`	number	no	Sort order
`defaultValue`	any	no	Default value. A scalar or structure depending on the type and `multiple`. For `FILE`, upload using `{ "fileData": ["filename", "base64"] }`
`description`	string \| null	no	Field description
`settings`	object	no	Property type settings. A JSON object. Pass the property fields at the top level of the request body
`xmlId`	string \| null	no	External ID
`inputFieldLocation`	number	no	Deprecated field. Bitrix24 does not use it
`active`	boolean	no	The property is active
`required`	boolean	no	A value is required at checkout
`multiple`	boolean	no	The property holds multiple values
`userProps`	boolean	no	Save the value in the buyer profile
`util`	boolean	no	Internal property
`isAddress`	boolean	no	The property contains an address
`isAddressFrom`	boolean	no	Origin address
`isAddressTo`	boolean	no	Destination address
`isEmail`	boolean	no	The property contains an email address
`isFiltered`	boolean	no	Use the property in a filter
`isLocation`	boolean	no	The property contains a location
`isLocation4tax`	boolean	no	Location used to calculate taxes
`isPayer`	boolean	no	Payer name
`isPhone`	boolean	no	Phone number
`isProfileName`	boolean	no	Buyer profile name
`isZip`	boolean	no	Postal 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
`success`	boolean	`true` on success. HTTP status: `201`
`data`	object	Created 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: