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

Update order status

PATCH /v1/order-statuses/:id

Updates the parameters of an existing status. Pass only the changed fields flat at the root of the JSON — without a fields wrapper.

Parameters

Parameter Type Required Description
Parameterid (path) Typestring Requiredyes DescriptionStatus code from List statuses

Fields to update (body)

Parameter Type Description
Parametersort Typenumber DescriptionSort order
Parameternotify Typeboolean DescriptionWhether to send a notification to the customer
Parametercolor Typestring DescriptionHEX color code (#FFA500). At most 10 characters — the database column width; a longer value is refused with 400 INVALID_PARAMS rather than silently truncated
ParameterxmlId Typestring DescriptionExternal identifier

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/order-statuses/T" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sort": 35,
    "color": "#2ECC71"
  }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/order-statuses/T" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sort": 35,
    "color": "#2ECC71"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/order-statuses/T', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    sort: 35,
    color: '#2ECC71',
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/order-statuses/T', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    sort: 35,
    color: '#2ECC71',
  }),
})

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

Response fields

Field Type Description
Fielddata Typeobject DescriptionUpdated status object. Full schema: Status fields

Response example

JSON 
{
  "success": true,
  "data": {
    "id": "T",
    "type": "O",
    "sort": 35,
    "notify": true,
    "color": "#2ECC71",
    "xmlId": null
  }
}

Error response example

404 — status not found:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "status is not exists"
  }
}

Errors

HTTP Code Description
HTTP404 CodeENTITY_NOT_FOUND DescriptionA status with this id was not found
HTTP400 CodeBITRIX_ERROR DescriptionInvalid field value
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the sale scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of general API errors — Errors.

Known specifics

The type field is pulled in automatically. Before updating a status, Vibecode fetches the current type value via GET /v1/order-statuses/:id and automatically adds it to the request if it was not passed. This lets you update a single field via PATCH without specifying the type every time.

The id field is not editable. You cannot change a status character code — PATCH accepts the other fields, but not the id itself. To rename a status, delete the old one and create a new one with the desired id. Note: orders referencing the old id will keep that reference and continue to work.

See also