Create: Shipments

POST /v1/shipments

Scope: sale.

Example

curl -X POST 'https://vibecode.bitrix24.com/v1/shipments' -H 'X-Api-Key: YOUR_KEY' -H 'Content-Type: application/json' -d '{"orderId": 51, "deliveryId": 5}'

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.

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.

Response

{
  "success": true,
  "data": {
    "id": 42,
    "orderId": 51,
    "deducted": false,
    "trackingNumber": "VIBE-PROBE"
  }
}

Errors

Shipments

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.