Update an item

Operation ID: updateItem

Group: Inventory › Items

Open in the interactive reference

PATCH /inventory/items/{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 item with the fields you send. A field you leave out keeps its current value.

itemCode and itemTypeId are not accepted, so the item code and item type can't change.

Setting active to false retires the item. Retiring is refused while the item still has a quantity in stock, in transit, allocated, reserved, on quality hold, or damaged. Retiring is also refused while the item is on a purchase order or warehouse transfer order still awaiting receipt.

A retired item is refused on every inventory document, corrections and cancellations included. Setting active back to true is never refused.

The response contains only the id. Read the updated item with GET inventory/items/:id.

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

Request body

Required, application/json: updateItemInput.

Field Type Required Description
itemName string no The display name of the item.
categoryId string no The unique identifier of the item's category. See id on GET inventory/item-categories/:id.
inventoryUnitId string no The unique identifier of the unit stock is counted in. Every quantity on an inventory level or transaction will be in this unit. It must be one of the units in unitGroupId. See id on GET inventory/unit-of-measures/:id.
unitGroupId string no The unique identifier of the unit of measure group that has the conversions between the item's units. Moving the item to another group re-checks the units it keeps as well as any sent here, because their conversions live in the group, and a unit with no conversion fails with UNIT_NOT_IN_UNIT_GROUP. See id on GET inventory/unit-of-measure-groups/:id.
salesUnitId string no The unique identifier of the unit used on sales documents. It must be one of the units in unitGroupId. See id on GET inventory/unit-of-measures/:id.
purchaseUnitId string no The unique identifier of the unit used on purchase documents. It must be one of the units in unitGroupId. See id on GET inventory/unit-of-measures/:id.
valuationMethod string no How the item's stock is valued. Accepted values: 'movingAverage', 'batch', 'serials', 'none'. Use 'none' for an item that is not stocked. 'batch' requires isBatch, 'serials' requires isSerial, and 'none' requires isInventory false, and each contradiction fails with TRACKING_MISMATCH. Changing it is checked against the tracking flags the item already has, not only the ones in this request. 'fifo' is under development and fails with VALUATION_METHOD_UNAVAILABLE.
isBatch boolean no Whether the item is tracked by batch.
isSerial boolean no Whether the item is tracked by serial number.
isInventory boolean no Whether stock levels are kept for the item. Set false for a service or charge item.
isSalesItem boolean no Whether the item can appear on sales documents.
isPurchaseItem boolean no Whether the item can appear on purchase documents.
active boolean no Whether the item can be selected on new documents. Setting it false retires the item without deleting it.
notes string no Free text on the item.
externalItemId string no Your own identifier for this item in an external system.
brandName string no The display name of the brand.
imageAvatar string no The URL of the item's avatar image.
eccnNumber string no The Export Control Classification Number.
htsCode string no The Harmonized Tariff Schedule code.
countryOfOrigin string no The country the item originates from.
minStockLevel decimal no The stock level below which the item should be reordered, in the inventory unit.
minimumTransactionQuantity decimal no The smallest quantity any document can move. Omit for no restriction. Omitting it is not the same as sending 1.
leadTime decimal no The number of weeks between ordering the item and receiving it.
standardCost decimal no The standard cost carried for planning. State its currency in currency.
itemPurchasePrice decimal no The expected purchase price. State its currency in currency.
currency string no The currency of standardCost and itemPurchasePrice. Required when either is given. Format ISO 4217, for example 'USD'.
weight decimal no The weight of one item, in weightUnit. Set it if the item may be received under a landed cost that uses Weight allocation, because that mode fails rather than falling back when an item has no weight. Example: "1.6".
weightUnit string no The unit weight is expressed in. Accepted values: 'G', 'Kg', 'Lbs'. Example: "Kg".
grossWeight decimal no The weight including packaging, in weightUnit.
netWeight decimal no The weight excluding packaging, in weightUnit.
length decimal no The length of one item. A landed cost Volume allocation needs length, width and height together, and fails when the set is incomplete.
width decimal no The width of one item.
height decimal no The height of one item.
volumePerUnit decimal no The volume of one item, in volumeUnit.
volumeUnit string no The unit volumePerUnit is expressed in. Accepted values: 'L'.
defaultAllocationMode string no The allocation mode a landed cost charge billed as this item falls back to when it names none. Accepted values: 'Equal', 'Quantity', 'LineTotal', 'Weight', 'Volume'.
isPerishable boolean no Whether the item expires.
shelfLifeDays number no The number of days the item keeps from production.
minShelfLifeDaysOnReceipt number no The least remaining shelf life a receipt of this item will accept.
minShelfLifeDaysOnDispatch number no The least remaining shelf life a dispatch of this item will accept.
bestBeforeOffsetDays number no The number of days between the expiry date and the best-before date printed on it.
storageTempMin decimal no The lowest storage temperature, in degrees Celsius.
storageTempMax decimal no The highest storage temperature, in degrees Celsius. 
{
  "itemName": "<itemName>",
  "categoryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "inventoryUnitId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "unitGroupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "salesUnitId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "purchaseUnitId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "valuationMethod": "<valuationMethod>",
  "isBatch": true,
  "isSerial": true,
  "isInventory": true,
  "isSalesItem": true,
  "isPurchaseItem": true,
  "active": true,
  "notes": "<notes>",
  "externalItemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "brandName": "<brandName>",
  "imageAvatar": "<imageAvatar>",
  "eccnNumber": "<eccnNumber>",
  "htsCode": "<htsCode>",
  "countryOfOrigin": "<countryOfOrigin>",
  "minStockLevel": "19.99",
  "minimumTransactionQuantity": "19.99",
  "leadTime": "19.99",
  "standardCost": "19.99",
  "itemPurchasePrice": "19.99",
  "currency": "<currency>",
  "weight": "1.6",
  "weightUnit": "Kg",
  "grossWeight": "19.99",
  "netWeight": "19.99",
  "length": "19.99",
  "width": "19.99",
  "height": "19.99",
  "volumePerUnit": "19.99",
  "volumeUnit": "<volumeUnit>",
  "defaultAllocationMode": "<defaultAllocationMode>",
  "isPerishable": true,
  "shelfLifeDays": 0,
  "minShelfLifeDaysOnReceipt": 0,
  "minShelfLifeDaysOnDispatch": 0,
  "bestBeforeOffsetDays": 0,
  "storageTempMin": "19.99",
  "storageTempMax": "19.99"
}

Response

200 Success

Under data (updateItemOutput):

Field Type Required Description
id string yes The unique identifier for the item. Example: "517a93e4-cbb4-4571-9e3d-2343e56cfd84". 
{
  "data": {
    "id": "517a93e4-cbb4-4571-9e3d-2343e56cfd84"
  },
  "diagnostics": [
    {
      "code": "<code>",
      "message": "<message>",
      "severity": "error",
      "path": [
        "<path>"
      ],
      "details": "<details>"
    }
  ]
}

Response headers

Errors

Code Status
NOT_FOUND 400
REFERENCE_NOT_FOUND 400
DUPLICATE_CODE 400
UNKNOWN_VALUE 400
TRACKING_MISMATCH 400
ITEM_TYPE_NOT_STOCKABLE 400
VALUATION_METHOD_UNAVAILABLE 400
UNIT_NOT_IN_UNIT_GROUP 400
IDEMPOTENCY_KEY_CONFLICT 409
IDEMPOTENCY_PAYLOAD_MISMATCH 422

Statuses