Update a shipment

Operation ID: updateShipment

Group: Inventory › Shipments

PATCH /inventory/shipments/{id}

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

Updates a shipment with the fields you send. A field you leave out keeps its current value.

Use the shipment's id, not its documentNumber.

Lines change through three separate arrays, applied in this order: updateLines, createLines, deleteLines. Leave out all three to keep the lines as they are. On an updateLines item, a field you leave out keeps its current value.

On an updateLines item, sending batches, serials, or binLocations replaces all of that line's tracking, so send every batch, serial, and bin detail the line should keep. Leave all three out, or send them empty, to keep the line's tracking as it is.

Changes a shipment in 'DRAFT' status, including its lines. A shipment in any other status, 'PACKED' included, can't be changed.

One request can remove a line and add its replacement. If a line id in deleteLines or updateLines is not on this shipment, the request fails with REFERENCE_NOT_FOUND.

The response is the updated shipment with its lines.

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.
`id`	path	string	yes	The unique identifier of the shipment you want to update.

Request body

Required, application/json: updateShipmentInput.

Field	Type	Required	Description
`businessPartnerId`	string	no	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.
`documentDate`	date	no	The date the shipment is dated. Use format YYYY-MM-DD.
`deliveryDate`	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'.
`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. Example: `"3SABCD7654321"`.
`referenceNumber`	string	no	The customer's own reference for the shipment.
`notes`	string	no	Free text on the shipment. Pass an empty string to clear it.
`deleteLines`	array<string>	no	The unique identifiers of lines to remove. Applied before updateLines and createLines.
`updateLines`	array<object>	no	The lines to change, each addressed by id. Applied after deleteLines and before createLines. Example: `[{"id":"8c14a6f2-3b70-4d59-9e02-6f5a1d38b47c","quantity":"36.00"}]`.
`updateLines[].id`	string	yes	The unique identifier for the line to change. A line belonging to another shipment is rejected.
`updateLines[].itemId`	string	no	The unique identifier for the item going out. See id on GET inventory/items/:id.
`updateLines[].locationId`	string	no	The unique identifier for the warehouse the goods leave from. It must agree with every other line. See id on GET inventory/warehouses/:id.
`updateLines[].unitId`	string	no	The unique identifier for the unit the quantity is counted in. See id on GET inventory/unit-of-measures/:id.
`updateLines[].quantity`	decimal	no	The quantity to ship, in the line's unit. Greater than zero.
`updateLines[].unitPrice`	decimal	no	The value of one unit, in the shipment's currency.
`updateLines[].notes`	string	no	Free text on the line. Pass an empty string to clear it.
`updateLines[].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. This replaces the line's batches.
`updateLines[].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.
`updateLines[].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.
`updateLines[].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.
`updateLines[].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. This replaces the line's serials.
`updateLines[].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.
`updateLines[].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.
`updateLines[].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. This replaces the line's bin entries.
`updateLines[].binLocations[].binLocationId`	string	yes	The unique identifier for the bin to take the goods from. See id on GET inventory/bins/:id.
`updateLines[].binLocations[].quantity`	decimal	yes	The quantity taken from this bin, in the item's inventory unit.
`updateLines[].binLocations[].batchNumber`	string	no	Names one of this line's batches, when the bin entry belongs to it.
`updateLines[].binLocations[].serialNumber`	string	no	Names one of this line's serialized units, when the bin entry belongs to it.
`createLines`	array<object>	no	The lines to add.
`createLines[].itemId`	string	yes	The unique identifier for the item going out. See id on GET inventory/items/:id.
`createLines[].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.
`createLines[].unitId`	string	yes	The unique identifier for the unit the quantity is counted in. See id on GET inventory/unit-of-measures/:id.
`createLines[].quantity`	decimal	yes	The quantity to ship, in that unit. Greater than zero.
`createLines[].unitPrice`	decimal	no	The value of one unit, in the shipment's currency. Omit it to take the price from the sales order line.
`createLines[].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.
`createLines[].notes`	string	no	Free text on the line.
`createLines[].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.
`createLines[].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.
`createLines[].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.
`createLines[].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.
`createLines[].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.
`createLines[].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.
`createLines[].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.
`createLines[].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.
`createLines[].binLocations[].binLocationId`	string	yes	The unique identifier for the bin to take the goods from. See id on GET inventory/bins/:id.
`createLines[].binLocations[].quantity`	decimal	yes	The quantity taken from this bin, in the item's inventory unit.
`createLines[].binLocations[].batchNumber`	string	no	Names one of this line's batches, when the bin entry belongs to it.
`createLines[].binLocations[].serialNumber`	string	no	Names one of this line's serialized units, when the bin entry belongs to it.

{
  "businessPartnerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "documentDate": "2026-01-15",
  "deliveryDate": "2026-01-15",
  "currency": "<currency>",
  "shipmentCarrierId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "trackingNumber": "3SABCD7654321",
  "referenceNumber": "<referenceNumber>",
  "notes": "<notes>",
  "deleteLines": [
    "<deleteLines>"
  ],
  "updateLines": [
    {
      "id": "8c14a6f2-3b70-4d59-9e02-6f5a1d38b47c",
      "quantity": "36.00"
    }
  ],
  "createLines": [
    {
      "itemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "locationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "unitId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "quantity": "19.99",
      "unitPrice": "19.99",
      "sourceDocumentLineId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "notes": "<notes>",
      "batches": [
        {
          "batchNumberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "batchNumber": "<batchNumber>",
          "quantity": "19.99"
        }
      ],
      "serials": [
        {
          "serialNumberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "serialNumber": "<serialNumber>"
        }
      ],
      "binLocations": [
        {
          "binLocationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "quantity": "19.99",
          "batchNumber": "<batchNumber>",
          "serialNumber": "<serialNumber>"
        }
      ]
    }
  ]
}

Response

200 Success

Under data (updateShipmentOutput):

Field	Type	Required	Description
`id`	string	yes	The unique identifier for the shipment. Example: `"2f7c9b31-8a05-4d16-b47e-903c5f1a86d2"`.
`documentNumber`	string	no	The shipment's document number, for example 'SD-8841'. Absent while none has been assigned. Example: `"SD-8841"`.
`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'. Example: `"DRAFT"`.
`documentDate`	date	yes	The date the shipment is dated. Format YYYY-MM-DD. Example: `"2026-08-14"`.
`deliveryDate`	date	no	The planned or actual delivery date. Format YYYY-MM-DD. Example: `"2026-08-19"`.
`entityId`	string	yes	The unique identifier for the legal entity the shipment belongs to. See id on GET base/entities. Example: `"1a9c4e70-38b5-4d26-9f01-7c2e5b8a6d43"`.
`entityName`	string	no	The display name of that legal entity. Example: `"Acme Netherlands B.V."`.
`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. Example: `"c73f2b81-5d94-4e60-a812-0f9b6d3e45c7"`.
`businessPartnerName`	string	no	The display name of that customer. Example: `"Bakker Retail B.V."`.
`shipmentCarrierId`	string	no	The unique identifier for the carrier taking the goods. See id on GET inventory/shipment-carriers/:id. Example: `"9d0a5e26-b183-4c47-92f5-6a4e17b0c853"`.
`shipmentCarrierName`	string	no	The name of that carrier. Example: `"PostNL"`.
`trackingNumber`	string	no	The carrier's tracking number for the goods. Example: `"3SABCD7654321"`.
`referenceNumber`	string	no	The customer's own reference for the shipment. Example: `"PO-BAKKER-4417"`.
`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. Example: `"OPEN"`.
`currency`	string	no	The currency of every amount on the shipment. Format ISO 4217, for example 'EUR'. Example: `"EUR"`.
`totalAmount`	decimal	no	The total value of the shipment, in the shipment's currency. Example: `"864.00"`.
`notes`	string	no	Free text on the shipment. Example: `"Palletised"`.
`createdDate`	date-time	no	The date and time the shipment was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. Example: `"2026-08-14T08:30:00.000Z"`.
`lastModifiedDate`	date-time	no	The date and time the shipment record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. Example: `"2026-08-14T09:05:00.000Z"`.
`lines`	array<object>	yes	The lines of the shipment. A shipment always has at least one. Example: [{"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":"36.00","inventoryQuantity":"36.00","unitPrice":"24.00","sourceDocumentLineId":"f9a4cdef-6095-425e-84f1-7f8192801ea2","sourceDocumentLineType":"SalesOrderProductItem","notes":"Ship complete"}].
`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`	decimal	yes	The quantity going out, in the line's unit.
`lines[].inventoryQuantity`	decimal	no	The same quantity in the item's stocking unit.
`lines[].pickedQuantity`	decimal	no	How much of the line has been picked. This API does not set it.
`lines[].packedQuantity`	decimal	no	How much of the line has been packed. This API does not set it.
`lines[].returnedQuantity`	decimal	no	How much of the line has come back on a sales return.
`lines[].openReturnQuantity`	decimal	no	How much of the line may still be returned.
`lines[].unitPrice`	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`	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"`.
`lines[].notes`	string	no	Free text on the line.
`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.
`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`	date	no	The expiration date of the batch. Format YYYY-MM-DD.
`lines[].batches[].quantity`	decimal	yes	The quantity of this batch going out, in the item's inventory unit.
`lines[].batches[].inventoryQuantity`	decimal	no	The same quantity in the item's stocking unit.
`lines[].batches[].returnedQuantity`	decimal	no	How much of this batch has come back on a sales return.
`lines[].batches[].unitCost`	decimal	no	The cost of one unit of this batch at shipment, in the shipment's currency.
`lines[].serials`	array<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`	decimal	no	How much of this unit has come back on a sales return.
`lines[].serials[].unitCost`	decimal	no	The cost of this unit at shipment, in the shipment's currency.
`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.
`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`	decimal	yes	The quantity taken from this bin, in the item's inventory unit.
`lines[].binLocations[].inventoryQuantity`	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.

{
  "data": {
    "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": "3SABCD7654321",
    "referenceNumber": "PO-BAKKER-4417",
    "returnStatus": "OPEN",
    "currency": "EUR",
    "totalAmount": "864.00",
    "notes": "Palletised",
    "createdDate": "2026-08-14T08:30:00.000Z",
    "lastModifiedDate": "2026-08-14T09:05: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": "36.00",
        "inventoryQuantity": "36.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

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
`NOT_FOUND`	400
`WRONG_STATUS`	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

400 — Invalid request or business failure. Codes: NOT_FOUND, WRONG_STATUS, REFERENCE_NOT_FOUND, NO_LINES, SOURCE_LINE_NOT_PROJECTED, INVALID_QUANTITY, MIXED_LOCATIONS, DUPLICATE_TRACKING_NUMBER, UNKNOWN_TRACKING_REFERENCE, POSTING_REJECTED
401 — The request carries no valid 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 from this client address. The response has no body and no Retry-After header.
500 — Internal server error