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 Required Description
Parameterid (path) Typenumber Requiredyes DescriptionItem identifier

Fields to update (body)

Parameter Type Description
Parameterquantity Typenumber DescriptionQuantity
Parameterprice Typenumber DescriptionPrice per unit
ParameterbasePrice Typenumber DescriptionBase price before discount
ParameterdiscountPrice Typenumber DescriptionDiscount amount per unit
Parametercurrency Typestring DescriptionCurrency
Parametername Typestring DescriptionProduct name override
ParametervatRate Typenumber DescriptionVAT rate as a fraction of one
ParametervatIncluded Typeboolean DescriptionWhether VAT is included in the price
ParametercustomPrice Typeboolean DescriptionProtects the price from auto-recalculation
Parameterweight Typenumber DescriptionWeight in grams
ParametermeasureCode Typenumber DescriptionMeasurement unit code
ParameterxmlId Typestring DescriptionExternal identifier

All item fields are editable except the service ones (id, orderId, productId, productXmlId, catalogXmlId, dateInsert, dateUpdate). The full set of available fields is returned by 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 application

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 application

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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe updated item object (all fields — see Basket item 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

404 — item not found:

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

Errors

HTTP Code Description
HTTP404 CodeENTITY_NOT_FOUND DescriptionAn item with this ID was not found — both on a partial PATCH without quantity (detected on pre-fetch) and on a PATCH with an explicit quantity
HTTP400 CodeBITRIX_ERROR DescriptionInvalid field value
HTTP403 CodeSCOPE_DENIED DescriptionThe API key lacks the sale scope
HTTP401 CodeTOKEN_MISSING DescriptionThe 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