# Order properties

Field definitions for an online store: names, types, settings, and default values used during checkout. Values entered by a customer in a specific order are stored separately.

When creating a property, select a payer type and a group from existing properties of that type. Partial updates preserve omitted fields and settings. The property type, payer type, and group are set during creation and cannot be changed through PATCH.

Bitrix24 API: `sale.property.*`
Scope: `sale`

## Operations

- [Create an order property](/docs/entities/order-properties/create) — `POST /v1/order-properties`
- [List order properties](/docs/entities/order-properties/list) — `GET /v1/order-properties`
- [Get an order property](/docs/entities/order-properties/get) — `GET /v1/order-properties/:id`
- [Update an order property](/docs/entities/order-properties/update) — `PATCH /v1/order-properties/:id`
- [Delete an order property](/docs/entities/order-properties/delete) — `DELETE /v1/order-properties/:id`
- [Search order properties](/docs/entities/order-properties/search) — `POST /v1/order-properties/search`
- [Order property fields](/docs/entities/order-properties/fields) — `GET /v1/order-properties/fields`
- [Aggregate order properties](/docs/entities/order-properties/aggregate) — `POST /v1/order-properties/aggregate`

## Key fields

| Field | Type | Description |
|------|-----|---------|
| `id` | number | Property definition ID. List: [`GET /v1/order-properties`](./order-properties/list.md) |
| `personTypeId` | number | Payer type ID from [`GET /v1/person-types`](/docs/entities/person-types/list). Required on creation |
| `type` | string | Type: `STRING`, `Y/N`, `NUMBER`, `ENUM`, `FILE`, `DATE`, `LOCATION`, `ADDRESS`. Required on creation |
| `name` | string | Field name. Required on creation |
| `propsGroupId` | number | Property group ID. Get it from a property with the same payer type using [`GET /v1/order-properties`](./order-properties/list.md). Required on creation |
| `settings` | object | Property type settings. Updates merge keys with the stored settings |
| `defaultValue` | any | Default value. The format depends on the property type and whether it accepts multiple values |

For the complete field list, see [`GET /v1/order-properties/fields`](./order-properties/fields.md).

## Before you start

1. **A property definition is distinct from its value.** These methods manage an order field. They do not create entered values, options for the `ENUM` type, or property groups.
2. **The group must belong to the selected payer type.** Find an existing property with the required `personTypeId` using [list](./order-properties/list.md) or [search](./order-properties/search.md) and use its `propsGroupId`. A new payer type may have no properties or groups. This section has no separate route for creating a group.
3. **The property type, payer type, and group cannot be changed.** A `PATCH` containing `id`, `type`, `personTypeId`, or `propsGroupId` returns `400 READONLY_FIELD`. Create another property definition to use a different type.
4. **Partial updates preserve other data.** The property is read before it is written. Omitted fields, flags, sort order, default value, and settings are preserved. `settings` is merged by top-level keys. A failed preliminary read stops the write. A concurrent external change between the read and write may be overwritten.
5. **Settings depend on the type.** `STRING` uses `minlength`, `maxlength`, `multiline`, and `pattern`; `NUMBER` uses `min`, `max`, and `step`; `DATE` uses `time`. Pass the property's own fields at the top level of the body. Nested `relations` and `variants` in `settings` cannot be changed.
6. **A file default requires an explicit replacement.** If a `FILE` property already has a file in `defaultValue`, pass a new `defaultValue` when updating it. Otherwise the request returns `400 INVALID_PARAMS`. The upload format is `{ "fileData": ["filename", "base64"] }`.
7. **Flags use the boolean type.** `active`, `required`, `multiple`, and other flags accept and return `true` or `false`.

## Typical workflow

1. Select a payer type: [`GET /v1/person-types`](/docs/entities/person-types/list).
2. Find a property of this type and get its `propsGroupId`: [`GET /v1/order-properties`](./order-properties/list.md).
3. Create a field definition: [`POST /v1/order-properties`](./order-properties/create.md).
4. Read the definition by its returned `id`: [`GET /v1/order-properties/:id`](./order-properties/get.md).
5. Update the name, flags, or settings: [`PATCH /v1/order-properties/:id`](./order-properties/update.md).
6. Delete the definition when it is no longer needed: [`DELETE /v1/order-properties/:id`](./order-properties/delete.md).

## Limits

| Limit | Value |
|-------|----------|
| Records per list or search request | `limit` up to 5000, default 50. Use `offset` for the following records |
| Aggregation | Up to 5 expressions, functions `count`, `sum`, `avg`, `min`, `max`. Up to 5000 records are read for calculations and grouping |
| Grouping | By `personTypeId`, `type`, `required`, `active`, up to 5 dimensions. `groupLimit` ranges from 1 to 1000 |
| Batch writes | `create`, `update`, `delete`. Up to 500 commands in `POST /v1/order-properties/batch`, sent to Bitrix24 in chunks of up to 50 commands. The property ID must be known in advance. Update each property at most once per request |
| Request rate | Shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

Batch writes are available through `POST /v1/batch` and `POST /v1/order-properties/batch`. They preserve omitted fields during updates using the same rules. Duplicate updates are checked within a single Bitrix24 `batch` call, containing up to 50 commands: a duplicate returns `400 INVALID_PARAMS`. This check does not reject duplicates in different chunks. Use separate requests for sequential updates of the same property. A reference to the creation result cannot replace the ID of a property to update. For the batch format, see [Batch calls](/docs/batch).

## See also

- [Payer types](/docs/entities/person-types)
- [Orders](/docs/entities/orders)
- [Entity API](/docs/entity-api)
- [Batch](/docs/batch)