## 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](/docs/entities/shipment-items).

## Request fields (body)

| Field | Type | Required | Description |
|------|-----|:-----:|---------|
| `orderDeliveryId` | number | yes | Shipment ID. List: [`GET /v1/shipments`](/docs/entities/shipments/list). 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`](/docs/entities/basket-items/list). 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`](./fields.md).

## Examples

### curl — personal key

```bash
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

```bash
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`](./update.md) |
| 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](/docs/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](./fields.md) 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

- [Shipment items](/docs/entities/shipment-items)
- [List shipment items](./list.md)
- [Get a shipment item](./get.md)
- [Update a shipment item](./update.md)
- [Delete a shipment item](./delete.md)
- [Shipment item fields](./fields.md)
- [Shipments](/docs/entities/shipments)
- [Basket items](/docs/entities/basket-items)