Para agentes de IA: markdown desta página — /docs-content-en/entities/shipment-items.md índice da documentação — /llms.txt

Os artigos da documentação estão disponíveis atualmente em inglês.

Shipment items

The contents of an online store order shipment: which basket item goes into the shipment and in what quantity.

Bitrix24 API: sale.shipmentitem.* Scope: sale

Create a shipment item

POST /v1/shipment-items

Adds a basket item of an online store order to a shipment in the specified quantity.

Fields are passed flat at the JSON root, without a fields wrapper. For where the available quantity of a basket item comes from, see Shipment items.

Request fields (body)

Field Type Required Description
FieldorderDeliveryId Typenumber Requiredyes DescriptionShipment ID. List: GET /v1/shipments. Cannot be changed after creation
FieldbasketId Typenumber Requiredyes DescriptionID of a basket item from the same order the shipment belongs to. List: GET /v1/basket-items. Cannot be changed after creation
Fieldquantity Typenumber Requiredyes DescriptionQuantity of the product in the shipment. A fractional value, such as 0.5, is stored without rounding. A number passed as a string with a dot, such as "0.5", is also accepted. Must not exceed the available quantity of the basket item
FieldxmlId Typestring Requiredno DescriptionExternal code. If omitted, it is generated automatically

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

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/shipment-items" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orderDeliveryId": 1207,
    "basketId": 1387,
    "quantity": 0.5
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/shipment-items" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orderDeliveryId": 1207,
    "basketId": 1387,
    "quantity": 0.5
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/shipment-items', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    orderDeliveryId: 1207,
    basketId: 1387,
    quantity: 0.5,
  }),
})

const { success, data } = await res.json()
console.log('Shipment item ID:', data.id)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/shipment-items', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    orderDeliveryId: 1207,
    basketId: 1387,
    quantity: 0.5,
  }),
})

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

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on success. The response HTTP status is 201
Fielddata Typeobject DescriptionThe created shipment item
Fielddata.id Typenumber DescriptionID of the created shipment item
Fielddata.orderDeliveryId Typenumber DescriptionShipment ID
Fielddata.basketId Typenumber DescriptionBasket item ID
Fielddata.quantity Typenumber DescriptionQuantity of the product in the shipment
Fielddata.reservedQuantity Typenumber DescriptionReserved quantity
Fielddata.xmlId Typestring DescriptionExternal code. If not passed in the request, a generated value such as bx_6ac608ffa0d41
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.5,
    "reservedQuantity": 0,
    "xmlId": "bx_6ac608ffa0d41"
  }
}

Error response example

422 — quantity exceeds the available quantity of the basket item:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "The basket does not have enough available quantity of the product \"product\" to add to the shipment. You may have already added part of this product from this order to other shipments",
    "b24Code": "SALE_SHIPMENT_ITEM_LESS_AVAILABLE_QUANTITY"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionA required field is missing or empty. Fields are checked in the order orderDeliveryId, basketId, quantity, and message contains the name of the first missing one
HTTP400 CodeNESTED_FIELDS_ENVELOPE DescriptionThe body contains an object under fields instead of flat fields at the JSON root; the item is not created
HTTP400 CodeREADONLY_FIELD DescriptionThe body contains a read-only field, such as reservedQuantity. The field name is in message
HTTP400 CodeINVALID_PARAMS DescriptionA field value does not match its type, such as the string "abc" in the numeric quantity. The field name is in message
HTTP422 CodeBITRIX_ERROR Descriptionquantity exceeds the available quantity of the basket item, b24Code is SALE_SHIPMENT_ITEM_LESS_AVAILABLE_QUANTITY
HTTP422 CodeBITRIX_ERROR DescriptionThe basket item is already in this shipment — Duplicate entry for key [basketId, orderDeliveryId]. Change the quantity of the existing item with PATCH /v1/shipment-items/:id
HTTP422 CodeBITRIX_ERROR DescriptionNo shipment with this orderDeliveryId exists, or the basket item basketId belongs to a different order — shipment not exists, b24Code is 201240400002
HTTP422 CodeBITRIX_ERROR DescriptionNo basket item with this basketId exists — shipment not exists, b24Code is 201240400003
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the creation for another reason. The reason text is in message
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key's user has no permission to edit orders in Bitrix24
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the sale scope
HTTP403 CodeMANAGEMENT_KEY_NO_ENTITY_ACCESS DescriptionThe request was 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 missing
HTTP401 CodeINVALID_API_KEY DescriptionThe provided API key was not found
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

An unknown scalar field name is not rejected. An unknown scalar field passes validation without a 400, is not saved and produces no warning. An object under fields is a separate case: it is rejected with 400 NESTED_FIELDS_ENVELOPE before creation. Pass shipment item fields at the JSON root.

See also