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

Update a shipment item

PATCH /v1/shipment-items/:id

Changes the product quantity and the external code of a shipment item in an online store order.

Fields are passed flat at the JSON root, without a fields wrapper. How a quantity change affects the free quantity of the basket item is described in Shipment items.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionShipment item ID, a non-negative integer. List: GET /v1/shipment-items

Request fields (body)

Field Type Required Description
Fieldquantity Typenumber Requiredyes DescriptionNew product quantity in the shipment. Pass it in every request, including when only xmlId changes. A fractional value is stored without rounding. A numeric string with a decimal point is also accepted, for example "0.5". An increase is limited by the free quantity of the basket item
FieldxmlId Typestring Requiredno DescriptionExternal code
FieldorderDeliveryId Typenumber Requiredno DescriptionRO. Set only on creation. To move the item to another shipment, delete it and create it again
FieldbasketId Typenumber Requiredno DescriptionRO. Set only on creation
FieldreservedQuantity Typenumber Requiredno DescriptionRO. Reserved quantity

Full list of fields: GET /v1/shipment-items/fields.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/shipment-items/1353" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 0.75,
    "xmlId": "vibe-doc-si-1"
  }'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/shipment-items/1353" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 0.75,
    "xmlId": "vibe-doc-si-1"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/shipment-items/1353', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    quantity: 0.75,
    xmlId: 'vibe-doc-si-1',
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/shipment-items/1353', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    quantity: 0.75,
    xmlId: 'vibe-doc-si-1',
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success
Fielddata Typeobject DescriptionThe updated shipment item with all fields
Fielddata.id Typenumber DescriptionShipment item ID
Fielddata.orderDeliveryId Typenumber DescriptionShipment ID
Fielddata.basketId Typenumber DescriptionBasket item ID
Fielddata.quantity Typenumber DescriptionProduct quantity in the shipment after the change
Fielddata.reservedQuantity Typenumber DescriptionReserved quantity
Fielddata.xmlId Typestring DescriptionExternal code
Fielddata.dateInsert Typedatetime DescriptionCreation date, ISO 8601

Response example

JSON 
{
  "success": true,
  "data": {
    "basketId": 1387,
    "dateInsert": "2026-10-07T09:55:27.000Z",
    "id": 1353,
    "orderDeliveryId": 1207,
    "quantity": 0.75,
    "reservedQuantity": 0,
    "xmlId": "vibe-doc-si-1"
  }
}

Error response example

404 — no shipment item with this id:

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

Errors

HTTP Code Description
HTTP400 CodeREADONLY_FIELD DescriptionThe body contains a read-only field: orderDeliveryId, basketId, reservedQuantity, id and others. The field name is in message
HTTP400 CodeEMPTY_UPDATE_BODY DescriptionThe request body is empty or is not a JSON object
HTTP400 CodeINVALID_PARAMS DescriptionA field value does not match its type, for example the string "abc" in the numeric quantity. The field name is in message
HTTP400 CodeINVALID_PARAMS Descriptionid in the path is not a non-negative integer
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo shipment item with this id: shipment item is not exists
HTTP404 CodeENTITY_NOT_FOUND DescriptionThe item belongs to the system shipment, and the passed quantity equals the current one. The change is not saved: shipmentItem <id> not found
HTTP422 CodeBITRIX_ERROR DescriptionThe item belongs to the system shipment, and a new quantity is passed. The change is not saved: System shipment cannot be modified, b24Code is 150
HTTP422 CodeBITRIX_ERROR DescriptionThe body has no quantity, for example only xmlId or only a field with an unknown name is passed: Required fields: quantity
HTTP422 CodeBITRIX_ERROR DescriptionThe new quantity exceeds the quantity available to the basket item, b24Code is SALE_SHIPMENT_ITEM_LESS_AVAILABLE_QUANTITY
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the change for another reason. The reason is in message
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key's user has no permission to modify orders in Bitrix24
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key works in read-only mode
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the sale scope
HTTP403 CodeMANAGEMENT_KEY_NO_ENTITY_ACCESS DescriptionThe request is made with a management key. Entities require an application key or a personal key with the sale scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is not passed
HTTP401 CodeINVALID_API_KEY DescriptionThe passed API key is not found
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors: Errors.

See also