Create Inventory Decrease

POST /inventory/inventory-decreases

Group: Inventory › Inventory Decreases · Operation ID: createInventoryDecrease

Creates an inventory decrease as a draft. It moves no stock until you commit it.

This creates a draft and posts nothing. No stock moves and no journal entry is written until you commit it with POST inventory/inventory-decreases/:id/commit, so you can build the document and check it before it posts. The response is the created document, in the same shape GET inventory/inventory-decreases/:id returns.

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

Field	Type	Required	Description
`locationId`	string	yes	The unique identifier for the warehouse location. One location for the whole document, and every line comes out of it. Required. See id on GET inventory/warehouses/:id.
`entityId`	string	no	The unique identifier for the legal entity. Omit it to use the location's owning entity. See id on GET base/entities.
`documentDate`	string (date)	no	The date the adjustment is dated. It drives the posting period. Defaults to today. Use format YYYY-MM-DD.
`reasonCodeId`	string	no	The unique identifier for a reason code explaining the adjustment. See id on GET inventory/reason-codes/:id.
`notes`	string	no	Free text on the inventory decrease.
`lines`	array of object	yes	The lines of the inventory decrease. At least one is required.
`lines[].itemId`	string	yes	The unique identifier for the item whose stock this line removes. See id on GET inventory/items/: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 remove, in that unit. A positive number greater than zero.
`lines[].unitPrice`	string (decimal)	no	The value of one unit, in the inventory decrease's currency. Optional: omit it to value the stock at the cost it already has, which is what a write-off ordinarily wants. A supplied value must be greater than zero.
`lines[].notes`	string	no	Free text on the line.
`lines[].batches`	array of object	no	The batches to take the quantity from. Required for a batch-tracked item, and the quantities must add up to the line's quantity. Every batch named must already exist for the item, since a decrease removes lots and does not create them.
`lines[].batches[].batchNumberId`	string	no	The unique identifier for the batch being removed. Give this or batchNumber.
`lines[].batches[].batchNumber`	string	no	The batch number as printed, for example 'LOT-2026-08-14'. It is matched against the batches of this line's item, since the same number on another item is a different lot. Give this or batchNumberId.
`lines[].batches[].quantity`	string (decimal)	yes	The quantity of this batch to remove, 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 units to remove, one entry per unit. Required for a serialized item, and the count must equal the line's quantity. Every unit named must already exist.
`lines[].serials[].serialNumberId`	string	no	The unique identifier for the unit being removed. Give this or serialNumber.
`lines[].serials[].serialNumber`	string	no	The serial number stamped on the unit, matched against the units of this line's item. Give this or serialNumberId.
`lines[].binLocations`	array of object	no	The bins the quantity comes 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 quantity 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. A number the line does not have is rejected rather than reinterpreted.
`lines[].binLocations[].serialNumber`	string	no	Names one of this line's serialized units, when the bin entry belongs to it.

Example:

{
  "locationId": "e1d84c07-5b39-4a26-9f70-2c8b613ad495",
  "entityId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "documentDate": "2026-08-14",
  "reasonCodeId": "6f2b58c1-9d47-4e03-a815-70c9d2e46b38",
  "notes": "Forklift damage, aisle 4",
  "lines": [
    {
      "itemId": "5f21c8b0-9d34-4a76-8e12-04b93c7de5a8",
      "unitId": "3b7d5e9c-1a24-4f80-9c6d-2e8f70b13a45",
      "quantity": "12.00",
      "notes": "Crushed by a forklift",
      "batches": [
        {
          "batchNumber": "LOT-2026-08-14",
          "quantity": "12.00"
        }
      ],
      "binLocations": [
        {
          "binLocationId": "0c7e91d3-4a58-4b26-9e10-63f8a2c5d704",
          "quantity": "12.00",
          "batchNumber": "LOT-2026-08-14"
        }
      ]
    }
  ]
}

Response

200 Success

Under data (createInventoryDecreaseOutput):

Field	Type	Required	Description
`id`	string	yes	The unique identifier for the inventory decrease.
`documentNumber`	string	no	The inventory decrease's document number, for example 'DEC-42'. Absent while none has been assigned.
`documentStatus`	string	yes	The status of the inventory decrease. Possible values: 'DRAFT', 'COMMITTED', 'CANCELLED'.
`documentDate`	string (date)	yes	The date the adjustment is dated. It drives the posting period, so it is not the same as when the record was created. Format YYYY-MM-DD.
`entityId`	string	yes	The unique identifier for the legal entity the document belongs to. See id on GET base/entities.
`entityName`	string	no	The display name of that legal entity.
`locationId`	string	no	The unique identifier for the warehouse location. One location for the whole document, and every line uses it. Absent only on a document with no lines. See id on GET inventory/warehouses/:id.
`locationCode`	string	no	The short code of that warehouse location.
`locationName`	string	no	The display name of that warehouse location.
`reasonCodeId`	string	no	The unique identifier for the reason code, when one was given. See id on GET inventory/reason-codes/:id.
`reasonCode`	string	no	The short code of that reason code.
`reasonCodeDescription`	string	no	The description of that reason code.
`currency`	string	no	The currency the inventory decrease is valued in, the legal entity's functional currency. Format ISO 4217, for example 'EUR'.
`notes`	string	no	Free text on the inventory decrease.
`createdDate`	string (date-time)	no	The date and time the inventory decrease was created, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
`lastModifiedDate`	string (date-time)	no	The date and time the inventory decrease record last changed, in UTC. Format YYYY-MM-DDTHH:mm:ss.sssZ.
`lines`	array of object	yes	The lines of the inventory decrease. An inventory decrease always has at least one.
`lines[].id`	string	yes	The unique identifier for the inventory decrease line.
`lines[].itemId`	string	yes	The unique identifier for the item whose stock this line removes. 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`	string (decimal)	yes	The quantity removed, in the line's unit. A positive number.
`lines[].inventoryQuantity`	string (decimal)	no	The same quantity in the item's stocking unit.
`lines[].unitPrice`	string (decimal)	no	The value of one unit, in the inventory decrease's currency, when one was recorded. Usually absent, since stock leaving is valued at the cost it already has.
`lines[].notes`	string	no	Free text on the line.
`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.
`lines[].batches[].batchNumberId`	string	no	The unique identifier for the batch record.
`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`	string (date)	no	The expiration date of the batch. Format YYYY-MM-DD.
`lines[].batches[].quantity`	string (decimal)	yes	The quantity of this batch removed by the line, in the line's unit.
`lines[].batches[].inventoryQuantity`	string (decimal)	no	The same quantity in the item's stocking unit.
`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.
`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[].manufacturerSerialNumber`	string	no	The maker's own number for the same unit, when one was recorded.
`lines[].binLocations`	array of object	no	The bins the quantity came 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 quantity came 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
`INVALID_QUANTITY`	400
`UNKNOWN_TRACKING_NUMBER`	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, INVALID_QUANTITY, UNKNOWN_TRACKING_NUMBER, 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