# Shipments

Manage Bitrix24 order shipments. Base method: `sale.shipment.*`. Scope: `sale`.

## Operations

- [List](./shipments/list.md): `GET /v1/shipments`
- [Get](./shipments/get.md): `GET /v1/shipments/:id`
- [Create](./shipments/create.md): `POST /v1/shipments`
- [Update](./shipments/update.md): `PATCH /v1/shipments/:id`
- [Delete](./shipments/delete.md): `DELETE /v1/shipments/:id`
- [Search](./shipments/search.md): `POST /v1/shipments/search`
- [Fields](./shipments/fields.md): `GET /v1/shipments/fields`
- [Aggregate: Shipments](./shipments/aggregate.md): `POST /v1/shipments/aggregate`
- [Ship](./shipments/ship.md): `POST /v1/shipments/:id/ship`
- [Unship](./shipments/unship.md): `POST /v1/shipments/:id/unship`

## Behavior

Lists contain only non-system shipments. Create requires `orderId` and `deliveryId`; the wrapper sets `deducted=N` and defaults `allowDelivery=N`. Look up a delivery service via `/v1/delivery-services` or `sale.delivery.getList`. Without PRODUCT, the Bitrix24 builder may transfer all unallocated positions from the system shipment. Read the composition after creation: the test cloud returned an empty shipment, so positions were added separately. Manage composition through [shipment items](/docs/entities/shipment-items).

PATCH reads the shipment first and preserves omitted fields: `deducted`, `companyId`, `deliveryDocNum`, `trackingNumber`, `comments`, `responsibleId`, `customPriceDelivery`, `priceDelivery`, `basePriceDelivery`, `allowDelivery`, `deliveryId`. A failed pre-read stops the write. `deducted` is readonly; use ship/unship. Batch is disabled through both doors because it does not perform a safe pre-read.

When warehouse accounting is enabled, ship deducts stock. Repeated actions are passed to Bitrix24; business refusals retain the Bitrix24 message. Bitrix24 also decides whether a shipped record can be deleted.

## Related routes

Use [orders](/docs/entities/orders) for an order with nested shipments; use [CRM deliveries](/docs/entities/crm-deliveries) for read-only shipments of a CRM item. These routes manage individual shipments and positions.

PATCH of a shipment with `customPriceDelivery=Y` returns `400 INVALID_PARAMS`: Bitrix24 REST drops this flag and would reset the manual delivery price; update that shipment in the Bitrix24 UI.

For an empty `companyId`, PATCH also reads the parent order. If Bitrix24 would inherit a different order company, it returns `400 INVALID_PARAMS` before writing. Set an explicit nonzero `companyId` or update the shipment in Bitrix24.