iotoms Docs

Create an item

POST
/api/v1/catalog/items

Creates a catalog item with its code, name, prices and links to department, category, brand, tax and other attributes. Returns 201 with the created item.

How to use it

  1. Look up the IDs to link (department, category, subcategory, brand, size, colour, style, tax, discount, image, base unit) from their list endpoints.
  2. Send a unique itemId, productId, itemName, sellingPrice, costPrice and type; any linked ID that does not exist is rejected as not found.
  3. The item is created (HTTP 201) and returned directly, without the status/message envelope. A baseUomId also becomes the item's base unit of measure.

Authorization

BearerAuth
headerAuthorizationBearer <JWT>

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 POST 'https://beta.iotoms.com/api/v1/catalog/items' \  -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"}