# Create Shipment

`POST /inventory/shipments`

Group: Inventory › Shipments · Operation ID: `createShipment`

Creates a shipment as a draft. Send it with POST inventory/shipments/:id/commit.

The shipment is created as a draft and nothing moves: no stock leaves and no cost of sale is posted. POST inventory/shipments/:id/commit sends the goods and posts the cost of sale. Every line must leave from the same warehouse, checked before anything is written. The whole call is one transaction, so a rejected request writes nothing.

[Open in the interactive reference](https://docs.api.lensing.ai/?op=createShipment)

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Api-Version` | header | `"v1"` | yes | The API version this request targets, named by its public identifier. Required on every request; omitting it, or naming a version this company does not have, is answered with 400. This document describes version `v1`. |
| `Idempotency-Key` | header | string | no | An opaque caller-chosen string (1-255 characters) that makes this request safe to retry. Repeating the same key with an identical request body replays the original response instead of re-executing - but only once that original request succeeded; a failed attempt re-executes on retry. Repeating the key with a different body is answered with 422. A key still in flight is answered with 409 - as is a key whose original request was interrupted before it finished, for a few minutes afterwards, until that attempt is presumed dead. A completed response stays replayable for 24 hours. The key is scoped to the caller, not to the action: reusing it for a different action is answered with 409 or 422 rather than treated independently. On read actions this header is ignored. On write actions that cannot offer the guarantee it is answered with `400 IDEMPOTENCY_NOT_SUPPORTED` rather than silently ignored. |

## Request body

Required, `application/json`: createShipmentInput.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `businessPartnerId` | string | yes | The unique identifier for the customer the goods go to. Required. Despite the name, this is a customer id. See id on GET accounting/customers/:id. |
| `entityId` | string | no | The unique identifier for the legal entity. Omit it and the first line's warehouse decides it. See id on GET base/entities. |
| `documentDate` | string (date) | no | The date the shipment is dated. Defaults to today. Use format YYYY-MM-DD. |
| `deliveryDate` | string (date) | no | The planned delivery date. Use format YYYY-MM-DD. |
| `currency` | string | no | The currency for every amount on the shipment. Format ISO 4217, for example 'EUR'. Omit it to use the currency of the legal entity's default accounting book, and creation fails when the entity has no default book. |
| `shipmentCarrierId` | string | no | The unique identifier for the carrier taking the goods. See id on GET inventory/shipment-carriers/:id. |
| `trackingNumber` | string | no | The carrier's tracking number. |
| `referenceNumber` | string | no | The customer's own reference for the shipment. |
| `notes` | string | no | Free text on the shipment. |
| `lines` | array of object | yes | The lines of the shipment. At least one is required. |
| `lines[].itemId` | string | yes | The unique identifier for the item going out. See id on GET inventory/items/:id. |
| `lines[].locationId` | string | yes | The unique identifier for the warehouse the goods leave from. Every line must use the same warehouse. See id on GET inventory/warehouses/:id. |
| `lines[].unitId` | string | yes | The unique identifier for the unit the quantity is counted in. See id on GET inventory/unit-of-measures/:id. |
| `lines[].quantity` | string (decimal) | yes | The quantity to ship, in that unit. Greater than zero. |
| `lines[].unitPrice` | string (decimal) | no | The value of one unit, in the shipment's currency. Omit it to take the price from the sales order line. |
| `lines[].sourceDocumentLineId` | string | no | The sales order line this line ships against. Each order publishes its lines as items[].id on GET accounting/sales-orders/:id. Naming it links the shipment to the order it fulfills. |
| `lines[].notes` | string | no | Free text on the line. |
| `lines[].batches` | array of object | no | The batches going out on this line. Required for a batch-tracked item, and the quantities must add up to the line's quantity. |
| `lines[].batches[].batchNumberId` | string | no | The unique identifier for the batch going out. |
| `lines[].batches[].batchNumber` | string | no | The batch number as printed. Required unless batchNumberId is given. |
| `lines[].batches[].quantity` | string (decimal) | yes | The quantity of this batch to ship, in the line's unit. The batch quantities of a line must add up to the line's quantity. |
| `lines[].serials` | array of object | no | The serialized units going out, one entry per unit. Required for a serialized item, and the count must equal the line's quantity. |
| `lines[].serials[].serialNumberId` | string | no | The unique identifier for the unit going out. |
| `lines[].serials[].serialNumber` | string | no | The serial number stamped on the unit. Required unless serialNumberId is given. |
| `lines[].binLocations` | array of object | no | The bins the goods come out of, in a bin-tracked warehouse. An entry may name a batchNumber or serialNumber of its own line. |
| `lines[].binLocations[].binLocationId` | string | yes | The unique identifier for the bin to take the goods from. See id on GET inventory/bins/:id. |
| `lines[].binLocations[].quantity` | string (decimal) | yes | The quantity taken from this bin, in the line's unit. |
| `lines[].binLocations[].batchNumber` | string | no | Names one of this line's batches, when the bin entry belongs to it. |
| `lines[].binLocations[].serialNumber` | string | no | Names one of this line's serialized units, when the bin entry belongs to it. |

Example:

```json
{
  "businessPartnerId": "c73f2b81-5d94-4e60-a812-0f9b6d3e45c7",
  "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "documentDate": "2026-08-14",
  "deliveryDate": "2026-08-19",
  "currency": "EUR",
  "shipmentCarrierId": "9d0a5e26-b183-4c47-92f5-6a4e17b0c853",
  "trackingNumber": "3SABCD1234567",
  "referenceNumber": "PO-BAKKER-4417",
  "notes": "Palletised",
  "lines": [
    {
      "itemId": "5f21c8b0-9d34-4a76-8e12-04b93c7de5a8",
      "locationId": "e1d84c07-5b39-4a26-9f70-2c8b613ad495",
      "unitId": "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45",
      "quantity": "40.00",
      "unitPrice": "24.00",
      "sourceDocumentLineId": "f9a4cdef-6095-425e-84f1-7f8192801ea2",
      "notes": "Ship complete"
    }
  ]
}
```

## Response

`200` Success

Under `data` (createShipmentOutput):

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The unique identifier for the shipment. |
| `documentNumber` | string | no | The shipment's document number, for example 'SD-8841'. Absent while none has been assigned. |
| `documentStatus` | string | yes | The status of the shipment. Possible values: 'DRAFT', 'PACKED', 'PARTIALLY_SHIPPED', 'SHIPPED', 'COMMITTED', 'DELIVERED', 'COMPLETED', 'CANCELLED', 'INVOICED', 'PARTIALLY_INVOICED', 'RETURNED', 'PARTIALLY_RETURNED'. |
| `documentDate` | string (date) | yes | The date the shipment is dated. Format YYYY-MM-DD. |
| `deliveryDate` | string (date) | no | The planned or actual delivery date. Format YYYY-MM-DD. |
| `entityId` | string | yes | The unique identifier for the legal entity the shipment belongs to. See id on GET base/entities. |
| `entityName` | string | no | The display name of that legal entity. |
| `businessPartnerId` | string | yes | The unique identifier for the customer the goods go to. Despite the name, this is a customer id. See id on GET accounting/customers/:id. |
| `businessPartnerName` | string | no | The display name of that customer. |
| `shipmentCarrierId` | string | no | The unique identifier for the carrier taking the goods. See id on GET inventory/shipment-carriers/:id. |
| `shipmentCarrierName` | string | no | The name of that carrier. |
| `trackingNumber` | string | no | The carrier's tracking number for the goods. |
| `referenceNumber` | string | no | The customer's own reference for the shipment. |
| `returnStatus` | string | no | How much of the shipment has come back on sales returns. Possible values: 'OPEN', 'PARTIALLY_RETURNED', 'FULLY_RETURNED'. The return process maintains it. |
| `currency` | string | no | The currency of every amount on the shipment. Format ISO 4217, for example 'EUR'. |
| `totalAmount` | string (decimal) | no | The total value of the shipment, in the shipment's currency. |
| `notes` | string | no | Free text on the shipment. |
| `createdDate` | string (date-time) | no | The date and time the shipment was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `lastModifiedDate` | string (date-time) | no | The date and time the shipment record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. |
| `lines` | array of object | yes | The lines of the shipment. A shipment always has at least one. |
| `lines[].id` | string | yes | The unique identifier for the shipment line. |
| `lines[].itemId` | string | yes | The unique identifier for the item going out. See id on GET inventory/items/:id. |
| `lines[].itemCode` | string | no | The short code of that item. |
| `lines[].itemName` | string | no | The display name of that item. |
| `lines[].locationId` | string | no | The unique identifier for the warehouse the goods leave from. Every line of a shipment must use the same warehouse. See id on GET inventory/warehouses/:id. |
| `lines[].locationCode` | string | no | The short code of that warehouse. |
| `lines[].locationName` | string | no | The display name of that warehouse. |
| `lines[].unitId` | string | yes | The unique identifier for the unit the quantity is counted in. See id on GET inventory/unit-of-measures/:id. |
| `lines[].unitCode` | string | no | The short code of that unit. |
| `lines[].quantity` | string (decimal) | yes | The quantity going out, in the line's unit. |
| `lines[].inventoryQuantity` | string (decimal) | no | The same quantity in the item's stocking unit. |
| `lines[].pickedQuantity` | string (decimal) | no | How much of the line has been picked. This API does not set it. |
| `lines[].packedQuantity` | string (decimal) | no | How much of the line has been packed. This API does not set it. |
| `lines[].returnedQuantity` | string (decimal) | no | How much of the line has come back on a sales return. |
| `lines[].openReturnQuantity` | string (decimal) | no | How much of the line may still be returned. |
| `lines[].unitPrice` | string (decimal) | no | The value of one unit, in the shipment's currency. |
| `lines[].status` | string | no | Where the line sits in the warehouse process. This is free text with no fixed set of values. |
| `lines[].sourceDocumentLineId` | string | no | The sales order line this line ships against. Each order publishes its lines as items[].id on GET accounting/sales-orders/:id. |
| `lines[].sourceDocumentLineType` | string, one of `"IMInventorySalesOrderLine"`, `"IMInventorySalesDeliveryLine"`, `"IMSalesOrderLine"`, `"IMInventoryPurchaseReturnLine"`, `"IMInventorySalesReturnLine"`, `"IMWarehouseTransferLine"`, `"IMInventoryDecreaseLine"`, `"IMInventoryIncreaseLine"`, `"IMInventoryRevaluationLine"`, `"IMInventoryTransferLine"`, `"IMInventoryAdjustmentLine"`, `"IMInventoryCountLine"`, `"IMInventoryPutAwayTask"`, `"IMInventoryPurchaseReturnReversal"`, `"PurchaseOrderLine"`, `"IMLandedCostAllocationLine"`, `"SalesOrderProductItem"`, `"IMWarehouseTransferOrderLine"`, `"VendorBillItemBase"`, `"InvPurchaseDeliveryLine"` | no | The kind of document line the source line is. |
| `lines[].notes` | string | no | Free text on the line. |
| `lines[].batches` | array of object | no | The batches going out on this line, for a batch-tracked item. Absent when the item is not batch-tracked. |
| `lines[].batches[].batchNumberId` | string | no | The unique identifier for the batch record. |
| `lines[].batches[].batchNumber` | string | yes | The batch number as printed. |
| `lines[].batches[].expirationDate` | string (date) | no | The expiration date of the batch. Format YYYY-MM-DD. |
| `lines[].batches[].quantity` | string (decimal) | yes | The quantity of this batch going out, in the line's unit. |
| `lines[].batches[].inventoryQuantity` | string (decimal) | no | The same quantity in the item's stocking unit. |
| `lines[].batches[].returnedQuantity` | string (decimal) | no | How much of this batch has come back on a sales return. |
| `lines[].batches[].unitCost` | string (decimal) | no | The cost of one unit of this batch at shipment, in the shipment's currency. |
| `lines[].serials` | array of object | no | The serialized units going out, one entry per unit. Absent when the item is not serialized. |
| `lines[].serials[].serialNumberId` | string | no | The unique identifier for the serial record. |
| `lines[].serials[].serialNumber` | string | yes | The serial number stamped on the unit. |
| `lines[].serials[].returnedQuantity` | string (decimal) | no | How much of this unit has come back on a sales return. |
| `lines[].serials[].unitCost` | string (decimal) | no | The cost of this unit at shipment, in the shipment's currency. |
| `lines[].binLocations` | array of object | no | The bins the goods come out of, in a bin-tracked warehouse. Each entry that names a batchNumber or serialNumber belongs to that batch or unit, and one that names neither belongs to the line. |
| `lines[].binLocations[].binLocationId` | string | yes | The unique identifier for the bin the goods come out of. See id on GET inventory/bins/:id. |
| `lines[].binLocations[].binLocationCode` | string | no | The short code of that bin. |
| `lines[].binLocations[].quantity` | string (decimal) | yes | The quantity taken from this bin, in the line's unit. |
| `lines[].binLocations[].inventoryQuantity` | string (decimal) | no | The same quantity in the item's stocking unit. |
| `lines[].binLocations[].batchNumber` | string | no | The batch this bin entry belongs to, when it belongs to one of the line's batches. |
| `lines[].binLocations[].serialNumber` | string | no | The serialized unit this bin entry belongs to, when it belongs to one of the line's units. |

## Response headers

- `Idempotency-Replayed` — Present and `true` only when this response replays a previously stored one for the same Idempotency-Key, rather than reflecting a live execution. Absent on a live response - never sent as `false`.

## Errors

| Code | Status |
| --- | --- |
| `REFERENCE_NOT_FOUND` | 400 |
| `NO_LINES` | 400 |
| `SOURCE_LINE_NOT_PROJECTED` | 400 |
| `INVALID_QUANTITY` | 400 |
| `MIXED_LOCATIONS` | 400 |
| `DUPLICATE_TRACKING_NUMBER` | 400 |
| `UNKNOWN_TRACKING_REFERENCE` | 400 |
| `POSTING_REJECTED` | 400 |
| `IDEMPOTENCY_KEY_CONFLICT` | 409 |
| `IDEMPOTENCY_PAYLOAD_MISMATCH` | 422 |

## Statuses

- `400` — Invalid request or business failure. Codes: REFERENCE_NOT_FOUND, NO_LINES, SOURCE_LINE_NOT_PROJECTED, INVALID_QUANTITY, MIXED_LOCATIONS, DUPLICATE_TRACKING_NUMBER, UNKNOWN_TRACKING_REFERENCE, POSTING_REJECTED
- `401` — Missing or invalid access token
- `403` — Not authorized
- `404` — Not found
- `409` — The Idempotency-Key is still being processed by another request.
- `422` — The Idempotency-Key was already used with a different request payload.
- `429` — Too many requests
- `500` — Internal server error