Catalog API Documentation

Browse endpoints, parameters, and live request examples.

GET /sockets/{socket_id}/items/{catalog_item_id}/stock

Get item stock status

Retrieves current stock availability information for a specific catalog item. This endpoint requires webhook configuration for real-time stock updates.

Catalog

Parameters

socket_id required path (integer)

The catalog socket to query

catalog_item_id required path (integer)

The catalog item ID to check

Responses

200 Stock information retrieved successfully
Item in stock

Item is available with known quantity 

{
  "stock": {
    "available": true,
    "catalog_item_id": "12345",
    "estimated_ship_date": null,
    "last_updated": "2025-08-08T10:45:00.000Z",
    "quantity_available": 157
  },
  "success": true,
  "timestamp": "2025-08-08T11:00:00.123Z"
}
Low stock warning

Item has limited quantity remaining 

{
  "stock": {
    "available": true,
    "catalog_item_id": "12346",
    "estimated_ship_date": null,
    "last_updated": "2025-08-08T10:30:00.000Z",
    "quantity_available": 3
  },
  "success": true,
  "timestamp": "2025-08-08T11:00:00.123Z"
}
Out of stock

Item currently unavailable but may be restocked 

{
  "stock": {
    "available": false,
    "catalog_item_id": "12347",
    "estimated_ship_date": "2025-08-15",
    "last_updated": "2025-08-08T09:15:00.000Z",
    "quantity_available": 0
  },
  "success": true,
  "timestamp": "2025-08-08T11:00:00.123Z"
}
Unlimited stock item

Digital or non-limited item always available 

{
  "stock": {
    "available": true,
    "catalog_item_id": "GC-100",
    "estimated_ship_date": null,
    "last_updated": "2025-08-08T00:00:00.000Z",
    "quantity_available": null
  },
  "success": true,
  "timestamp": "2025-08-08T11:00:00.123Z"
}
Response Schema
Schema Reference:

Stock information for a specific catalog item

Type: object
Required fields:
success timestamp stock

Properties:

stock ref: StockInfo required
success required
timestamp required
400 Invalid request
Example Response 
{
  "error_code": "INVALID_ITEM_TYPE",
  "message": "Stock checks only apply to limited stock items",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Response Schema
Schema Reference:

Standard error response format

Type: object
Required fields:
success message timestamp error_code

Properties:

error_code required
message required
success required
timestamp required
404 Item not found
Example Response 
{
  "error_code": "ITEM_NOT_FOUND",
  "message": "Item not found",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Response Schema
Schema Reference:

Standard error response format

Type: object
Required fields:
success message timestamp error_code

Properties:

error_code required
message required
success required
timestamp required
503 Stock service unavailable
Example Response 
{
  "error_code": "SERVICE_UNAVAILABLE",
  "message": "Stock check not available for this item",
  "success": false,
  "timestamp": "2023-12-01T15:30:45.123Z"
}
Response Schema
Schema Reference:

Standard error response format

Type: object
Required fields:
success message timestamp error_code

Properties:

error_code required
message required
success required
timestamp required