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

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
orderDeliveryId number yes Shipment ID. List: GET /v1/shipments. Cannot be changed after creation
basketId number yes ID of a basket item from the same order the shipment belongs to. List: GET /v1/basket-items. Cannot be changed after creation
quantity number yes Quantity 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
xmlId string no External 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
success boolean true on success. The response HTTP status is 201
data object The created shipment item
data.id number ID of the created shipment item
data.orderDeliveryId number Shipment ID
data.basketId number Basket item ID
data.quantity number Quantity of the product in the shipment
data.reservedQuantity number Reserved quantity
data.xmlId string External code. If not passed in the request, a generated value such as bx_6ac608ffa0d41
data.dateInsert datetime Creation 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
400 MISSING_REQUIRED_FIELDS A 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
400 READONLY_FIELD The body contains a read-only field, such as reservedQuantity. The field name is in message
400 INVALID_PARAMS A field value does not match its type, such as the string "abc" in the numeric quantity. The field name is in message
422 BITRIX_ERROR quantity exceeds the available quantity of the basket item, b24Code is SALE_SHIPMENT_ITEM_LESS_AVAILABLE_QUANTITY
422 BITRIX_ERROR The 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
422 BITRIX_ERROR No shipment with this orderDeliveryId exists, or the basket item basketId belongs to a different order — shipment not exists, b24Code is 201240400002
422 BITRIX_ERROR No basket item with this basketId exists — shipment not exists, b24Code is 201240400003
422 BITRIX_ERROR Bitrix24 rejected the creation for another reason. The reason text is in message
403 BITRIX_ACCESS_DENIED The key's user has no permission to edit orders in Bitrix24
403 WRITE_BLOCKED_READONLY_KEY The key is in read-only mode
403 SCOPE_DENIED The API key does not have the sale scope
403 MANAGEMENT_KEY_NO_ENTITY_ACCESS The request was made with a management key. Entities require an application key or a personal key with the sale scope
401 MISSING_API_KEY The X-Api-Key header is missing
401 INVALID_API_KEY The provided API key was not found
401 TOKEN_MISSING The API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

A field with an unknown name is not rejected. A body with a field that is not among the shipment item fields passes request validation without a 400 error, and the item is created. Such a field is not saved, and meta.warnings contains no warning about it. A typo in the name of an optional field does not cause an error.

See also