Stock Balance Module

  10. API Documentation, 1009. Stock Balance
SKYBIZ API — Stock Balance Module

Stock Balance

The Stock Balance module allows you to retrieve the current on-hand quantity of items across different locations in your SKYBIZ account. Supports read operation only.

Endpoint: /apiv2/modules/stock_balance.php

Required Permissions: Stock Balance — Read

Note: This module only supports read operation.

Read Stock Balance

Retrieves the on-hand quantity for specified items and locations as of the given date. The calculation includes all IN (GRN, Transfers In) and OUT (Sales, Transfers Out) transactions up to the specified date.

Base Request Structure

{
  "api_key": "your-api-key",
  "api_secret": "your-api-secret",
  "action": "read",
  "date": "YYYY-MM-DD",
  "item_code": ["ITEM001", "ITEM002"],
  "location_code": ["LOC001", "LOC002"]
}

Request Parameters

Parameter Description Required
api_key Your API key Yes
api_secret Your API secret Yes
action Must be "read" Yes
date Date in YYYY-MM-DD format. On-hand balance is calculated up to this date. Yes
item_code Array of item codes. Min 1 item, max 100 items. Yes
location_code Array of location codes. Min 1 location. Yes

Date Rules

  • Format must be YYYY-MM-DD — e.g. "2026-06-23"
  • Date is required — you cannot omit it
  • Stock balance is calculated up to and including the specified date
  • The system calculates: date_from = date - 1 day and date_to = date

Item Code Rules

  • Must be an array — e.g. ["ITEM001", "ITEM002"]
  • Minimum 1 item
  • Maximum 100 items
  • Each item code must not be empty

Location Code Rules

  • Must be an array — e.g. ["LOC001", "LOC002"]
  • Minimum 1 location
  • Each location code must not be empty

Response Fields

Field Type Description
ItemCode string Item code
LocationCode string Location code where the stock is held
Onhand integer On-hand quantity as of the specified date

Example 1 — Get Stock Balance for Specific Items and Locations

This request returns the on-hand quantity for ITEM100, ITEM200, and ITEM300 at LOC001, LOC002, and LOC003 as of 2026-06-23.

Request

{
  "api_key": "your-api-key",
  "api_secret": "your-api-secret",
  "action": "read",
  "date": "2026-06-23",
  "item_code": ["ITEM100", "ITEM200", "ITEM300"],
  "location_code": ["LOC001", "LOC002", "LOC003"]
}

Response (Success)

{
  "status": "response",
  "timestamp": "2026-06-23T15:14:48+08:00",
  "request_id": "req_6a3a3ee854374",
  "data": {
    "requested_by": "your-api-key",
    "mode": "2",
    "batch_id": "API20260623151448",
    "date_processed": "2026-06-23",
    "date_range": {
      "from": "2026-06-22",
      "to": "2026-06-23"
    },
    "total_records": 4,
    "data": [
      {
        "ItemCode": "ITEM100",
        "LocationCode": "LOC001",
        "Onhand": 45
      },
      {
        "ItemCode": "ITEM100",
        "LocationCode": "LOC002",
        "Onhand": 25
      },
      {
        "ItemCode": "ITEM200",
        "LocationCode": "LOC001",
        "Onhand": 17
      },
      {
        "ItemCode": "ITEM300",
        "LocationCode": "LOC003",
        "Onhand": 90
      }
    ]
  }
}

Sample Code for making an API READ request using php

<?php
header('Content-Type: application/json');

// ============================================================
// STEP 1: CONFIGURATION
// ============================================================

$API_KEY = "your-api-key";
$API_SECRET = "your-api-secret";
$ACTION = "read";
$DATE = "2026-06-23";

// Item and location codes (required)
$ITEM_CODES = ["ITEM100", "ITEM200", "ITEM300"];
$LOCATION_CODES = ["LOC001", "LOC002", "LOC003"];

// ============================================================
// STEP 2: ENDPOINT
// ============================================================

$BASE_URL = "https://domain-name/01/clientportal/apiv2/modules"; //(replace it with your skybiz domain name url)
$ENDPOINT = "stock_balance.php";

// ============================================================
// STEP 3: BUILD PAYLOAD
// ============================================================

$payload = [
    "api_key" => $API_KEY,
    "api_secret" => $API_SECRET,
    "action" => $ACTION,
    "date" => $DATE,
    "item_code" => $ITEM_CODES,
    "location_code" => $LOCATION_CODES
];

// ============================================================
// STEP 4: SEND REQUEST
// ============================================================

$url = rtrim($BASE_URL, '/') . '/' . ltrim($ENDPOINT, '/');

$ch = curl_init($url);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_TIMEOUT => 30,
]);

$response = curl_exec($ch);

// ============================================================
// STEP 5: HANDLE CURL ERROR
// ============================================================

if ($response === false) {
    echo json_encode([
        "status" => "error",
        "timestamp" => date("c"),
        "request_id" => uniqid("req_"),
        "message" => curl_error($ch)
    ], JSON_PRETTY_PRINT);
    curl_close($ch);
    exit;
}

$httpStatus = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

// ============================================================
// STEP 6: DECODE RESPONSE
// ============================================================

$result = json_decode($response, true);

if (!$result) {
    echo json_encode([
        "status" => "error",
        "timestamp" => date("c"),
        "request_id" => uniqid("req_"),
        "message" => "Invalid JSON from API",
        "raw_response" => $response
    ], JSON_PRETTY_PRINT);
    exit;
}

// ============================================================
// STEP 7: RETURN CLEAN JSON FORMAT
// ============================================================

echo json_encode([
    "status" => $result['status'] ?? "error",
    "timestamp" => date("c"),
    "request_id" => $result['request_id'] ?? uniqid("req_"),
    "data" => $result['data'] ?? null,
    "message" => $result['message'] ?? null
], JSON_PRETTY_PRINT);
?>

Postman Steps — READ Request

  1. Set method to POST

 

  1. Enter URL: https://your-domain/01/clientportal/apiv2/modules/stock_balance.php

 

  1. Set header: Content-Type: application/json

  1. Under Body, select raw and format JSON

  1. Paste your request payload and click Send

Error Responses

Missing Date

{
  "status": "error",
  "timestamp": "2026-06-23T10:46:15+08:00",
  "request_id": "req_6612f3b9c21a7",
  "message": "Date is required"
}

Invalid Date Format

{
  "status": "error",
  "timestamp": "2026-06-23T10:46:15+08:00",
  "request_id": "req_6612f3b9c21a7",
  "message": "Invalid date format. Use YYYY-MM-DD format"
}

Missing item_code

{
  "status": "error",
  "timestamp": "2026-06-23T10:46:15+08:00",
  "request_id": "req_6612f3b9c21a7",
  "message": "item_code is required and must contain at least 1 item"
}

Missing location_code

{
  "status": "error",
  "timestamp": "2026-06-23T10:46:15+08:00",
  "request_id": "req_6612f3b9c21a7",
  "message": "location_code is required and must contain at least 1 location"
}

Empty item_code Array

{
  "status": "error",
  "timestamp": "2026-06-23T10:46:15+08:00",
  "request_id": "req_6612f3b9c21a7",
  "message": "item_code must contain at least 1 item"
}

Empty location_code Array

{
  "status": "error",
  "timestamp": "2026-06-23T10:46:15+08:00",
  "request_id": "req_6612f3b9c21a7",
  "message": "location_code must contain at least 1 location"
}

Exceed 100 Items (>100)

{
  "status": "error",
  "timestamp": "2026-06-23T10:46:15+08:00",
  "request_id": "req_6612f3b9c21a7",
  "message": "Maximum 100 item codes allowed. You sent 101 items"
}

No Read Permission

{
  "status": "error",
  "timestamp": "2026-06-23T10:46:15+08:00",
  "request_id": "req_6612f3b9c21a7",
  "message": "Stock Balance read permission denied"
}

No Data Found

{
  "status": "response",
  "timestamp": "2026-06-23T10:46:15+08:00",
  "request_id": "req_6612f3b9c21a7",
  "data": {
    "requested_by": "your-api-key",
    "mode": "2",
    "batch_id": "API20260623104615",
    "date_processed": "2026-06-23",
    "date_range": {
      "from": "2026-06-22",
      "to": "2026-06-23"
    },
    "total_records": 0,
    "message": "No stock balance data found for the specified criteria",
    "data": []
  }
}

Common Errors — Stock Balance Module

Error Message Cause Fix
"Date is required" Missing date parameter Add date field in YYYY-MM-DD format
"Invalid date format. Use YYYY-MM-DD format" Wrong date format Use YYYY-MM-DD — e.g. "2026-06-23"
"item_code is required and must contain at least 1 item" Missing item_code parameter Add item_code array with at least 1 item
"location_code is required and must contain at least 1 location" Missing location_code parameter Add location_code array with at least 1 location
"item_code must contain at least 1 item" Empty item_code array Add at least 1 item code to the array
"location_code must contain at least 1 location" Empty location_code array Add at least 1 location code to the array
"Maximum 100 item codes allowed. You sent X items" Too many item codes Reduce to 100 items or fewer
"No stock balance data found for the specified criteria" No transactions found for the given items/locations/date Check if items/locations exist and have transactions
"Stock Balance read permission denied" No read permission for Stock Balance module Enable read permission in portal by contacting your SkyBiz Admin
"Invalid action. Only 'read' is allowed for Stock Balance API" Wrong action used Use "read" as the action