Item variants represent specific presentations of an item (e.g., 1kg bag, 5kg box). Each variant has its own unit of measure, pricing, and stock tracking.
List Item Variants curl -X GET "https://api.sushigo.com/api/v1/item-variants?item_id=1&per_page=20" \ -H "Authorization: Bearer YOUR_TOKEN"
Query Parameters Search by code or name (case-insensitive partial match)
Response Last purchase/production cost
Parent item details (id, sku, name, type)
Unit of measure details (id, code, name, symbol)
Example Response { "status" : 200 , "data" : [ { "id" : 1 , "item_id" : 1 , "uom_id" : 3 , "code" : "ARR-KG" , "name" : "Arroz Premium 1kg" , "description" : "Presentación de 1 kilogramo" , "track_lot" : false , "track_serial" : false , "last_unit_cost" : 28.50 , "avg_unit_cost" : 27.80 , "sale_price" : 35.00 , "min_stock" : 10.0 , "max_stock" : 100.0 , "is_active" : true , "item" : { "id" : 1 , "sku" : "INS-001" , "name" : "Arroz Sushi Premium" , "type" : "INSUMO" }, "uom" : { "id" : 3 , "code" : "KG" , "name" : "Kilogramo" , "symbol" : "kg" }, "created_at" : "2026-01-15T10:30:00+00:00" , "updated_at" : "2026-01-15T10:30:00+00:00" } ], "meta" : { "current_page" : 1 , "per_page" : 15 , "total" : 3 } }
Create Item Variant curl -X POST "https://api.sushigo.com/api/v1/item-variants" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "item_id": 1, "uom_id": 3, "code": "ARR-KG", "name": "Arroz Premium 1kg", "description": "Presentación de 1 kilogramo", "sale_price": 35.00, "min_stock": 10, "max_stock": 100, "track_lot": false, "is_active": true }'
Request Body Parent item ID (must exist)
Unique variant code (auto-uppercased, max 100 chars)
Variant name (max 255 chars)
Product barcode (EAN, UPC, Code128, etc.) - cleaned and uppercased automatically
Track individual serial numbers
Minimum stock level (≥ 0)
Maximum stock level (≥ min_stock)
Response Returns the created variant object with related item and UOM data. Status 201.
Errors
422 - Validation error (duplicate code, invalid item/UOM, max_stock < min_stock)403 - Insufficient permissions
Get Item Variant curl -X GET "https://api.sushigo.com/api/v1/item-variants/1" \ -H "Authorization: Bearer YOUR_TOKEN"
Path Parameters Response Total quantity across all locations
Total available (on_hand - reserved)
Example Response { "status" : 200 , "data" : { "id" : 1 , "code" : "ARR-KG" , "name" : "Arroz Premium 1kg" , "total_on_hand" : 250.0 , "total_reserved" : 15.0 , "total_available" : 235.0 , "avg_unit_cost" : 27.80 , "sale_price" : 35.00 , "item" : { "id" : 1 , "sku" : "INS-001" , "name" : "Arroz Sushi Premium" , "type" : "INSUMO" }, "uom" : { "id" : 3 , "code" : "KG" , "name" : "Kilogramo" , "symbol" : "kg" } } }
Errors Update Item Variant curl -X PUT "https://api.sushigo.com/api/v1/item-variants/1" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "sale_price": 38.00, "min_stock": 15 }'
Path Parameters Request Body All fields are optional. Only provided fields will be updated.
Variant code (must be unique)
item_id, uom_id, track_lot, and track_serial cannot be changed after creation.
Response Returns the updated variant object with status 200.
Errors
404 - Variant not found422 - Validation error403 - Insufficient permissions
Delete Item Variant curl -X DELETE "https://api.sushigo.com/api/v1/item-variants/1" \ -H "Authorization: Bearer YOUR_TOKEN"
Path Parameters Response { "status" : 200 , "message" : "Item variant deleted successfully" }
Errors
404 - Variant not found409 - Cannot delete - variant has stock on hand. Clear inventory first.403 - Insufficient permissions
Variants with stock on hand cannot be deleted. You must first consume or move all stock to zero before deletion.