Bulk create shipments

Operation ID: bulkCreateShipments

Group: Inventory › Shipments

Open in the interactive reference

POST /inventory/shipments/bulk

Retry-safe: A write that accepts Idempotency-Key: repeating a request with the same key replays the stored answer instead of executing twice.

Creates multiple shipments in one request, each as a draft. Each shipment in shipments takes the same fields as the body of POST inventory/shipments. The response lists the created shipments in the order you sent them.

If any shipment can't be created, none are.

Parameters

Name In Type Required Description
Api-Version header string · 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: bulkCreateShipmentsInput.

Field Type Required Description
shipments array<object> yes The shipments to create. At least one, and each is exactly what POST inventory/shipments takes. Example: [{"businessPartnerId":"c73f2b81-5d94-4e60-a812-0f9b6d3e45c7","documentDate":"2026-08-14","deliveryDate":"2026-08-19","shipmentCarrierId":"9d0a5e26-b183-4c47-92f5-6a4e17b0c853","trackingNumber":"3SABCD1234567","referenceNumber":"PO-BAKKER-4417","currency":"EUR","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"}]}].
shipments[].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.
shipments[].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.
shipments[].documentDate date no The date the shipment is dated. Defaults to today. Use format YYYY-MM-DD.
shipments[].deliveryDate date no The planned delivery date. Use format YYYY-MM-DD.
shipments[].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.
shipments[].shipmentCarrierId string no The unique identifier for the carrier taking the goods. See id on GET inventory/shipment-carriers/:id.
shipments[].trackingNumber string no The carrier's tracking number.
shipments[].referenceNumber string no The customer's own reference for the shipment.
shipments[].notes string no Free text on the shipment.
shipments[].lines array<object> yes The lines of the shipment. At least one is required.
shipments[].lines[].itemId string yes The unique identifier for the item going out. See id on GET inventory/items/:id.
shipments[].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.
shipments[].lines[].unitId string yes The unique identifier for the unit the quantity is counted in. See id on GET inventory/unit-of-measures/:id.
shipments[].lines[].quantity decimal yes The quantity to ship, in that unit. Greater than zero.
shipments[].lines[].unitPrice decimal no The value of one unit, in the shipment's currency. Omit it to take the price from the sales order line.
shipments[].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.
shipments[].lines[].notes string no Free text on the line.
shipments[].lines[].batches array<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 in the item's inventory unit.
shipments[].lines[].batches[].batchNumberId string no The unique identifier for the batch going out. See id on GET inventory/batch-numbers. Either this or batchNumber is required.
shipments[].lines[].batches[].batchNumber string no The batch number as printed. Either this or batchNumberId is required; alone, it must name exactly one batch of the item in the warehouse the line ships from. Given beside batchNumberId, it must be that batch's own number.
shipments[].lines[].batches[].quantity decimal yes The quantity of this batch to ship, in the item's inventory unit. The batch quantities of a line must add up to the line's quantity in that unit.
shipments[].lines[].serials array<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.
shipments[].lines[].serials[].serialNumberId string no The unique identifier for the unit going out. See id on GET inventory/serial-numbers. Either this or serialNumber is required.
shipments[].lines[].serials[].serialNumber string no The serial number stamped on the unit. Either this or serialNumberId is required; alone, it must name exactly one unit of the item in the warehouse the line ships from. Given beside serialNumberId, it must be that unit's own number.
shipments[].lines[].binLocations array<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.
shipments[].lines[].binLocations[].binLocationId string yes The unique identifier for the bin to take the goods from. See id on GET inventory/bins/:id.
shipments[].lines[].binLocations[].quantity decimal yes The quantity taken from this bin, in the item's inventory unit.
shipments[].lines[].binLocations[].batchNumber string no Names one of this line's batches, when the bin entry belongs to it.
shipments[].lines[].binLocations[].serialNumber string no Names one of this line's serialized units, when the bin entry belongs to it. 
{
  "shipments": [
    {
      "businessPartnerId": "c73f2b81-5d94-4e60-a812-0f9b6d3e45c7",
      "documentDate": "2026-08-14",
      "deliveryDate": "2026-08-19",
      "shipmentCarrierId": "9d0a5e26-b183-4c47-92f5-6a4e17b0c853",
      "trackingNumber": "3SABCD1234567",
      "referenceNumber": "PO-BAKKER-4417",
      "currency": "EUR",
      "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 (bulkCreateShipmentsOutput):

Field Type Required Description
items array<object> yes The created shipments, in input order. Match them to inputs by position. Example: [{"id":"2f7c9b31-8a05-4d16-b47e-903c5f1a86d2","documentNumber":"SD-8841","documentStatus":"DRAFT","documentDate":"2026-08-14","deliveryDate":"2026-08-19","entityId":"1a9c4e70-38b5-4d26-9f01-7c2e5b8a6d43","entityName":"Acme Netherlands B.V.","businessPartnerId":"c73f2b81-5d94-4e60-a812-0f9b6d3e45c7","businessPartnerName":"Bakker Retail B.V.","shipmentCarrierId":"9d0a5e26-b183-4c47-92f5-6a4e17b0c853","shipmentCarrierName":"PostNL","trackingNumber":"3SABCD1234567","referenceNumber":"PO-BAKKER-4417","returnStatus":"OPEN","currency":"EUR","totalAmount":"960.00","notes":"Palletised","createdDate":"2026-08-14T08:30:00.000Z","lastModifiedDate":"2026-08-14T08:30:00.000Z","lines":[{"id":"8c14a6f2-3b70-4d59-9e02-6f5a1d38b47c","itemId":"5f21c8b0-9d34-4a76-8e12-04b93c7de5a8","itemCode":"WIDGET-01","itemName":"Standard widget","locationId":"e1d84c07-5b39-4a26-9f70-2c8b613ad495","locationCode":"WH-01","locationName":"Rotterdam Distribution Centre","unitId":"3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45","unitCode":"EA","quantity":"40.00","inventoryQuantity":"40.00","unitPrice":"24.00","sourceDocumentLineId":"f9a4cdef-6095-425e-84f1-7f8192801ea2","sourceDocumentLineType":"SalesOrderProductItem","notes":"Ship complete"}]}].
items[].id string yes The unique identifier for the shipment.
items[].documentNumber string no The shipment's document number, for example 'SD-8841'. Absent while none has been assigned.
items[].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'.
items[].documentDate date yes The date the shipment is dated. Format YYYY-MM-DD.
items[].deliveryDate date no The planned or actual delivery date. Format YYYY-MM-DD.
items[].entityId string yes The unique identifier for the legal entity the shipment belongs to. See id on GET base/entities.
items[].entityName string no The display name of that legal entity.
items[].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.
items[].businessPartnerName string no The display name of that customer.
items[].shipmentCarrierId string no The unique identifier for the carrier taking the goods. See id on GET inventory/shipment-carriers/:id.
items[].shipmentCarrierName string no The name of that carrier.
items[].trackingNumber string no The carrier's tracking number for the goods.
items[].referenceNumber string no The customer's own reference for the shipment.
items[].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.
items[].currency string no The currency of every amount on the shipment. Format ISO 4217, for example 'EUR'.
items[].totalAmount decimal no The total value of the shipment, in the shipment's currency.
items[].notes string no Free text on the shipment.
items[].createdDate date-time no The date and time the shipment was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].lastModifiedDate date-time no The date and time the shipment record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].lines array<object> yes The lines of the shipment. A shipment always has at least one.
items[].lines[].id string yes The unique identifier for the shipment line.
items[].lines[].itemId string yes The unique identifier for the item going out. See id on GET inventory/items/:id.
items[].lines[].itemCode string no The short code of that item.
items[].lines[].itemName string no The display name of that item.
items[].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.
items[].lines[].locationCode string no The short code of that warehouse.
items[].lines[].locationName string no The display name of that warehouse.
items[].lines[].unitId string yes The unique identifier for the unit the quantity is counted in. See id on GET inventory/unit-of-measures/:id.
items[].lines[].unitCode string no The short code of that unit.
items[].lines[].quantity decimal yes The quantity going out, in the line's unit.
items[].lines[].inventoryQuantity decimal no The same quantity in the item's stocking unit.
items[].lines[].pickedQuantity decimal no How much of the line has been picked. This API does not set it.
items[].lines[].packedQuantity decimal no How much of the line has been packed. This API does not set it.
items[].lines[].returnedQuantity decimal no How much of the line has come back on a sales return.
items[].lines[].openReturnQuantity decimal no How much of the line may still be returned.
items[].lines[].unitPrice decimal no The value of one unit, in the shipment's currency.
items[].lines[].status string no Where the line sits in the warehouse process. This is free text with no fixed set of values.
items[].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.
items[].lines[].sourceDocumentLineType any no The kind of document line the source line is. One of: "IMInventorySalesOrderLine", "IMInventorySalesDeliveryLine", "IMSalesOrderLine", "IMInventoryPurchaseReturnLine", "IMInventorySalesReturnLine", "IMWarehouseTransferLine", "IMInventoryDecreaseLine", "IMInventoryIncreaseLine", "IMInventoryRevaluationLine", "IMInventoryTransferLine", "IMInventoryAdjustmentLine", "IMInventoryCountLine", "IMInventoryPutAwayTask", "IMInventoryPurchaseReturnReversal", "PurchaseOrderLine", "IMLandedCostAllocationLine", "SalesOrderProductItem", "IMWarehouseTransferOrderLine", "VendorBillItemBase", "InvPurchaseDeliveryLine".
items[].lines[].notes string no Free text on the line.
items[].lines[].batches array<object> no The batches going out on this line, for a batch-tracked item. Absent when the item is not batch-tracked.
items[].lines[].batches[].batchNumberId string no The unique identifier for the batch record.
items[].lines[].batches[].batchNumber string yes The batch number as printed.
items[].lines[].batches[].expirationDate date no The expiration date of the batch. Format YYYY-MM-DD.
items[].lines[].batches[].quantity decimal yes The quantity of this batch going out, in the item's inventory unit.
items[].lines[].batches[].inventoryQuantity decimal no The same quantity in the item's stocking unit.
items[].lines[].batches[].returnedQuantity decimal no How much of this batch has come back on a sales return.
items[].lines[].batches[].unitCost decimal no The cost of one unit of this batch at shipment, in the shipment's currency.
items[].lines[].serials array<object> no The serialized units going out, one entry per unit. Absent when the item is not serialized.
items[].lines[].serials[].serialNumberId string no The unique identifier for the serial record.
items[].lines[].serials[].serialNumber string yes The serial number stamped on the unit.
items[].lines[].serials[].returnedQuantity decimal no How much of this unit has come back on a sales return.
items[].lines[].serials[].unitCost decimal no The cost of this unit at shipment, in the shipment's currency.
items[].lines[].binLocations array<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.
items[].lines[].binLocations[].binLocationId string yes The unique identifier for the bin the goods come out of. See id on GET inventory/bins/:id.
items[].lines[].binLocations[].binLocationCode string no The short code of that bin.
items[].lines[].binLocations[].quantity decimal yes The quantity taken from this bin, in the item's inventory unit.
items[].lines[].binLocations[].inventoryQuantity decimal no The same quantity in the item's stocking unit.
items[].lines[].binLocations[].batchNumber string no The batch this bin entry belongs to, when it belongs to one of the line's batches.
items[].lines[].binLocations[].serialNumber string no The serialized unit this bin entry belongs to, when it belongs to one of the line's units. 
{
  "data": {
    "items": [
      {
        "id": "2f7c9b31-8a05-4d16-b47e-903c5f1a86d2",
        "documentNumber": "SD-8841",
        "documentStatus": "DRAFT",
        "documentDate": "2026-08-14",
        "deliveryDate": "2026-08-19",
        "entityId": "1a9c4e70-38b5-4d26-9f01-7c2e5b8a6d43",
        "entityName": "Acme Netherlands B.V.",
        "businessPartnerId": "c73f2b81-5d94-4e60-a812-0f9b6d3e45c7",
        "businessPartnerName": "Bakker Retail B.V.",
        "shipmentCarrierId": "9d0a5e26-b183-4c47-92f5-6a4e17b0c853",
        "shipmentCarrierName": "PostNL",
        "trackingNumber": "3SABCD1234567",
        "referenceNumber": "PO-BAKKER-4417",
        "returnStatus": "OPEN",
        "currency": "EUR",
        "totalAmount": "960.00",
        "notes": "Palletised",
        "createdDate": "2026-08-14T08:30:00.000Z",
        "lastModifiedDate": "2026-08-14T08:30:00.000Z",
        "lines": [
          {
            "id": "8c14a6f2-3b70-4d59-9e02-6f5a1d38b47c",
            "itemId": "5f21c8b0-9d34-4a76-8e12-04b93c7de5a8",
            "itemCode": "WIDGET-01",
            "itemName": "Standard widget",
            "locationId": "e1d84c07-5b39-4a26-9f70-2c8b613ad495",
            "locationCode": "WH-01",
            "locationName": "Rotterdam Distribution Centre",
            "unitId": "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45",
            "unitCode": "EA",
            "quantity": "40.00",
            "inventoryQuantity": "40.00",
            "unitPrice": "24.00",
            "sourceDocumentLineId": "f9a4cdef-6095-425e-84f1-7f8192801ea2",
            "sourceDocumentLineType": "SalesOrderProductItem",
            "notes": "Ship complete"
          }
        ]
      }
    ]
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Response headers

Errors

Code Status
NOTHING_TO_CREATE 400
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