Creates several inventory increases in one call, each as a draft.

POST /inventory/inventory-increases/bulk

Group: Inventory › Inventory Increases · Operation ID: bulkCreateInventoryIncreases

Creates several inventory increases in one call, each in DRAFT. All or nothing: every entry is validated before any is written, so a rejected entry leaves nothing behind. index on the error says which, counting from zero. Each entry is exactly what POST inventory/inventory-increases takes, and the results come back in input order.

Open in the interactive reference

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: bulkCreateInventoryIncreasesInput.

Field Type Required Description
increases array of object yes The inventory increases to create. At least one, and each is exactly what POST inventory/inventory-increases takes.
increases[].locationId string yes The unique identifier for the warehouse the stock is added to. One warehouse for the whole inventory increase, and every line is added to it. Required. See id on GET inventory/warehouses/:id.
increases[].entityId string no The unique identifier for the legal entity. Omit it to use the warehouse's owning entity. See id on GET base/entities.
increases[].documentDate string (date) no The date the inventory increase is dated. Defaults to today. It sets the posting period. Use format YYYY-MM-DD.
increases[].reasonCodeId string no The unique identifier for a reason code explaining the adjustment. See id on GET inventory/reason-codes/:id.
increases[].notes string no Free text on the inventory increase.
increases[].lines array of object yes The lines of the inventory increase. At least one is required.
increases[].lines[].itemId string yes The unique identifier for the item this line adds to stock. See id on GET inventory/items/:id.
increases[].lines[].unitId string yes The unique identifier for the unit the quantity is counted in. See id on GET inventory/unit-of-measures/:id.
increases[].lines[].quantity string (decimal) yes The quantity added, in that unit. Greater than zero.
increases[].lines[].unitPrice string (decimal) yes The value of one unit, in the inventory increase's currency. Greater than zero.
increases[].lines[].notes string no Free text on the line.
increases[].lines[].batches array of 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.
increases[].lines[].batches[].batchNumberId string no The unique identifier for an existing batch. Omit it and give batchNumber to receive a new lot, which creates the batch record when the number is new to the item.
increases[].lines[].batches[].batchNumber string no The batch number as printed. Required unless batchNumberId is given.
increases[].lines[].batches[].manufacturerBatchNumber string no The maker's own number for the batch.
increases[].lines[].batches[].expirationDate string (date) no The expiration date of the batch. Use format YYYY-MM-DD.
increases[].lines[].batches[].quantity string (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.
increases[].lines[].batches[].unitCost string (decimal) no The cost of one unit of this batch, in the inventory increase's currency. Defaults to the line's unitPrice.
increases[].lines[].serials array of object no The serialized units, one entry per unit. Required for a serialized item, and the count must equal the line's quantity.
increases[].lines[].serials[].serialNumberId string no The unique identifier for an existing serial record. Omit it and give serialNumber for a unit new to the system.
increases[].lines[].serials[].serialNumber string no The serial number stamped on the unit. Required unless serialNumberId is given.
increases[].lines[].serials[].manufacturerSerialNumber string no The maker's own number for the unit.
increases[].lines[].serials[].unitCost string (decimal) no The cost of this unit, in the inventory increase's currency. Defaults to the line's unitPrice.
increases[].lines[].binLocations array of 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.
increases[].lines[].binLocations[].binLocationId string yes The unique identifier for the bin the quantity lands in. See id on GET inventory/bins/:id.
increases[].lines[].binLocations[].quantity string (decimal) yes The quantity landing in this bin, in the line's unit.
increases[].lines[].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.
increases[].lines[].binLocations[].serialNumber string no Names one of this line's serialized units, when the bin entry belongs to it.

Example:

{
  "increases": [
    {
      "locationId": "e1d84c07-5b39-4a26-9f70-2c8b613ad495",
      "documentDate": "2026-08-14",
      "reasonCodeId": "6f2b58c1-9d47-4e03-a815-70c9d2e46b38",
      "notes": "August cycle count",
      "lines": [
        {
          "itemId": "5f21c8b0-9d34-4a76-8e12-04b93c7de5a8",
          "unitId": "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45",
          "quantity": "120.00",
          "unitPrice": "3.75",
          "notes": "Found during the August count",
          "batches": [
            {
              "batchNumber": "LOT-2026-08-14",
              "expirationDate": "2027-08-14",
              "quantity": "120.00"
            }
          ],
          "binLocations": [
            {
              "binLocationId": "0c7e91d3-4a58-4b26-9e10-63f8a2c5d704",
              "quantity": "120.00",
              "batchNumber": "LOT-2026-08-14"
            }
          ]
        }
      ]
    }
  ]
}

Response

200 Success

Under data (bulkCreateInventoryIncreasesOutput):

Field Type Required Description
items array of object yes The created inventory increases, in input order. Match them to inputs by position.
items[].id string yes The unique identifier for the inventory increase.
items[].documentNumber string no The inventory increase's document number, for example 'INC-42'. Absent while none has been assigned.
items[].documentStatus string yes The status of the inventory increase. Possible values: 'DRAFT', 'COMMITTED', 'CANCELLED'.
items[].documentDate string (date) yes The date the inventory increase is dated. It sets the posting period. Format YYYY-MM-DD.
items[].entityId string yes The unique identifier for the legal entity the inventory increase belongs to. See id on GET base/entities.
items[].entityName string no The display name of that legal entity.
items[].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.
items[].locationCode string no The short code of that warehouse.
items[].locationName string no The display name of that warehouse.
items[].reasonCodeId string no The unique identifier for the reason code, when one was given. See id on GET inventory/reason-codes/:id.
items[].reasonCode string no The short code of that reason code.
items[].reasonCodeDescription string no The description of that reason code.
items[].currency string no The currency of every amount on the inventory increase. Format ISO 4217, for example 'EUR'.
items[].notes string no Free text on the inventory increase.
items[].createdDate string (date-time) no The date and time the inventory increase was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].lastModifiedDate string (date-time) no The date and time the inventory increase record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
items[].lines array of object yes The lines of the inventory increase. An inventory increase always has at least one.
items[].lines[].id string yes The unique identifier for the inventory increase line.
items[].lines[].itemId string yes The unique identifier for the item this line adds to stock. 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[].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, for example 'BOX'.
items[].lines[].quantity string (decimal) yes The quantity added, in the line's unit.
items[].lines[].inventoryQuantity string (decimal) no The same quantity in the item's stocking unit.
items[].lines[].unitPrice string (decimal) no The value of one unit, in the inventory increase's currency.
items[].lines[].notes string no Free text on the line.
items[].lines[].batches array of object no The batches making up this line's quantity, 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 this entry created or matched.
items[].lines[].batches[].batchNumber string yes The batch number as printed, for example 'LOT-2026-08-14'.
items[].lines[].batches[].manufacturerBatchNumber string no The maker's own number for the same batch, when one was recorded.
items[].lines[].batches[].expirationDate string (date) no The expiration date of the batch. Format YYYY-MM-DD.
items[].lines[].batches[].quantity string (decimal) yes The quantity of this batch on the line, in the line's unit.
items[].lines[].batches[].inventoryQuantity string (decimal) no The same quantity in the item's stocking unit.
items[].lines[].batches[].unitCost string (decimal) no The cost of one unit of this batch, in the inventory increase's currency.
items[].lines[].serials array of object no The serialized units making up this line's quantity, one entry per unit. Absent when the item is not serialized.
items[].lines[].serials[].serialNumberId string no The unique identifier for the serial record this entry created or matched.
items[].lines[].serials[].serialNumber string yes The serial number stamped on the unit.
items[].lines[].serials[].manufacturerSerialNumber string no The maker's own number for the same unit, when one was recorded.
items[].lines[].serials[].unitCost string (decimal) no The cost of this unit, in the inventory increase's currency.
items[].lines[].binLocations array of 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.
items[].lines[].binLocations[].binLocationId string yes The unique identifier for the bin the quantity landed in. See id on GET inventory/bins/:id.
items[].lines[].binLocations[].binLocationCode string no The short code of that bin.
items[].lines[].binLocations[].quantity string (decimal) yes The quantity landing in this bin, in the line's unit.
items[].lines[].binLocations[].inventoryQuantity string (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.

Response headers

Errors

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