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

Update basket item

PATCH /v1/basket-items/:id

Updates the fields of an existing basket item. Pass only the fields you change, flat at the root of the JSON — no fields wrapper.

Parameters

Parameter Type Req. Description
id (path) number yes Item identifier

Fields to update (body)

Parameter Type Description
quantity number Quantity
price number Price per unit
basePrice number Base price before discount
discountPrice number Discount amount per unit
currency string Currency
name string Product name override
vatRate number VAT rate as a fraction of one
vatIncluded boolean Whether VAT is included in the price
customPrice boolean Protects the price from auto-recalculation
weight number Weight in grams
measureCode number Measurement unit code
xmlId string External identifier

All item fields are editable except the service ones (id, orderId, productId, productXmlId, catalogXmlId, dateInsert, dateUpdate). The full set of available fields is visible in the response of GET /v1/basket-items/:id.

Partial update. You do not need to pass quantity in every request. When quantity is absent from the body, the wrapper reads the item's current quantity and substitutes it — you can change only the price or another field. If the item is not found during such a partial update, 404 ENTITY_NOT_FOUND is returned.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/basket-items/9" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 3,
    "discountPrice": 50
  }'

curl — OAuth app

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/basket-items/9" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 3,
    "discountPrice": 50
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/basket-items/9', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    quantity: 3,
    discountPrice: 50,
  }),
})

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

JavaScript — OAuth app

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/basket-items/9', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    quantity: 3,
    discountPrice: 50,
  }),
})

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

Response fields

Field Type Description
data object The updated item object with all fields

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 9,
    "orderId": 33,
    "productId": 119,
    "name": "Home Slippers Favorite Sport",
    "price": 470,
    "basePrice": 470,
    "discountPrice": 50,
    "currency": "USD",
    "quantity": 3,
    "vatRate": 0,
    "vatIncluded": true,
    "customPrice": false,
    "canBuy": true,
    "weight": 0,
    "measureCode": 796,
    "measureName": "pcs",
    "dateUpdate": "2026-05-13T11:58:14.000Z"
  }
}

Error response example

422 — item not found:

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

Errors

HTTP Code Description
404 ENTITY_NOT_FOUND Item not found (partial PATCH without quantity — detected on pre-fetch)
422 BITRIX_ERROR An item with this ID was not found (PATCH with explicit quantity)
400 BITRIX_ERROR Invalid field value
403 SCOPE_DENIED The API key lacks the sale scope
401 TOKEN_MISSING The API key has no configured tokens

For the full list of common API errors, see Errors.

Known specifics

The fields id, orderId, productId, productXmlId, catalogXmlId, dateInsert are read-only. They are set on creation, and an attempt to change them is ignored. To move an item to another order, delete it via DELETE /v1/basket-items/:id and create a new one via POST /v1/basket-items.

Price protection via customPrice. With customPrice: true, the item price will not be recalculated automatically when the catalog product price changes.

See also