iotoms Docs

Replace an item

PUT
/api/v1/catalog/items/{itemId}

Replaces all fields of the item identified by itemId with the request body; optional fields left out are cleared, a missing status becomes ACTIVE, and the base unit is kept when omitted. Linked IDs must exist. Returns the item directly. A changed selling price is logged in the price change audit trail.

How to use it

  1. Read the current item with Get an item and look up attribute IDs (department, category, brand, tax...) from their list endpoints.
  2. Send the full item: optional fields you leave out are cleared, status left out becomes ACTIVE, and baseUomId keeps its current value when omitted.
  3. A changed sellingPrice is recorded in the price change audit trail. The item code itself cannot be changed.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

Path Parameters

itemId*string

Item code (itemId) of the item, e.g. from List items.

Request Body

application/json
  1. body
id?|

Internal numeric ID. Set by the server; ignored on create and update.

Formatint64
itemId*string

Item code: your unique identifier for the item. Required, not blank. On update the code in the URL wins; it cannot be changed.

upc?|

Barcode (UPC/EAN) of the item. Optional.

productId*string

Product identifier the item belongs to. Required, not blank.

itemName*string

Display name of the item. Required, not blank.

sellingPrice*number

Selling price per base unit, in the merchant's currency. Treated as 0 if omitted, so always send it. Changing it is recorded in the price change audit trail.

Formatdouble
costPrice*number

Cost price per base unit, in the merchant's currency. Required.

Formatdouble
departmentId?|

ID from List departments. Optional; an unknown ID is rejected as not found.

Formatint64
categoryId?|

ID from List categories. Optional; an unknown ID is rejected as not found.

Formatint64
subcategoryId?|

ID from List subcategories. Optional; an unknown ID is rejected as not found.

Formatint64
description?|

Free-text description, up to 255 characters.

Length0 <= length <= 255
imageGalleryId?|

ID from List gallery images to use as the item's image. Optional.

Formatint64
styleId?|

ID from List styles. Optional.

Formatint64
sizeId?|

ID from List sizes. Optional.

Formatint64
colorId?|

ID from List colors. Optional.

Formatint64
brandId?|

ID from List brands. Optional.

Formatint64
season?|

Season label, up to 100 characters. Optional.

Length0 <= length <= 100
type*string

STORE_ITEM for a normal sellable item, MODIFIER_ITEM for an add-on/modifier sold with another item. Required.

Value in"MODIFIER_ITEM""STORE_ITEM"
taxId?|

ID from List taxes for the tax to charge on this item. Optional.

Formatint64
discountId?|

ID from List discounts to link to this item. Optional.

Formatint64
status*string

Item status: ACTIVE (sellable), INACTIVE, ARCHIVED or DELETED. Defaults to ACTIVE, also on Replace an item when left out.

Value in"ACTIVE""INACTIVE""ARCHIVED""DELETED"
baseUomId?|

ID of the base (stocking) unit from List units of measure. On update, omit it to keep the current base unit.

Formatuuid
modifiedTime*string

Last-changed timestamp. Set by the server; ignored on input.

Formatdate-time

Response Body

OK

*/*
  1. response
id?|

Internal numeric ID. Set by the server; other endpoints identify items by itemId instead.

Formatint64
itemId*string

Item code: your unique identifier for the item, used in URLs and by other endpoints. Cannot be changed after creation.

upc?|

Barcode (UPC/EAN) of the item, if any.

productId*string

Product identifier the item belongs to, e.g. a parent product code shared by variants.

itemName?|

Display name of the item.

sellingPrice*number

Selling price per base unit, in the merchant's currency.

Formatdouble
costPrice*number

Cost price per base unit, in the merchant's currency.

Formatdouble
department?

The item's department (id, name), or null.

category?

The item's category, or null.

subcategory?

The item's subcategory (id, name), or null.

description?|

Free-text description of the item.

imageGallery?

The gallery image linked to the item, or null.

style?

The item's style (id, name), or null.

size?

The item's size (id, name, status), or null.

color?

The item's colour, or null.

brand?

The item's brand, or null.

season?|

Season label, e.g. a collection name. Free text up to 100 characters.

type*string

STORE_ITEM for a normal sellable item, MODIFIER_ITEM for an add-on/modifier sold with another item.

Value in"MODIFIER_ITEM""STORE_ITEM"
tax?

The tax applied to the item (name and rates), or null.

discount?

The discount linked to the item, or null.

status*string

Item status: ACTIVE (sellable), INACTIVE, ARCHIVED or DELETED. Defaults to ACTIVE.

Value in"ACTIVE""INACTIVE""ARCHIVED""DELETED"
modifiedTime*string

Time stored when the item was created (ISO 8601 timestamp). Replace an item and Update selected item fields do not refresh this time, so later edits are not reflected in it.

Formatdate-time
itemType*string

Manufacturing role: RAW_MATERIAL, SEMI_FINISHED, FINISHED_GOOD (default), CONSUMABLE or TRADING.

unitCost?|

Unit cost in the merchant's currency; for manufactured items it is recalculated from component costs when a production order completes.

baseUomId?|

ID of the item's base (stocking) unit of measure; see List units of measure.

Formatuuid
catchWeight*boolean

True for a variable-weight item: stock is measured by actual net weight at receipt. Its base unit must be a weight unit.

hsnCode?|

India GST: HSN classification code of the item (up to 8 characters).

gstRatePercent?|

India GST: total GST rate as a percentage.

igstRatePercent?|

India GST: IGST rate (inter-state sales) as a percentage.

cgstRatePercent?|

India GST: CGST rate (intra-state sales) as a percentage.

sgstRatePercent?|

India GST: SGST rate (intra-state sales) as a percentage.

commodityCode?|

EU Intrastat: commodity code of the item (up to 8 characters).

netMassKg?|

EU Intrastat: net mass of one unit in kilograms.

countryOfOrigin?|

EU Intrastat: two-letter ISO country code where the item was produced.

Example Request
curl -X PUT 'https://beta.iotoms.com/api/v1/catalog/items/string' \  -H 'Content-Type: application/json' \  -d '{  "itemId": "string",  "productId": "string",  "itemName": "string",  "sellingPrice": 0.1,  "costPrice": 0.1,  "type": "MODIFIER_ITEM",  "status": "ACTIVE",  "modifiedTime": "2019-08-24T14:15:22Z"}'
Example Response
{  "id": 0,  "itemId": "string",  "upc": "string",  "productId": "string",  "itemName": "string",  "sellingPrice": 0.1,  "costPrice": 0.1,  "department": {    "id": 0,    "name": "string",    "modifiedTime": "2019-08-24T14:15:22Z"  },  "category": {    "id": 0,    "name": "string",    "modifiedTime": "2019-08-24T14:15:22Z"  },  "subcategory": {    "id": 0,    "name": "string",    "modifiedTime": "2019-08-24T14:15:22Z"  },  "description": "string",  "imageGallery": {    "id": 0,    "imageUrl": "string",    "modifiedTime": "2019-08-24T14:15:22Z"  },  "style": {    "id": 0,    "name": "string",    "modifiedTime": "2019-08-24T14:15:22Z"  },  "size": {    "id": 0,    "name": "string",    "status": "string",    "modifiedTime": "2019-08-24T14:15:22Z"  },  "color": {    "id": 0,    "name": "string",    "status": "string",    "modifiedTime": "2019-08-24T14:15:22Z"  },  "brand": {    "id": 0,    "name": "string",    "modifiedTime": "2019-08-24T14:15:22Z"  },  "season": "string",  "type": "MODIFIER_ITEM",  "tax": {    "id": 0,    "name": "string",    "taxRate1": 0,    "taxRate2": 0,    "modifiedTime": "2019-08-24T14:15:22Z",    "status": "string"  },  "discount": {    "id": 0,    "name": "string",    "discountType": 0,    "rate": 0,    "modifiedTime": "2019-08-24T14:15:22Z",    "status": "string",    "buyQuantity": 0,    "getQuantity": 0,    "getDiscountPercent": 0,    "tierMinQuantity": 0  },  "status": "ACTIVE",  "modifiedTime": "2019-08-24T14:15:22Z",  "itemType": "string",  "unitCost": 0,  "baseUomId": "0c43b7c4-22c4-4b37-9c1a-485778bd5b04",  "catchWeight": true,  "hsnCode": "string",  "gstRatePercent": 0,  "igstRatePercent": 0,  "cgstRatePercent": 0,  "sgstRatePercent": 0,  "commodityCode": "string",  "netMassKg": 0,  "countryOfOrigin": "string"}