Skip to content

API Usage Inventory

Jump to bottom
simitben edited this page Apr 10, 2026 · 1 revision

Purpose

This page explains how third-party systems should call Inventory APIs in SimBiz 6 API V3.

Base URL

  • https://<host>/api/v3

Authentication

All inventory endpoints are protected.

Required headers:

  • Authorization: Bearer <token>
  • x-uid: <uid>

Token endpoint:

  • POST /api/v3/token (see API-Usage-Auth-System.md)

Date-Time Format

For filter parameters such as updated_from and updated_to, use:

  • YYYY-MM-DD HH:MM:SS
  • Example: 2026-04-09 00:00:00

Endpoint Summary

Endpoint Method Purpose
/api/v3/inventory/items GET List inventory items
/api/v3/inventory/items/{id} GET Get item detail by item id
/api/v3/inventory/items/by-code/{itemCode} GET Get item detail by item code
/api/v3/inventory/items POST Create item
/api/v3/inventory/items/{id} PATCH Update item
/api/v3/inventory/items/by-barcode/{barcode} GET Get item by barcode/item code
/api/v3/inventory/stocks/by-location GET Get stock balances by location
/api/v3/inventory/reference-data/{resource} GET Get reference lists

Response Pattern

  • List endpoints return data as an array and meta.pagination with paging details.
  • Detail endpoints return data as one object and meta as an empty object.
  • Use /{id} when you already have the internal item id.
  • Use /by-code/{itemCode} when you only have the item code.
  • Use /by-barcode/{barcode} when you only have the barcode, or when the integration stores the barcode as its lookup key.

1) List Inventory Items

Request

GET /api/v3/inventory/items

Query Parameters

Parameter Type Required Notes
page int No default 1
per_page int No default 50, max 200
q string No search by item code/name/barcode
item_id string No exact item id
item_code string No exact item code
updated_from datetime No updated range start
updated_to datetime No updated range end
organization_id / org_id string No org filter by id
organization_code / org_code string No org filter by code

If no organization filter is provided, API uses token org context.

Example cURL

curl -G "https://<host>/api/v3/inventory/items" \
  -H "Authorization: Bearer <token>" \
  -H "x-uid: support" \
  --data-urlencode "organization_code=BHH" \
  --data-urlencode "q=CAMBRIDGE" \
  --data-urlencode "updated_from=2026-01-01 00:00:00" \
  --data-urlencode "updated_to=2026-12-31 23:59:59" \
  --data-urlencode "page=1" \
  --data-urlencode "per_page=20"

Success Response Example

{
  "status": "OK",
  "data": [
    {
      "item_id": "1-1-1001",
      "item_code": "ITEM001",
      "item_name": "Sample Item",
      "item_barcode": "9551234567890",
      "organization_id": "1-1",
      "organization_code": "BHH",
      "updated": "2026-04-09 10:22:11"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 1,
      "total_pages": 1
    },
    "filters": {
      "organization_id": "",
      "organization_code": "BHH",
      "q": "CAMBRIDGE",
      "updated_from": "2026-01-01 00:00:00",
      "updated_to": "2026-12-31 23:59:59"
    }
  }
}

2) Get Item by ID

Use this when the integration already knows item_id.

Request

GET /api/v3/inventory/items/{id}

Path Parameters

Parameter Required Notes
id Yes item id

Example cURL

curl -X GET "https://<host>/api/v3/inventory/items/1-1-1001" \
  -H "Authorization: Bearer <token>" \
  -H "x-uid: support"

Success Response Example

{
  "status": "OK",
  "data": {
    "item_id": "1-1-1001",
    "item_code": "ITEM001",
    "item_name": "Sample Item",
    "item_barcode": "9551234567890",
    "organization_id": "1-1",
    "organization_code": "BHH",
    "updated": "2026-04-09 10:22:11"
  },
  "meta": {}
}

3) Get Item by Barcode

Use this when the caller only has a barcode or barcode-based external reference.

Request

GET /api/v3/inventory/items/by-barcode/{barcode}

Path Parameters

Parameter Required Notes
barcode Yes barcode or item code

Example cURL

curl -X GET "https://<host>/api/v3/inventory/items/by-barcode/9551234567890" \
  -H "Authorization: Bearer <token>" \
  -H "x-uid: support"

Success Response Example

{
  "status": "OK",
  "data": {
    "item_id": "1-1-1001",
    "item_code": "ITEM001",
    "item_name": "Sample Item",
    "item_barcode": "9551234567890",
    "organization_id": "1-1",
    "organization_code": "BHH",
    "updated": "2026-04-09 10:22:11"
  },
  "meta": {}
}

3a) Get Item by Code

Use this when the caller only has item_code.

Request

GET /api/v3/inventory/items/by-code/{itemCode}

Path Parameters

Parameter Required Notes
itemCode Yes exact item code

Example cURL

curl -X GET "https://<host>/api/v3/inventory/items/by-code/ITEM001" \
  -H "Authorization: Bearer <token>" \
  -H "x-uid: support"

Success Response Example

{
  "status": "OK",
  "data": {
    "item_id": "1-1-1001",
    "item_code": "ITEM001",
    "item_name": "Sample Item",
    "item_barcode": "9551234567890",
    "organization_id": "1-1",
    "organization_code": "BHH",
    "updated": "2026-04-09 10:22:11"
  },
  "meta": {}
}

4) Create Item

Request

POST /api/v3/inventory/items

JSON Body

Top-level:

  • organization_code or organization_id (optional if token org should be used)
  • data (required)

data.header common fields:

  • item_code (required)
  • item_name (required)
  • category_code or category_id
  • type_code or type_id
  • brand_code or brand_id

data.line common fields:

  • baseuom_code or baseuom_id
  • salesuom_code or salesuom_id
  • purchaseuom_code or purchaseuom_id
  • sell_price
  • purchase_price
  • isstock, issold, ispurchase

Example cURL

curl -X POST "https://<host>/api/v3/inventory/items" \
  -H "Authorization: Bearer <token>" \
  -H "x-uid: support" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_code": "BHH",
    "data": {
      "header": {
        "item_code": "ITEM-API-001",
        "item_name": "API Created Item",
        "category_code": "CAT001",
        "type_code": "TYPE001",
        "brand_code": "BRAND001"
      },
      "line": {
        "baseuom_code": "PCS",
        "salesuom_code": "PCS",
        "purchaseuom_code": "PCS",
        "sell_price": "12.00",
        "purchase_price": "10.00",
        "isstock": "1",
        "issold": "1",
        "ispurchase": "1"
      }
    }
  }'

5) Update Item

Request

PATCH /api/v3/inventory/items/{id}

Notes

  • id path parameter will be injected into data.header.item_id if not provided.
  • Use same payload shape as create (organization_* + data.header + data.line).

Example cURL

curl -X PATCH "https://<host>/api/v3/inventory/items/1-1-1001" \
  -H "Authorization: Bearer <token>" \
  -H "x-uid: support" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_code": "BHH",
    "data": {
      "header": {
        "item_name": "Updated API Item"
      },
      "line": {
        "sell_price": "13.00"
      }
    }
  }'

6) Stocks by Location

Request

GET /api/v3/inventory/stocks/by-location

Query Parameters

Parameter Type Required Notes
branch_id string No branch filter
item_codes string No comma-separated item codes
separate_location int/string No 1 to sort by location
updated_from datetime No updated range start
updated_to datetime No updated range end
organization_id / org_id string No org filter by id
organization_code / org_code string No org filter by code

Example cURL

curl -G "https://<host>/api/v3/inventory/stocks/by-location" \
  -H "Authorization: Bearer <token>" \
  -H "x-uid: support" \
  --data-urlencode "organization_code=BHH" \
  --data-urlencode "branch_id=1" \
  --data-urlencode "item_codes=ITEM001,ITEM002" \
  --data-urlencode "updated_from=2026-01-01 00:00:00" \
  --data-urlencode "updated_to=2026-12-31 23:59:59"

7) Reference Data

Request

GET /api/v3/inventory/reference-data/{resource}

Allowed Resource Values

  • categories
  • brands
  • types
  • uoms
  • locations

Example cURL

curl -X GET "https://<host>/api/v3/inventory/reference-data/categories" \
  -H "Authorization: Bearer <token>" \
  -H "x-uid: support"

Common Error Responses

Missing token or uid

{
  "status": "Failed",
  "errors": [
    {
      "code": "V3_AUTH_MISSING_CREDENTIAL",
      "message": "Missing uid or token",
      "details": []
    }
  ],
  "meta": []
}

Item not found

{
  "status": "Failed",
  "errors": [
    {
      "code": "V3_INV_ITEM_NOT_FOUND",
      "message": "Item not found",
      "details": {
        "id": "1-1-999999"
      }
    }
  ],
  "meta": []
}

Clone this wiki locally