# Order properties

Methods: `sale.property.*`. Scope: `sale`.

## Operations

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

## Usage notes

These are field definitions, not order field values. Types: STRING, Y/N, NUMBER, ENUM, FILE, DATE, LOCATION, ADDRESS. Creation requires personTypeId, type, name and propsGroupId. Find a group in existing properties for the same payer type: new payer types may have no groups. These routes do not create groups. On PATCH, type, personTypeId and propsGroupId are read-only: Bitrix24 silently ignores changes. Before PATCH the wrapper reads the record and preserves omitted fields, flags, sort order, the default value and settings. A failed read stops the write. settings is merged by key, preserving other settings. REST cannot make concurrent external changes between this read and write atomic. Both batch endpoints use the same protection; the id must be known before batch execution, so a reference to a create result is unsupported.

settings depends on type: STRING — size, minlength, maxlength, multiline, pattern, cols, rows; NUMBER — min, max, step; ENUM — multielement, size; DATE — time; FILE — maxsize, accept. Do not place ordinary property fields in settings: Bitrix24 flattens the object into parameters. defaultValue depends on type and multiplicity: a scalar or an array. ENUM variants (sale.propertyvariant.*) and values in orders (sale.propertyvalue.*) are outside this section.

Deletion keeps values in existing orders but detaches them from the definition: ORDER_PROPS_ID becomes NULL. Bitrix24 deletes variants, customer profile values and definition relations.

Y/N flags accept and return booleans. Missing record: 404 ENTITY_NOT_FOUND. Business refusal: 422 with the Bitrix24 message. Empty POST: 400 MISSING_REQUIRED_FIELDS. A READONLY key cannot write (403). Lists support filter, select, sort, limit, offset; Bitrix24 pages contain 50 rows and V1 fetches more automatically when limit > 50.

`POST /v1/batch`, `POST /v1/order-properties/batch`.

Each property can be updated only once in a batch: a duplicate returns 400 INVALID_PARAMS before writing. This avoids restoring a speculative snapshot if an earlier batch command failed. Use separate requests for sequential updates.

Before updating, V1 internally reads all sale.propertyrelation.list pages and preserves P/D links through settings; this release has no public relation routes. If this read fails, no write runs. For FILE with a stored default file, a partial PATCH without an explicit defaultValue replacement returns 400 INVALID_PARAMS: the read format cannot be reused for writing, and omission deletes the file. An explicit replacement is passed to Bitrix24; defaultValue uploads use fileData [filename, base64], removal uses remove: Y.

settings must be a JSON object: null and arrays return 400 INVALID_PARAMS. For ENUM, before PATCH V1 internally reads all sale.propertyvariant.list pages and preserves variants to validate defaultValue; writing variants at the top level or in settings is refused (400 READONLY_FIELD). defaultValue is a polymorphic JSON value depending on property type: string, number, boolean, array, object or null; Bitrix24 performs further validation.