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

## Operations

- [Create a shipment item](./shipment-items/create.md) — `POST /v1/shipment-items`
- [List shipment items](./shipment-items/list.md) — `GET /v1/shipment-items`
- [Get a shipment item](./shipment-items/get.md) — `GET /v1/shipment-items/:id`
- [Update a shipment item](./shipment-items/update.md) — `PATCH /v1/shipment-items/:id`
- [Delete a shipment item](./shipment-items/delete.md) — `DELETE /v1/shipment-items/:id`
- [Search shipment items](./shipment-items/search.md) — `POST /v1/shipment-items/search`
- [Shipment item fields](./shipment-items/fields.md) — `GET /v1/shipment-items/fields`
- [Aggregate shipment items](./shipment-items/aggregate.md) — `POST /v1/shipment-items/aggregate`
- [Batch operations on shipment items](./shipment-items/batch.md) — `POST /v1/shipment-items/batch`

## Key fields

| Field | Type | Description |
|------|-----|---------|
| `orderDeliveryId` | number | Shipment ID. List: [`GET /v1/shipments`](/docs/entities/shipments/list). Set only on creation |
| `basketId` | number | ID of a basket item of the same order. List: [`GET /v1/basket-items`](/docs/entities/basket-items/list). Set only on creation |
| `quantity` | number | Quantity of the product in the shipment, fractional values allowed |
| `reservedQuantity` | number | Reserved quantity, read-only |
| `xmlId` | string | External code of the item |

Full list of fields — [`GET /v1/shipment-items/fields`](./shipment-items/fields.md).

## What to know before you start

1. **The unallocated basket remainder sits in the system shipment.** Every basket item has a row in the order's system shipment. Creating an item in a regular shipment reduces the quantity in the system row, and deleting it returns the quantity to that row. A quantity above the remainder is rejected with `422 BITRIX_ERROR`. The system shipment is not returned by [`GET /v1/shipments/:id`](/docs/entities/shipments/get), but its items appear in the item list. A system shipment item cannot be changed directly: the remainder changes only through items of regular shipments.
2. **The shipment and the basket item are set only on creation.** Creation requires `orderDeliveryId`, `basketId` and `quantity`, and the shipment and the basket item belong to the same order. A basket item goes into a shipment as a single row: a repeated `basketId` and `orderDeliveryId` pair is rejected. To move an item to another shipment, delete it and create it again.
3. **`quantity` is required in every update.** [`PATCH /v1/shipment-items/:id`](./shipment-items/update.md) without `quantity` is rejected with `422 BITRIX_ERROR`, even if only `xmlId` changes.
4. **Not every list row can be fetched by `id`.** Items of the system shipment and items of shipments that no longer exist are returned by [`GET /v1/shipment-items`](./shipment-items/list.md), but [`GET /v1/shipment-items/:id`](./shipment-items/get.md) returns `404 ENTITY_NOT_FOUND` for them. To get the contents of a specific shipment, filter by `filter[orderDeliveryId]`.

## Typical scenario

1. Find the order: [`GET /v1/orders`](/docs/entities/orders/list).
2. Find the order's basket items: [`GET /v1/basket-items?filter[orderId]=1027`](/docs/entities/basket-items/list).
3. Create a shipment or pick an existing one: [`POST /v1/shipments`](/docs/entities/shipments/create).
4. Add a basket item to the shipment: [`POST /v1/shipment-items`](./shipment-items/create.md) with `orderDeliveryId`, `basketId` and `quantity`.
5. Check the shipment contents: [`GET /v1/shipment-items?filter[orderDeliveryId]=1207`](./shipment-items/list.md).
6. Change the quantity: [`PATCH /v1/shipment-items/:id`](./shipment-items/update.md), or remove the item: [`DELETE /v1/shipment-items/:id`](./shipment-items/delete.md).

## Limits

| Limit | Value |
|-------|----------|
| Records per list request | up to 5000 (`limit`), 50 by default |
| Aggregation | functions `count`, `sum`, `avg`, `min`, `max` in [`POST /v1/shipment-items/aggregate`](./shipment-items/aggregate.md) |
| Batch operations | create, update and delete in [`POST /v1/shipment-items/batch`](./shipment-items/batch.md) |
| Request rate | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Shipments](/docs/entities/shipments)
- [Basket items](/docs/entities/basket-items)
- [Orders](/docs/entities/orders)
- [CRM deliveries](/docs/entities/crm-deliveries)
- [Entity reference](/docs/entity-api)