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
Parameterid (path) Typenumber Requiredyes DescriptionOrder property ID. List: GET /v1/order-properties

Request body fields

Field Type Required Description
Fieldname Typestring Requiredno DescriptionOrder field name
Fieldcode Typestring | null Requiredno DescriptionSymbolic code
Fieldsort Typenumber Requiredno DescriptionSort order
FielddefaultValue Typeany Requiredno DescriptionDefault 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" }
Fielddescription Typestring | null Requiredno DescriptionField description
Fieldsettings Typeobject Requiredno DescriptionProperty 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
FieldxmlId Typestring | null Requiredno DescriptionExternal ID
FieldinputFieldLocation Typenumber Requiredno DescriptionDeprecated field. Bitrix24 does not use it
Fieldactive Typeboolean Requiredno DescriptionThe property is active
Fieldrequired Typeboolean Requiredno DescriptionA value is required at checkout
Fieldmultiple Typeboolean Requiredno DescriptionThe property holds multiple values
FielduserProps Typeboolean Requiredno DescriptionSave the value in the buyer profile
Fieldutil Typeboolean Requiredno DescriptionInternal property
FieldisAddress Typeboolean Requiredno DescriptionThe property contains an address
FieldisAddressFrom Typeboolean Requiredno DescriptionOrigin address
FieldisAddressTo Typeboolean Requiredno DescriptionDestination address
FieldisEmail Typeboolean Requiredno DescriptionThe property contains an email address
FieldisFiltered Typeboolean Requiredno DescriptionUse the property in a filter
FieldisLocation Typeboolean Requiredno DescriptionThe property contains a location
FieldisLocation4tax Typeboolean Requiredno DescriptionLocation used to calculate taxes
FieldisPayer Typeboolean Requiredno DescriptionPayer name
FieldisPhone Typeboolean Requiredno DescriptionPhone number
FieldisProfileName Typeboolean Requiredno DescriptionBuyer profile name
FieldisZip Typeboolean Requiredno DescriptionPostal 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
Fieldsuccess Typeboolean Descriptiontrue on success. HTTP status: 200
Fielddata Typeobject DescriptionUpdated 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
HTTP400 CodeEMPTY_UPDATE_BODY DescriptionThe request body is empty
HTTP400 CodeNO_RECOGNIZED_UPDATE_FIELDS DescriptionThe body contains no writable order property field
HTTP400 CodeREADONLY_FIELD DescriptionThe request contains id, type, personTypeId, propsGroupId, relations or variants, including any of these fields inside settings
HTTP400 CodeINVALID_PARAMS DescriptionAn object or array was passed to a scalar field
HTTP400 CodeINVALID_PARAMS DescriptionA nonnumeric string, an empty string, or a boolean was passed to a numeric field
HTTP400 CodeINVALID_PARAMS DescriptionA flag is neither boolean true/false nor one of the strings "Y"/"N", "yes"/"no", "1"/"0", "true"/"false" (case-insensitive, ignoring surrounding whitespace)
HTTP400 CodeINVALID_PARAMS Descriptionsettings is not a JSON object
HTTP400 CodeINVALID_PARAMS DescriptionThe FILE property has a stored file in defaultValue, but no explicit defaultValue replacement was supplied
HTTP400 CodeINVALID_PARAMS DescriptionThe preliminary read of the property, relations or variants did not provide the data required to save the update
HTTP400 CodeINVALID_PARAMS DescriptionThe property ID is not a positive integer
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo property exists with this id. Message: property is not exists
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the operation. The reason is in message
HTTP422 CodeBITRIX_ERROR DescriptionThe key's user does not have permission in Bitrix24. The Bitrix24 code is in error.b24Code: 200040300010 or 200040300020
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe portal credentials do not have the sale scope (insufficient_scope)
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the sale scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeTOKEN_MISSING DescriptionThe 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