Skip to main content

Inventory Management API

Version 1.7 — April 2025

Authentication: All requests require an IdToken from the Login API. See Authentication to obtain one and Errors for authorization errors.

Create Inventory API​

Create Inventory API allows to create multiple inventory items at the same time and associate the items to the respective RFID tracker serial number.

Graph API​

  • URL: https://api.xemelgo.com/graphql
  • Method: POST

Properties​

PropertyTypeDescriptionRequired
idStringSerial number of the item. Can be same as the RFID tag number in case the items are not serializedYes
partIdStringSKU/product/UPC number representing the type of the productYes
trackerSerialStringRFID tag number for the itemNo
descriptionStringDescription if any for the itemNo
nameStringName of the itemNo
lotNumberStringLot number of the lot the item is a part ofNo
expirationDateAWSTimestamp in millisecondsDate to define the expiration date for an itemNo
locationIdStringLocation of the item, that the item currently is being added toNo
customPropertiesAWSJSONAdditional properties that a customer may want to specify for the itemNo

Headers

Authorization – $idToken

Request Body​

Input can consist of multiple JSON objects of unique items.

mutation {
createInventory(
input: {
inventory: [
{
id: "item 1"
partId: "SKU 1"
trackerSerial: "12345679"
comments: "This is testing payload"
locationId: "Warehouse"
customProperties: "{\"thickness\": \"7/1\", \"width\": \"2-3/4\", \"length\": \"41.75\", \"quantity\": 286, \"po_number\": 123453}"
}
]
}
) {
inventoryIds
}
}

StatusCode - 200

Response Body​

{
"data": {
"createInventory": {
"inventoryIds": ["item 1"]
}
}
}

Response consists of a list of all inventory items that were created

Errors​

See authorization errors.

Additional 200-Level Errors​

ErrorError code
Duplicate trackerSerial in payload200
TrackerSerial already exists200
Item with same serial id already exist200

TrackerSerial in Payload​

{
"data": {
"createInventory": {
"inventoryIds": []
}
},
"errors": [
{
"path": ["createInventory"],
"data": null,
"errorType": "ResourceAlreadyExistError",
"errorInfo": null,
"message": "Item '1234' has tracker serial '12345679' that already exists. Use 'reuseTrackerSerial' if you want to reuse this tracker serial."
}
]
}

Item with Same ID Already Exists​

{
"data": {
"createInventory": {
"inventoryIds": []
}
},
"errors": [
{
"path": ["createInventory"],
"data": null,
"errorType": "PayloadValidationError",
"errorInfo": null,
"message": "Duplicate value [item1] found in the 'id' property. Please make sure each item has a unique id."
}
]
}

Duplicate TrackerSerial in Payload​

{
"data": {
"createInventory": {
"inventoryIds": []
}
},
"errors": [
{
"path": ["createInventory"],
"data": null,
"errorType": "PayloadValidationError",
"errorInfo": null,
"message": "Duplicate value [12345679] found in the 'trackerSerial' property. Please make sure each item has a unique trackerSerial."
}
]
}

Update Inventory API​

Update Inventory API allows to update different properties of the inventory items including updating the trackerSerial, item id or other properties.

Graph API​

  • URL: https://api.xemelgo.com/graphql
  • Method: POST

Properties​

PropertyTypeDescriptionRequired
idStringSerial number of the item. Can be same as the RFID tag number in case the items are not serializedYes
partIdStringSKU/product/UPC number representing the type of the productNo
trackerSerialStringRFID tag number for the itemNo
descriptionStringDescription if any for the itemNo
nameStringName of the itemNo
lotNumberStringLot number of the lot the item is a part ofNo
expirationDateAWSTimestamp in millisecondsDate to define the expiration date for an itemNo
locationIdStringLocation of the item, that the item currently is being added toNo
customPropertiesAWSJSONAdditional properties that a customer may want to specify for the itemNo

Headers

Authorization – $idToken

Request Body​

Input can consist of multiple JSON objects of unique items.

mutation {
updateInventory(
input: {
inventory: [
{
id: "item 1"
updates: {
trackerSerial: "98765432"
comments: "This is an updated payload"
locationId: "Warehouse"
customProperties: "{\"thickness\": \"7/1\", \"width\": \"2-3/4\", \"length\": \"41.75\", \"quantity\": 286, \"po_number\": 12345}"
}
}
]
}
) {
inventory {
id
part {
id
}
trackerSerial
customProperties
}
}
}

StatusCode - 200

Response Body​

{
"data": {
"updateInventory": {
"inventory": [
{
"id": "item 1",
"part": {
"id": "SKU 1"
},
"trackerSerial": "98765432",
"customProperties": "{\"species\":\"HW\",\"received_date\":1744779990000,\"grade\":\"grade\",\"width\":\"2-3/4\",\"thickness\":\"7/1\",\"length\":\"41.75\",\"quantity\":300,\"vendor\":\"Easter foreign products\",\"po_number\":12345}"
}
]
}
}
}

Response consists of a list of updated inventory items with updated properties.

Errors​

See authorization errors.

Additional 200-Level Errors​

ErrorError code
Duplicate trackerSerial in payload200
trackerSerial already exists200
Item with same serial id already exists200

Delete Inventory API​

Delete Inventory API allows you to permanently delete one or more inventory records from the system.

Graph API​

  • URL: https://api.xemelgo.com/graphql
  • Method: POST

Properties​

PropertyTypeDescriptionRequired
inventoryIdsStringList of inventory IDs to be deleted.Yes

Headers

Authorization – $idToken

Request Body​

mutation deleteInventory {
deleteInventory(input: { inventoryIds: ["860009120300091900000026"] }) {
inventoryIds
}
}

StatusCode - 200

Response Body​

{
"data": {
"deleteInventory": {
"inventoryIds": [
"860009120300091900000026"
]
}
}
}

Consume Inventory API​

Consume Inventory API allows to mark multiple inventory items as consumed at the same time.

Graph API​

  • URL: https://api.xemelgo.com/graphql
  • Method: POST

Properties​

PropertyTypeDescriptionRequired
inventoryIds[String!]!Array of inventory item IDs to be consumedYes

Headers

Authorization – $idToken

Request Body​

Input consists of an array of inventory item IDs to be consumed.

mutation {
consumeInventory(input: { inventoryIds: ["item 1", "item 2", "item 3"] }) {
inventoryIds
}
}

StatusCode - 200

Response Body​

{
"data": {
"consumeInventory": {
"inventoryIds": ["item 1", "item 2", "item 3"]
}
}
}

Response consists of a list of all inventory items that were consumed.

Errors​

See authorization errors.


Create Item Set API​

Create Item Set API allows to create multiple items at the same time and associate the items to the respective RFID tracker serial number.

Note* - This is a legacy API and continues to be supported.

Endpoint Details​

  • URL: https://api.xemelgo.com/graphql
  • Method: POST

Properties​

PropertyTypeDescriptionRequired
tracker_serialStringSerial number of the RFID tag associated to the specific itemYes
item_numberStringItem number/SKU number of the product item that the item belongs toYes
nameStringOptional property to describe a display name of the itemNo
lot_numberStringLot number of the lot the item is a part ofNo
categoryStringHigher level category that the item type/product belongs toNo
expiry_dateAWSTimestamp in millisecondsOptional date to define the expiration, calibration, or maintenance dateNo
onboarding_locationStringLocation of the item, that the item currently is being added toNo
customer_part_numberStringThe corresponding customer part number for the item_numberNo
tenant_propertiesAWS/JSONAdditional properties that a customer may want to specify for the itemNo

Headers –
Authorization – $idToken

Request Body​

Input can consist of multiple json of unique items

mutation {
createItemSet(
input: [
{
tracker_serial: "2024111100000001"
item_number: "Item-123"
name: "Item Name"
category: "Category"
expiry_date: 1721310198000
onboarding_location: "Warehouse A"
}
]
) {
tracker_serials
}
}

StatusCode - 200

Response Body​

{
"data": {
"createItemSet": {
"tracker_serials": [
"202411110000000000000001",
"202411110000000000000002",
"202411110000000000000003"
]
}
}
}

Response consists of a list of all tracker_serials that were created.

Errors​

See authorization errors.

Additional 400-Level Errors​

ErrorError code
Duplicate tracker_serial in payload400
Tracker_serial already exists400

Duplicate tracker_serial in payload​

{
"data": {
"createItemSet": null
},
"errors": [
{
"message": "All tracker_serials provided needs to be unique"
}
]
}

Tracker_serial already exists​

{
"data": {
"createItemSet": null
},
"errors": [
{
"message": "Tracker serial provided in the payload already exist in the system"
}
]
}

Get Items API​

Get a list of the current inventory items.

Endpoint Details​

  • URL: https://api.xemelgo.com/graphql
  • Method: POST

Request Properties​

PropertyTypeDescriptionRequired
filterStringFilter results on inventory item propertiesNo
nextTokenStringIf the request requires multiple pages to complete, provide the nextToken from the previous request's response to get the next pageNo

Response Properties​

PropertyTypeDescription
idStringUnique identifier for the inventory item
partInventoryPartInventory item part information
trackerSerialStringSerial number of the RFID tag associated to the specific inventory item
nameStringInventory item name
descriptionStringInventory item description
lotNumberStringLot number of the lot the item is a part of
isConsumedBooleanIf true, the item was consumed
consumedDateAWSTimestampTimestamp of the inventory item’s consumption
expirationDateAWSTimestampInventory item’s date of expiration
quantityIntegerThe expected quantity of the part
customerPartNumberStringInventory item’s customer part number (if applicable)
lastUpdatedDateAWSTimestampTimestamp of when the inventory item tracking information was last updated
creationDateAWSTimestampTimestamp at which the inventory item was created
stateStringCurrent state of the inventory item
locationLocationV2Location properties for the inventory item’s current location
lastDetectedAtLocationLocationV2Location properties where the inventory item was last detected by an RFID
customPropertiesAWS/JSONAdditional properties that a customer may have specified for the inventory item

Inventory Part Properties​

PropertyTypeDescription
idStringUnique identifier for the inventory part
numberStringInventory part number
nameStringInventory part name
descriptionStringInventory part description
unitStringUnit of measure for the inventory part
imagePathStringImage URL/path of the inventory part
customPropertiesAWS/JSONAdditional properties that a customer may have specified for the inventory part

LocationV2 Properties​

PropertyTypeDescription
idStringUnique identifier for the location
nameStringLocation name
descriptionStringLocation description
customPropertiesAWS/JSONAdditional properties that a customer may have specified for the location

Find item with a specific id ITEM_1234

filter : "id == \\\"ITEM_1234\\\""

Find item whose id starts with a prefix ITEM_

filter : "id ~= \\\"ITEM_\\\""

Filter for items created since a specific timestamp

filter : "creationDate > 1709254800000"

Filter for items that are not consumed

filter : "not isConsumed"

Headers –
Authorization – $idToken

Request Body​

query {
inventory(input: { filter: null, nextToken: null }) {
inventory {
creationDate
expirationDate
consumedDate
customProperties
customerPartNumber
description
id
isConsumed
lastUpdatedDate
lastDetectedAtLocation {
customProperties
description
id
name
}
location {
customProperties
description
id
name
}
trackerSerial
state
part {
customProperties
name
description
imagePath
id
quantity
number
unit
}
lotNumber
name
}
nextToken
}
}

Status Code - 200

Response Body​

{
"data": {
"inventory": {
"inventory": [
{
"creationDate": 1708057740183,
"expirationDate": null,
"consumedDate": null,
"customProperties": "{}",
"customerPartNumber": null,
"description": "",
"id": "INVENTORY_ITEM_1",
"isConsumed": false,
"lastUpdatedDate": 1706901595152,
"lastDetectedAtLocation": {
"customProperties": "{}",
"description": null,
"id": "STOCK_ROOM_1",
"name": "Stock Room 1"
},
"location": {
"customProperties": "{}",
"description": null,
"id": "STOCK_ROOM_1",
"name": "Stock Room 1"
},
"trackerSerial": "INVENTORY_ITEM_1_EPC",
"state": "OnHand",
"part": {
"customProperties": "{}",
"name": null,
"description": null,
"imagePath": null,
"id": "PART_1234",
"quantity": null,
"number": null,
"unit": null
},
"lotNumber": "",
"name": ""
}
],
"nextToken": null
}
}
}

Response consists of a list of all inventory items.

Errors​

See authorization errors.

Additional 200-Level Errors​

Error TypeError Code
Filter Error200
Invalid Token Error200

Filter error example:​

{
"data": {
"inventory": null
},
"errors": [
{
"path": ["inventory"],
"data": null,
"errorType": "FilterError",
"errorInfo": null,
"locations": [
{
"line": 57,
"column": 3,
"sourceName": null
}
],
"message": "Error: Lexical error on line 1. Unrecognized text.\n\tid === \"1234\"\n-----^"
}
]
}

Invalid token error example:​

{
"data": {
"inventory": null
},
"errors": [
{
"path": ["inventory"],
"data": null,
"errorType": "Error",
"errorInfo": null,
"locations": [
{
"line": 57,
"column": 3,
"sourceName": null
}
],
"message": "Invalid token"
}
]
}

Cycle Count Event​

The cycle count data can be published to a secure endpoint provided by the customer. The data can be ingested in the ERP system to then adjust the quantities of the SKU available accordingly.

The cycle count event payload will contain a list of SKUs and their respective on-hand and missing counts for the facility after a cycle count is performed in either the sales floor or back stock room. If a SKU is not listed in the payload, then it can be assumed that there are no items of that SKU in the store.

Example Payload​

{
"id": "bc87d998-7d57-426e-ab71-b359f3c367ab",
"eventType": "CYCLE_COUNT",
"locationId": "<Location – i.e. 101, 102, 103>",
"timestamp": <number – i.e. 1721310198000>,
"inventoryParts": [
{
"id": "<UPC – i.e. 197217325306>",
"name": "<Name – i.e. G5014TP-1271-2>",
"onhandCount": <number>,
"missingCount": <number>
}
// ...
]
}

Upload CSV API​

The Upload CSV API allows uploading CSV files to be processed by Xemelgo to:

  1. Create and/or update Item Types
  2. Upload supplemental data, such as Stock on Order for inventory tracking
  3. Define stock threshold values at different locations

Endpoint Details​

  • URL: https://api.xemelgo.com/graphql
  • Method: POST

Request Properties​

PropertyTypeDescriptionRequired
fileContentStringCSV file contents in JSON string format (including headers)Yes
fileNameStringName of the file to be created in Xemelgo (.csv filename)Yes
filePathStringPath for upload, e.g., ItemTypeSyncNo
typeStringType of upload: ANY, STOCK_ON_ORDER, STOCK_THRESHOLDNo, defaults to ANY
batchNameStringGroup multiple file uploads under a batch nameRequired for STOCK_ON_ORDER

Required CSV Columns for for STOCK_THRESHOLD and STOCK_ON_ORDER type​

STOCK_THRESHOLD​

HeaderValue DescriptionRequired
Item TypeItem Type IDYes
LocationXemelgo location nameYes
MinMinimum stock levelNo
OptimalOptimal stock levelNo

STOCK_ON_ORDER​

HeaderValue DescriptionRequired
Item TypeItem Type IDYes
LocationXemelgo location nameYes
Stock on OrderAmount of stock on orderNo

Request Body​

mutation {
uploadCSV(
input: {
fileContent: "Number,Number,Number\n123,123,123\n3333,33123123,3311\n1333,123331,231233233"
fileName: "test-1.csv"
filePath: "ItemTypeSync"
}
) {
result
}
}

Status Code - 200

Request Body Example (STOCK_THRESHOLD Upload)​

mutation {
uploadCSV(
input: {
fileContent: "Item Type,Location,Min,Optimal\nWigs,Stock Room,10,50\n"
fileName: "StockRoom1_StockThreshold.csv"
type: STOCK_THRESHOLD
}
) {
result
}
}

Request Body Example (STOCK_ON_ORDER Upload)​

mutation {
uploadCSV(
input: {
fileContent: "Location,Item Type,Stock On Order\nStockRoom1,Wigs,10\n"
fileName: "StockRoom1_StockOnOrder.csv"
type: STOCK_ON_ORDER
batchName: "2024Dec11"
}
) {
result
}
}

Response Body​

{
"data": {
"uploadCSV": {
"result": "File [test-1.csv] has been uploaded to Xemelgo"
}
}
}

Status Code - 200

Errors​

See authorization errors.

Additional 400-Level Errors​

ErrorError code
Invalid String or JSON400
Missing required fileContent field400

Invalid String or JSON​

{
"errors": [
{
"errorType": "MalformedHttpRequestException",
"message": "Unable to parse GraphQL query."
}
]
}

Missing required fileContent field​

{
"data": null,
"errors": [
{
"path": null,
"locations": [
{
"line": 3,
"column": 9,
"sourceName": null
}
],
"message": "Validation error of type WrongType: argument 'input' with value 'ObjectValue(objectFields=[ObjectField{name='fileName', value=StringValue{value='test-1.csv'}}, ObjectField{name='filePath', value=StringValue{value='ItemTypeSync'}}])' is missing required fields '[fileContent]' @ 'uploadCSV'"
}
]
}

Inventory Management Postman Collection​

{
"info": {
"_postman_id": "9ff7a270-cd8d-4387-b935-69242088b115",
"name": "Inventory Management Collection",
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
"_exporter_id": "14257901"
},
"item": [
{
"name": "Login",
"event": [
{
"listen": "prerequest",
"script": {
"exec": [
"var emailId = \"base 64 encoded email\";",
"var pass = \"base 64 encoded password\";",
"",
"pm.environment.set(\"email\", btoa(emailId));",
"pm.environment.set(\"password\", btoa(pass));"
],
"type": "text/javascript",
"packages": {}
}
},
{
"listen": "test",
"script": {
"exec": [
"var jsonData = JSON.parse(responseBody);",
"pm.environment.set(\"token\", jsonData.IdToken);"
],
"type": "text/javascript",
"packages": {}
}
}
],
"request": {
"auth": {
"type": "noauth"
},
"method": "POST",
"header": [
{
"key": "scenario",
"value": "1",
"type": "text",
"disabled": true
}
],
"body": {
"mode": "raw",
"raw": "{\n \"email\": \"{{email}}\",\n \"password\": \"{{password}}\"\n}",
"options": {
"raw": {
"language": "json"
}
}
},
"url": {
"raw": "https://rest.api.xemelgo.com/login",
"protocol": "https",
"host": ["rest", "api", "xemelgo", "com"],
"path": ["login"]
}
},
"response": []
},
{
"name": "Create Inventory part",
"request": {
"auth": {
"type": "noauth"
},
"method": "POST",
"header": [
{
"key": "Authorization",
"value": "{{token}}",
"type": "text"
}
],
"body": {
"mode": "graphql",
"graphql": {
"query": "mutation {\n createInventoryParts(\n input: {\n inputList: [\n {\n id : \"{{identifier}}\",\n description: \"{{Description}}\",\n customProperties: \"{\\\"sub_location_ts\\\": \\\"{{Bin}}\\\",\\\"customer_part_number_ts\\\": \\\"{{CPN}}\\\"}\"\n }\n ]\n }\n ) {\n partIds\n }\n}",
"variables": ""
}
},
"url": {
"raw": "https://api.xemelgo.com/graphql",
"protocol": "https",
"host": ["api", "xemelgo", "com"],
"path": ["graphql"]
}
},
"response": []
},
{
"name": "Update Inventory part",
"request": {
"auth": {
"type": "noauth"
},
"method": "POST",
"header": [
{
"key": "Authorization",
"value": "{{token}}",
"type": "text"
}
],
"body": {
"mode": "graphql",
"graphql": {
"query": "mutation {\n updateInventoryParts(\n input: {\n inputList: [\n {\n id : \"{{identifier}}\",\n customProperties: \"{\\\"bin_location_ts\\\": \\\"{{bin}}\\\"}\"\n }\n ]\n }\n ) {\n partIds\n }\n}",
"variables": ""
}
},
"url": {
"raw": "https://api.xemelgo.com/graphql",
"protocol": "https",
"host": ["api", "xemelgo", "com"],
"path": ["graphql"]
}
},
"response": []
},
{
"name": "List Inventory Parts",
"request": {
"auth": {
"type": "noauth"
},
"method": "POST",
"header": [
{
"key": "Authorization",
"value": "{{token}}",
"type": "text"
}
],
"body": {
"mode": "graphql",
"graphql": {
"query": "query inventoryParts ($filter: String, $nextToken: String) {\n inventoryParts(input: { filter: $filter, nextToken: $nextToken }) {\n inventoryParts {\n id\n number\n name\n description\n unit\n quantity\n }\n nextToken\n }\n}",
"variables": "{\n \"filter\": \"id in (\\\"FR557\\\", \\\"TB655\\\")\"\n}"
}
},
"url": {
"raw": "https://api.xemelgo.com/graphql",
"protocol": "https",
"host": ["api", "xemelgo", "com"],
"path": ["graphql"]
}
},
"response": []
},
{
"name": "Create Inventory",
"request": {
"auth": {
"type": "noauth"
},
"method": "POST",
"header": [
{
"key": "Authorization",
"value": "{{token}}",
"type": "text"
}
],
"body": {
"mode": "graphql",
"graphql": {
"query": "mutation {\n createItemSet(\n input: [\n {\n tracker_serial: \"E2801191A503006903FFC904\"\n item_number: \"FL7M-10K6WE-910Z\"\n },\n {\n tracker_serial: \"E2801191A503006903FFC9A4\"\n item_number: \"FL7M-10J6W-CN03\"\n },\n {\n tracker_serial: \"E2801191A503006903FFC994\"\n item_number: \"FL7M-10J6W-CN03\"\n },\n {\n tracker_serial: \"E2801191A503006903FFC9E4\"\n item_number: \"FL7M-15Y6W-910\"\n },\n {\n tracker_serial: \"E2801191A503006903FFC9D4\"\n item_number: \"FL7M-15Y6W-910\"\n }\n ]\n ) {\n tracker_serials\n }\n}",
"variables": ""
}
},
"url": {
"raw": "https://api.xemelgo.com/graphql",
"protocol": "https",
"host": ["api", "xemelgo", "com"],
"path": ["graphql"]
}
},
"response": []
},
{
"name": "List Inventory",
"request": {
"auth": {
"type": "noauth"
},
"method": "POST",
"header": [
{
"key": "Authorization",
"value": "{{token}}",
"type": "text"
}
],
"body": {
"mode": "graphql",
"graphql": {
"query": "query inventory ($filter: String, $nextToken: String) {\n inventory(input: { filter: $filter, nextToken: $nextToken }) {\n inventory {\n id\n name\n description\n part {\n id\n name\n }\n trackerSerial\n lastUpdatedDate\n creationDate\n state\n isConsumed\n consumedDate\n }\n nextToken\n }\n}",
"variables": "{\n \"filter\": \"state==\\\"removed\\\" and lastUpdatedDate >= 1736535539743\"\n}"
}
},
"url": {
"raw": "https://api.xemelgo.com/graphql",
"protocol": "https",
"host": ["api", "xemelgo", "com"],
"path": ["graphql"]
}
},
"response": []
}
]
}