For AI agents: markdown of this page — /docs-content-en/entities/order-properties/update.md documentation index — /llms.txt

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

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

Terminal 
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

Terminal 
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

Response example

The main fields are shown. Full list: Order property fields.

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.

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 for field preservation and concurrent update rules.

See also