## 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`](/docs/entities/person-types/list) |
| `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`](./list.md), 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

```bash
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

```bash
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](./fields.md) |

## Response example

The main fields are shown. Full list: [Order property fields](./fields.md).

```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 |
|------|------|------|
| 400 | `MISSING_REQUIRED_FIELDS` | `personTypeId`, `type`, `name`, or `propsGroupId` is missing; `personTypeId`, `name`, or `propsGroupId` is `null`; or `name` is an empty string |
| 400 | `INVALID_PARAMS` | `type` is not an allowed property type, is `null`, or is an empty string. Message: `Invalid order property type.` |
| 400 | `READONLY_FIELD` | The request contains `id`, `relations` or `variants`, including inside `settings` |
| 400 | `INVALID_PARAMS` | An object or array was passed to a scalar field |
| 400 | `INVALID_PARAMS` | A nonnumeric string, an empty string, or a boolean was passed to a numeric field |
| 400 | `INVALID_PARAMS` | A flag is neither boolean `true`/`false` nor one of the strings `"Y"`/`"N"`, `"yes"`/`"no"`, `"1"`/`"0"`, `"true"`/`"false"` (case-insensitive, ignoring surrounding whitespace) |
| 400 | `INVALID_PARAMS` | `settings` is not a JSON object |
| 422 | `BITRIX_ERROR` | Bitrix24 rejected the operation. The reason is in `message` |
| 422 | `BITRIX_ERROR` | The key's user does not have permission in Bitrix24. The Bitrix24 code is in `error.b24Code`: `200040300020` |
| 403 | `BITRIX_ACCESS_DENIED` | The portal credentials do not have the `sale` scope (`insufficient_scope`) |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode |
| 403 | `SCOPE_DENIED` | The API key does not have the `sale` scope |
| 401 | `MISSING_API_KEY` | The `X-Api-Key` header is missing |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |

For the full list of shared API errors, see [Error codes](/docs/errors).

## See also

- [Order properties](/docs/entities/order-properties)
- [Get an order property](./get.md)
- [Update an order property](./update.md)
- [Delete an order property](./delete.md)
- [Order property fields](./fields.md)