Update an inventory increase

Operation ID: updateInventoryIncrease

Group: Inventory › Inventory Increases

PATCH /inventory/inventory-increases/{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 an inventory increase with the fields you send. A field you leave out keeps its current value. Lines change through three separate arrays: deleteLines, updateLines, and createLines. You can send any combination in one request.

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 entry the line should keep.

Leave all three out to keep the line's tracking as it is.

Only a draft can be changed. You can change its date, reason code, notes, and lines. The response is the whole updated document.

The warehouse can't be changed. To use another warehouse, delete the draft and create a new inventory increase.

One request can remove a line and add its replacement.

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 inventory increase you want to update.

Request body

Required, application/json: updateInventoryIncreaseInput.

Field	Type	Required	Description
`documentDate`	date	no	A new document date. It sets the posting period. Use format YYYY-MM-DD.
`reasonCodeId`	string	no	A new reason code. See id on GET inventory/reason-codes/:id.
`notes`	string	no	New free text. Pass an empty string to clear it. Example: `"August cycle count, recounted"`.
`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":"9b3f5a10-7c24-4e68-8d05-1f6a92b4c837","quantity":"150.00","batches":[{"batchNumber":"LOT-2026-08-14","expirationDate":"2027-08-14","quantity":"150.00"}],"binLocations":[{"binLocationId":"0c7e91d3-4a58-4b26-9e10-63f8a2c5d704","quantity":"150.00","batchNumber":"LOT-2026-08-14"}]}]`.
`updateLines[].id`	string	yes	The unique identifier for the line to change. A line belonging to another inventory increase is rejected, not skipped.
`updateLines[].itemId`	string	no	A new item for the line. See id on GET inventory/items/:id.
`updateLines[].unitId`	string	no	A new unit for the line's quantity. See id on GET inventory/unit-of-measures/:id.
`updateLines[].quantity`	decimal	no	A new quantity, in the line's unit. Greater than zero when given.
`updateLines[].unitPrice`	decimal	no	A new unit value, in the inventory increase's currency. Greater than zero when given. On a line valued by lineValue, a price equal to the one calculated from it (lineValue divided by the quantity as it will be stored after this update, at the currency's precision) changes nothing and the line keeps its lineValue; any other price becomes the line's valuation source and lineValue is cleared.
`updateLines[].notes`	string	no	New free text. Pass an empty string to clear it.
`updateLines[].batches`	array<object>	no	The batches making up this line's quantity. Required for a batch-tracked item, and the quantities must add up to the line's quantity. Sending this array replaces the line's batches.
`updateLines[].batches[].batchNumberId`	string	no	The unique identifier of the batch, when it already exists. Optional: the number decides the lot. Given, it must be the batch batchNumber names for the item in this warehouse.
`updateLines[].batches[].batchNumber`	string	no	The batch number as printed. Required. It names the lot within the item and the warehouse, and a number new to both creates the batch record.
`updateLines[].batches[].manufacturerBatchNumber`	string	no	The maker's own number for the batch.
`updateLines[].batches[].expirationDate`	date	no	The expiration date of the batch. Use format YYYY-MM-DD.
`updateLines[].batches[].quantity`	decimal	yes	The quantity of this batch, in the line's unit. The batch quantities of a line must add up to the line's quantity.
`updateLines[].batches[].unitCost`	decimal	no	The cost of one unit of this batch, in the inventory increase's currency. Defaults to the line's unitPrice.
`updateLines[].serials`	array<object>	no	The serialized units, one entry per unit. Required for a serialized item, and the count must equal the line's quantity. Sending this array replaces the line's serials.
`updateLines[].serials[].serialNumberId`	string	no	The unique identifier of the unit, when it already exists. Optional: the number decides the unit. Given, it must be the unit serialNumber names for the item in this warehouse.
`updateLines[].serials[].serialNumber`	string	no	The serial number stamped on the unit. Required. It names the unit within the item and the warehouse, and a number new to both creates the serial record.
`updateLines[].serials[].manufacturerSerialNumber`	string	no	The maker's own number for the unit.
`updateLines[].serials[].unitCost`	decimal	no	The cost of this unit, in the inventory increase's currency. Defaults to the line's unitPrice.
`updateLines[].binLocations`	array<object>	no	The bins the quantity lands in, in a bin-tracked warehouse. An entry may name a batchNumber or serialNumber of its own line. Sending this array replaces the line's bin entries.
`updateLines[].binLocations[].binLocationId`	string	yes	The unique identifier for the bin the quantity lands in. See id on GET inventory/bins/:id.
`updateLines[].binLocations[].quantity`	decimal	yes	The quantity landing in this bin, in the line's unit.
`updateLines[].binLocations[].batchNumber`	string	no	Names one of this line's batches, when the bin entry belongs to it. A number not on the line is rejected.
`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. They land at the inventory increase's existing warehouse. A document with no lines cannot take new ones.
`createLines[].itemId`	string	yes	The unique identifier for the item this line adds to stock. See id on GET inventory/items/: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 added, in that unit. Greater than zero.
`createLines[].unitPrice`	decimal	yes	The value of one unit, in the inventory increase's currency. Greater than zero.
`createLines[].notes`	string	no	Free text on the line.
`createLines[].batches`	array<object>	no	The batches making up this line's quantity. Required for a batch-tracked item, and the quantities must add up to the line's quantity.
`createLines[].batches[].batchNumberId`	string	no	The unique identifier of the batch, when it already exists. Optional: the number decides the lot. Given, it must be the batch batchNumber names for the item in this warehouse.
`createLines[].batches[].batchNumber`	string	no	The batch number as printed. Required. It names the lot within the item and the warehouse, and a number new to both creates the batch record.
`createLines[].batches[].manufacturerBatchNumber`	string	no	The maker's own number for the batch.
`createLines[].batches[].expirationDate`	date	no	The expiration date of the batch. Use format YYYY-MM-DD.
`createLines[].batches[].quantity`	decimal	yes	The quantity of this batch, in the line's unit. The batch quantities of a line must add up to the line's quantity.
`createLines[].batches[].unitCost`	decimal	no	The cost of one unit of this batch, in the inventory increase's currency. Defaults to the line's unitPrice.
`createLines[].serials`	array<object>	no	The serialized units, 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 of the unit, when it already exists. Optional: the number decides the unit. Given, it must be the unit serialNumber names for the item in this warehouse.
`createLines[].serials[].serialNumber`	string	no	The serial number stamped on the unit. Required. It names the unit within the item and the warehouse, and a number new to both creates the serial record.
`createLines[].serials[].manufacturerSerialNumber`	string	no	The maker's own number for the unit.
`createLines[].serials[].unitCost`	decimal	no	The cost of this unit, in the inventory increase's currency. Defaults to the line's unitPrice.
`createLines[].binLocations`	array<object>	no	The bins the quantity lands in, 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 the quantity lands in. See id on GET inventory/bins/:id.
`createLines[].binLocations[].quantity`	decimal	yes	The quantity landing in this bin, in the line's unit.
`createLines[].binLocations[].batchNumber`	string	no	Names one of this line's batches, when the bin entry belongs to it. A number not on the line is rejected.
`createLines[].binLocations[].serialNumber`	string	no	Names one of this line's serialized units, when the bin entry belongs to it.

{
  "documentDate": "2026-01-15",
  "reasonCodeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "notes": "August cycle count, recounted",
  "deleteLines": [
    "<deleteLines>"
  ],
  "updateLines": [
    {
      "id": "9b3f5a10-7c24-4e68-8d05-1f6a92b4c837",
      "quantity": "150.00",
      "batches": [
        {
          "batchNumber": "LOT-2026-08-14",
          "expirationDate": "2027-08-14",
          "quantity": "150.00"
        }
      ],
      "binLocations": [
        {
          "binLocationId": "0c7e91d3-4a58-4b26-9e10-63f8a2c5d704",
          "quantity": "150.00",
          "batchNumber": "LOT-2026-08-14"
        }
      ]
    }
  ],
  "createLines": [
    {
      "itemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "unitId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "quantity": "19.99",
      "unitPrice": "19.99",
      "notes": "<notes>",
      "batches": [
        {
          "batchNumberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "batchNumber": "<batchNumber>",
          "manufacturerBatchNumber": "<manufacturerBatchNumber>",
          "expirationDate": "2026-01-15",
          "quantity": "19.99",
          "unitCost": "19.99"
        }
      ],
      "serials": [
        {
          "serialNumberId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "serialNumber": "<serialNumber>",
          "manufacturerSerialNumber": "<manufacturerSerialNumber>",
          "unitCost": "19.99"
        }
      ],
      "binLocations": [
        {
          "binLocationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "quantity": "19.99",
          "batchNumber": "<batchNumber>",
          "serialNumber": "<serialNumber>"
        }
      ]
    }
  ]
}

Response

200 Success

Under data (updateInventoryIncreaseOutput):

Field	Type	Required	Description
`id`	string	yes	The unique identifier for the inventory increase. Example: `"d4a17f28-6b93-4c50-8e71-2a5d0c9b3e64"`.
`documentNumber`	string	no	The inventory increase's document number, for example 'INC-42'. Absent while none has been assigned. Example: `"INC-42"`.
`documentStatus`	string	yes	The status of the inventory increase. Possible values: 'DRAFT', 'COMMITTED', 'CANCELLED'. Example: `"DRAFT"`.
`documentDate`	date	yes	The date the inventory increase is dated. It sets the posting period. Format YYYY-MM-DD. Example: `"2026-08-14"`.
`entityId`	string	yes	The unique identifier for the legal entity the inventory increase 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."`.
`locationId`	string	no	The unique identifier for the warehouse the stock is added to. One warehouse for the whole inventory increase. Absent only on a document with no lines. See id on GET inventory/warehouses/:id. Example: `"e1d84c07-5b39-4a26-9f70-2c8b613ad495"`.
`locationCode`	string	no	The short code of that warehouse. Example: `"WH-01"`.
`locationName`	string	no	The display name of that warehouse. Example: `"Rotterdam Distribution Centre"`.
`reasonCodeId`	string	no	The unique identifier for the reason code, when one was given. See id on GET inventory/reason-codes/:id. Example: `"6f2b58c1-9d47-4e03-a815-70c9d2e46b38"`.
`reasonCode`	string	no	The short code of that reason code. Example: `"COUNT"`.
`reasonCodeDescription`	string	no	The description of that reason code. Example: `"Count correction"`.
`currency`	string	no	The currency of every amount on the inventory increase. Format ISO 4217, for example 'EUR'. Example: `"EUR"`.
`notes`	string	no	Free text on the inventory increase. Example: `"August cycle count, recounted"`.
`createdDate`	date-time	no	The date and time the inventory increase was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. Example: `"2026-08-14T09:12:00.000Z"`.
`lastModifiedDate`	date-time	no	The date and time the inventory increase record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ. Example: `"2026-08-14T09:40:00.000Z"`.
`lines`	array<object>	yes	The lines of the inventory increase. An inventory increase always has at least one. Example: [{"id":"9b3f5a10-7c24-4e68-8d05-1f6a92b4c837","itemId":"5f21c8b0-9d34-4a76-8e12-04b93c7de5a8","itemCode":"WIDGET-01","itemName":"Standard widget","unitId":"3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45","unitCode":"EA","quantity":"150.00","inventoryQuantity":"150.00","unitPrice":"3.75","notes":"Found during the August count","batches":[{"batchNumberId":"9c31f5a8-6b02-4e79-b354-8d1a67e0f2b9","batchNumber":"LOT-2026-08-14","expirationDate":"2027-08-14","quantity":"150.00","inventoryQuantity":"150.00","unitCost":"3.75"}],"binLocations":[{"binLocationId":"0c7e91d3-4a58-4b26-9e10-63f8a2c5d704","binLocationCode":"A-01-02","quantity":"150.00","inventoryQuantity":"150.00","batchNumber":"LOT-2026-08-14"}]}].
`lines[].id`	string	yes	The unique identifier for the inventory increase line.
`lines[].itemId`	string	yes	The unique identifier for the item this line adds to stock. 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[].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, for example 'BOX'.
`lines[].quantity`	decimal	yes	The quantity added, in the line's unit.
`lines[].inventoryQuantity`	decimal	no	The same quantity in the item's stocking unit.
`lines[].unitPrice`	decimal	no	The value of one unit, in the inventory increase's currency.
`lines[].lineValue`	decimal	no	The total value of the line, in the inventory increase's currency, when the line was valued as a whole rather than per unit. When present it is what the line is worth, and unitPrice is calculated from it as lineValue divided by quantity. Absent on a line valued by unitPrice.
`lines[].notes`	string	no	Free text on the line.
`lines[].batches`	array<object>	no	The batches making up this line's quantity, 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 this entry created or matched.
`lines[].batches[].batchNumber`	string	yes	The batch number as printed, for example 'LOT-2026-08-14'.
`lines[].batches[].manufacturerBatchNumber`	string	no	The maker's own number for the same batch, when one was recorded.
`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 on the line, in the line's unit.
`lines[].batches[].inventoryQuantity`	decimal	no	The same quantity in the item's stocking unit.
`lines[].batches[].unitCost`	decimal	no	The cost of one unit of this batch, in the inventory increase's currency.
`lines[].serials`	array<object>	no	The serialized units making up this line's quantity, one entry per unit. Absent when the item is not serialized.
`lines[].serials[].serialNumberId`	string	no	The unique identifier for the serial record this entry created or matched.
`lines[].serials[].serialNumber`	string	yes	The serial number stamped on the unit.
`lines[].serials[].manufacturerSerialNumber`	string	no	The maker's own number for the same unit, when one was recorded.
`lines[].serials[].unitCost`	decimal	no	The cost of this unit, in the inventory increase's currency.
`lines[].binLocations`	array<object>	no	The bins the quantity lands in, 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 quantity landed in. 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 landing in this bin, in the line's 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": "d4a17f28-6b93-4c50-8e71-2a5d0c9b3e64",
    "documentNumber": "INC-42",
    "documentStatus": "DRAFT",
    "documentDate": "2026-08-14",
    "entityId": "1a9c4e70-38b5-4d26-9f01-7c2e5b8a6d43",
    "entityName": "Acme Netherlands B.V.",
    "locationId": "e1d84c07-5b39-4a26-9f70-2c8b613ad495",
    "locationCode": "WH-01",
    "locationName": "Rotterdam Distribution Centre",
    "reasonCodeId": "6f2b58c1-9d47-4e03-a815-70c9d2e46b38",
    "reasonCode": "COUNT",
    "reasonCodeDescription": "Count correction",
    "currency": "EUR",
    "notes": "August cycle count, recounted",
    "createdDate": "2026-08-14T09:12:00.000Z",
    "lastModifiedDate": "2026-08-14T09:40:00.000Z",
    "lines": [
      {
        "id": "9b3f5a10-7c24-4e68-8d05-1f6a92b4c837",
        "itemId": "5f21c8b0-9d34-4a76-8e12-04b93c7de5a8",
        "itemCode": "WIDGET-01",
        "itemName": "Standard widget",
        "unitId": "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45",
        "unitCode": "EA",
        "quantity": "150.00",
        "inventoryQuantity": "150.00",
        "unitPrice": "3.75",
        "notes": "Found during the August count",
        "batches": [
          {
            "batchNumberId": "9c31f5a8-6b02-4e79-b354-8d1a67e0f2b9",
            "batchNumber": "LOT-2026-08-14",
            "expirationDate": "2027-08-14",
            "quantity": "150.00",
            "inventoryQuantity": "150.00",
            "unitCost": "3.75"
          }
        ],
        "binLocations": [
          {
            "binLocationId": "0c7e91d3-4a58-4b26-9e10-63f8a2c5d704",
            "binLocationCode": "A-01-02",
            "quantity": "150.00",
            "inventoryQuantity": "150.00",
            "batchNumber": "LOT-2026-08-14"
          }
        ]
      }
    ]
  },
  "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
`INVALID_QUANTITY`	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, INVALID_QUANTITY, 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