## Update an order property

`PATCH /v1/order-properties/:id`

Changes the name, flags and settings of an existing online store order field used at checkout.

Pass only the fields to change at the root of the JSON body, without a `fields` wrapper.

## Parameters

| Parameter | Type | Required | Description |
|----------|-----|:-----:|---------|
| `id` (path) | number | yes | Order property ID. List: [`GET /v1/order-properties`](./list.md) |

## Request body fields

| Field | Type | Required | Description |
|------|------|------|------|
| `name` | string | no | Order field name |
| `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` with a stored file, supply an explicit replacement. Upload using `{ "fileData": ["filename", "base64"] }`, clear the file with `{ "remove": "Y" }` |
| `description` | string \| null | no | Field description |
| `settings` | object | no | Property type settings. A JSON object. Supplied top-level keys replace stored values, and other keys are preserved. `null` and arrays are rejected. 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 |

## Examples

### curl — personal key

```bash
curl -X PATCH "https://vibecode.bitrix24.com/v1/order-properties/125" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Delivery comment",
  "settings": {
    "maxlength": 300
  }
}'
```

### curl — OAuth application

```bash
curl -X PATCH "https://vibecode.bitrix24.com/v1/order-properties/125" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Delivery comment",
  "settings": {
    "maxlength": 300
  }
}'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/order-properties/125', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Delivery comment",
    "settings": {
      "maxlength": 300
    }
  }),
})

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

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/order-properties/125', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Delivery comment",
    "settings": {
      "maxlength": 300
    }
  }),
})

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

## Response fields

| Field | Type | Description |
|------|------|------|
| `success` | boolean | `true` on success. HTTP status: `200` |
| `data` | object | Updated 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": "Delivery comment",
    "propsGroupId": 9,
    "code": "DELIVERY_COMMENT",
    "active": false,
    "defaultValue": "Call before delivery",
    "settings": {
      "maxlength": 300,
      "multiline": "N"
    }
  }
}
```

## Error response example

404 — the property has already been deleted:

```json
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "property is not exists"
  }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `EMPTY_UPDATE_BODY` | The request body is empty |
| 400 | `NO_RECOGNIZED_UPDATE_FIELDS` | The body contains no writable order property field |
| 400 | `READONLY_FIELD` | The request contains `id`, `type`, `personTypeId`, `propsGroupId`, `relations` or `variants`, including any of these fields 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 |
| 400 | `INVALID_PARAMS` | The `FILE` property has a stored file in `defaultValue`, but no explicit `defaultValue` replacement was supplied |
| 400 | `INVALID_PARAMS` | The preliminary read of the property, relations or variants did not provide the data required to save the update |
| 400 | `INVALID_PARAMS` | The property ID is not a positive integer |
| 404 | `ENTITY_NOT_FOUND` | No property exists with this `id`. Message: `property is not exists` |
| 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`: `200040300010` or `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).

## Known specifics

Before the write, all links to payment systems and delivery services are preserved. For `ENUM`, all list options are preserved, including options read from subsequent pages. See [Order properties](/docs/entities/order-properties) for field preservation and concurrent update rules.

## See also

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