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 Req. Description
id (path) string yes Status character code

Fields to update (body)

Parameter Type Description
sort number Sort order
notify boolean Whether to send a notification to the customer
color string HEX color code (#FFA500)
xmlId string External 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
data object Updated status object with all fields

Response example

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

Error response example

422 — status not found:

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

Errors

HTTP Code Description
422 BITRIX_ERROR A status with this id was not found
400 BITRIX_ERROR Invalid field value
403 SCOPE_DENIED The API key does not have the sale scope
401 TOKEN_MISSING The 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