# Shipments

Online store order shipments: delivery service, delivery cost, tracking number, shipping document and the "shipped" mark.

Bitrix24 API: `sale.shipment.*`
Scope: `sale`

## Operations

- [Create a shipment](./shipments/create.md) — `POST /v1/shipments`
- [List shipments](./shipments/list.md) — `GET /v1/shipments`
- [Get a shipment](./shipments/get.md) — `GET /v1/shipments/:id`
- [Update a shipment](./shipments/update.md) — `PATCH /v1/shipments/:id`
- [Delete a shipment](./shipments/delete.md) — `DELETE /v1/shipments/:id`
- [Search shipments](./shipments/search.md) — `POST /v1/shipments/search`
- [Shipment fields](./shipments/fields.md) — `GET /v1/shipments/fields`
- [Aggregate shipments](./shipments/aggregate.md) — `POST /v1/shipments/aggregate`
- [Set the "shipped" mark](./shipments/ship.md) — `POST /v1/shipments/:id/ship`
- [Clear the "shipped" mark](./shipments/unship.md) — `POST /v1/shipments/:id/unship`

## Key fields

| Field | Type | Description |
|------|-----|---------|
| `orderId` | number | Order ID. List: [`GET /v1/orders`](/docs/entities/orders/list). Set only on creation |
| `deliveryId` | number | Delivery service ID. List: [`GET /v1/delivery-services`](/docs/entities/delivery-services/list) |
| `deducted` | boolean | The "shipped" mark. Changed only via [`ship`](./shipments/ship.md) and [`unship`](./shipments/unship.md) |
| `allowDelivery` | boolean | Delivery allowed. A new shipment without this field is created with `false` |
| `statusId` | string | Delivery status. List: [`GET /v1/order-statuses?filter[type]=D`](/docs/entities/order-statuses/list) |
| `responsibleId` | number | Responsible employee. List: [`GET /v1/users`](/docs/entities/users/list) |
| `priceDelivery` | number | Delivery cost |
| `shipmentItems` | array | Shipment items. Changed via [shipment items](/docs/entities/shipment-items) |

Full field list — [`GET /v1/shipments/fields`](./shipments/fields.md).

## What to know before you start

1. **A shipment always belongs to an order.** Creation requires `orderId` and `deliveryId`; a shipment cannot be moved to another order. The shipment number `accountNumber` is built from the order number and the shipment's sequence number joined by `/`, for example `1027/2`.
2. **A new shipment may be created without items.** Shipment contents are set separately, via [shipment items](/docs/entities/shipment-items). After creation, check `shipmentItems` in [`GET /v1/shipments/:id`](./shipments/get.md).
3. **The "shipped" mark is set by a separate action.** The `deducted` field in a create or update body is rejected with `400 READONLY_FIELD`. A new shipment is created without the mark; set it via [`POST /v1/shipments/:id/ship`](./shipments/ship.md). With inventory management enabled, the mark may write off stock from the warehouse.
4. **Updates keep fields you do not send.** [`PATCH /v1/shipments/:id`](./shipments/update.md) reads the shipment before writing, so send only the fields you change. The update is rejected if the shipment cannot be saved without loss: an empty responsible employee, an empty shipment company while the order has a different company, or a manual delivery cost (`customPriceDelivery: true`). Change such a shipment in the Bitrix24 interface.
5. **System shipments are not returned.** List and search return only shipments with `system: false`. The `filter[system]=true` filter returns an empty list.

## Typical scenario

1. Find the order: [`GET /v1/orders`](/docs/entities/orders/list).
2. Pick a delivery service: [`GET /v1/delivery-services`](/docs/entities/delivery-services/list).
3. Create the shipment: [`POST /v1/shipments`](./shipments/create.md) with `orderId` and `deliveryId`.
4. Fill the shipment with items: [shipment items](/docs/entities/shipment-items).
5. Record the tracking number and document number: [`PATCH /v1/shipments/:id`](./shipments/update.md).
6. When the goods are handed over for delivery, set the mark: [`POST /v1/shipments/:id/ship`](./shipments/ship.md).

## Limits

| Limit | Value |
|-------|----------|
| Records per list request | up to 5000 (`limit`), 50 by default |
| Aggregation | up to 5 `aggregate` expressions per request, functions `count`, `sum`, `avg`, `min`, `max` |
| Batch calls | not supported: [`POST /v1/batch`](/docs/batch) returns `ACTION_NOT_SUPPORTED` for `shipments`; call the section's endpoints one at a time |
| Rate limit | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Shipment items](/docs/entities/shipment-items)
- [Orders](/docs/entities/orders)
- [Delivery services](/docs/entities/delivery-services)
- [Order statuses](/docs/entities/order-statuses)
- [CRM deliveries](/docs/entities/crm-deliveries)
- [Entity reference](/docs/entity-api)