Inventory API

API reference for inventory levels, analytics, channel-location ATP, and cycle counts

Inventory API

The Inventory API provides endpoints for viewing inventory levels, analytics, channel-location ATP matrices, and managing cycle counts.

Scope: Tenant-scoped; requires authenticated org context
Availability: Not available in SuperAdmin

Authentication

All requests require authentication. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

See Authentication for details.

Base URL

https://app.betterdata.co/api/inventory

Headers

All requests must include:

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Endpoints

Method	Path	Summary	Auth	Stability	Permissions
GET	/api/inventory	List inventory items	session	stable	inventory.read
POST	/api/inventory/adjust	Adjust inventory	session	stable	inventory.adjust
GET	/api/inventory/adjustments	List inventory adjustments	session	stable	inventory.adjust
POST	/api/inventory/adjustments	Create inventory adjustment	session	stable	inventory.adjust
POST	/api/inventory/adjustments/lot-correction	Create lot correction adjustment	session	stable	inventory.adjust
GET	/api/inventory/adjustments/reason-codes	List adjustment reason codes	session	stable	inventory.adjust
GET	/api/inventory/adjustments/record-stock	List recorded stock adjustments	session	stable	inventory.adjust
POST	/api/inventory/adjustments/record-stock	Record stock adjustment	session	stable	inventory.adjust
GET	/api/inventory/availability	List availability records	session	stable	inventory.read
GET	/api/inventory/availability/[id]	Get availability record	session	stable	inventory.read
POST	/api/inventory/availability/[id]	Create availability record	session	stable	inventory.write
POST	/api/inventory/availability/check	Check availability	session	stable	inventory.read
GET	/api/inventory/channel-location	Get channel × location ATP matrix	session	stable	inventory.read
GET	/api/inventory/channel-location/drilldown	Drill down into channel-location ATP	session	stable	inventory.read
GET	/api/inventory/channel/summary	Get channel inventory summary	session	stable	inventory.read
GET	/api/inventory/cycle-count	List cycle count batches	session	stable	inventory.cyclecount
POST	/api/inventory/cycle-count	Create cycle count batch	session	stable	inventory.cyclecount
GET	/api/inventory/cycle-count/[batchId]	Get cycle count batch details	session	stable	inventory.cyclecount
POST	/api/inventory/cycle-count/[batchId]	Update cycle count batch	session	stable	inventory.cyclecount
GET	/api/inventory/cycle-count/abc	Get ABC classification for cycle counting	session	stable	inventory.cyclecount
POST	/api/inventory/cycle-count/abc	Create ABC-based cycle count	session	stable	inventory.cyclecount
GET	/api/inventory/cycle-count/blind-form	Get blind cycle count form	session	stable	inventory.cyclecount
POST	/api/inventory/cycle-count/resolve	Resolve cycle count discrepancies	session	stable	inventory.cyclecount
GET	/api/inventory/expired	List expired inventory	session	stable	inventory.read
POST	/api/inventory/expired/mark-consumed	Mark expired inventory as consumed	session	stable	inventory.write
POST	/api/inventory/expired/mark-expired	Mark inventory as expired	session	stable	inventory.write
POST	/api/inventory/expired/transfer-destruction	Transfer expired inventory for destruction	session	stable	inventory.write
GET	/api/inventory/holds	List inventory holds	session	stable	inventory.read
POST	/api/inventory/holds	Create inventory hold	session	stable	inventory.write
POST	/api/inventory/holds/release	Release inventory hold	session	stable	inventory.write
GET	/api/inventory/locations	List inventory by location	session	stable	inventory.read
GET	/api/inventory/lot-control/validate	Get lot control validation	session	stable	inventory.read
POST	/api/inventory/lot-control/validate	Validate lot control	session	stable	inventory.read
GET	/api/inventory/put-away	List put-away tasks	session	stable	inventory.read
POST	/api/inventory/put-away	Create put-away task	session	stable	inventory.write
POST	/api/inventory/record-stock	Record stock	session	stable	inventory.write
GET	/api/inventory/replenishment	List replenishment records	session	stable	replenishment.read
POST	/api/inventory/replenishment	Create replenishment record	session	stable	replenishment.write
GET	/api/inventory/replenishment/config	Get replenishment configuration	session	stable	replenishment.read
POST	/api/inventory/replenishment/config	Update replenishment configuration	session	stable	replenishment.write
POST	/api/inventory/replenishment/suggestions	Get replenishment suggestions	session	stable	replenishment.read
GET	/api/inventory/transfers	List inventory transfers	session	stable	transfers.read
POST	/api/inventory/transfers	Create inventory transfer	session	stable	transfers.write
GET	/api/inventory/transfers/[id]	Get inventory transfer	session	stable	transfers.read
POST	/api/inventory/transfers/[id]	Update inventory transfer	session	stable	transfers.write
GET	/api/inventory/transfers/bins	Get transfer bins	session	stable	transfers.read
GET	/api/products/[id]/inventory-levels	Get product inventory levels	session	stable	products.read, inventory.read
GET	/api/stock-requests	List stock requests	session	stable	stockrequests.read
POST	/api/stock-requests	Create a stock request	session	stable	stockrequests.write
GET	/api/stock-requests/[id]	Get a specific stock request	session	stable	stockrequests.read
PATCH	/api/stock-requests/[id]	Update a stock request	session	stable	stockrequests.write
DELETE	/api/stock-requests/[id]	Delete a stock request	session	stable	stockrequests.write
POST	/api/stock-requests/[id]/approve	Approve a stock request	session	stable	stockrequests.approve
POST	/api/stock-requests/[id]/comment	Add comment to stock request	session	stable	stockrequests.write
GET	/api/stock-requests/[id]/lines	Get stock request lines	session	stable	stockrequests.read
POST	/api/stock-requests/[id]/lines	Add line to stock request	session	stable	stockrequests.write
POST	/api/stock-requests/[id]/reject	Reject a stock request	session	stable	stockrequests.approve
POST	/api/stock-requests/[id]/rollback	Rollback a stock request	session	stable	stockrequests.write
GET	/api/stock-requests/[id]/status	Get stock request status	session	stable	stockrequests.read
POST	/api/stock-requests/[id]/status	Update stock request status	session	stable	stockrequests.write
POST	/api/stock-requests/[id]/submit	Submit a stock request	session	stable	stockrequests.write
GET	/api/stock-requests/by-category	Get stock requests by category	session	stable	stockrequests.read
GET	/api/stock-requests/dashboard	Get stock requests dashboard data	session	stable	stockrequests.read
GET	/api/stock-requests/filters	Get stock request filter options	session	stable	stockrequests.read
GET	/api/stock-requests/pending-approvals	Get pending approvals	session	stable	stockrequests.approve
GET	/api/stock-requests/products/search	Search products for stock requests	session	stable	stockrequests.read, products.read
GET	/api/stock-requests/products/stocklist	Get stocklist for stock requests	session	stable	stockrequests.read

| GET | /cycle-count | List cycle count batches | | POST | /cycle-count | Create cycle count batch | | GET | /cycle-count/[batchId] | Get cycle count batch details | | POST | /cycle-count/resolve | Resolve cycle count discrepancies |

Example Requests

Get Channel × Location ATP Matrix

curl -X GET "https://app.betterdata.co/api/inventory/channel-location?locationId=loc_123&page=1&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "products": [
    {
      "productMasterId": "prod_123",
      "productName": "Product Name",
      "globalSku": "SKU-123",
      "categoryName": "Category",
      "channels": [
        {
          "channelId": "DTC",
          "channelName": "Direct to Consumer",
          "atp": 150,
          "onHand": 200,
          "reserved": 50,
          "available": 150,
          "severity": "OK",
          "threshold": 10,
          "policyId": "policy_123"
        }
      ],
      "totalOnHand": 200,
      "totalReserved": 50,
      "minAtp": 150,
      "maxAtp": 150,
      "hasCritical": false
    }
  ],
  "channels": [
    {
      "channelId": "DTC",
      "channelName": "Direct to Consumer",
      "channelType": "E_COMMERCE",
      "policyId": "policy_123",
      "lowAtpThreshold": 10
    }
  ],
  "location": {
    "id": "loc_123",
    "name": "Main Warehouse"
  },
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "total": 150,
    "totalPages": 3
  }
}

List Inventory Items

curl -X GET "https://app.betterdata.co/api/inventory?locationId=loc_123&productMasterId=prod_123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "items": [
    {
      "id": "item_123",
      "productMasterId": "prod_123",
      "locationId": "loc_123",
      "quantityOnHand": 200,
      "quantityReserved": 50,
      "quantityAvailable": 150,
      "lotId": "lot_123",
      "expiryDate": "2024-12-31",
      "binId": "bin_123"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 1,
    "totalPages": 1
  }
}

Get Inventory Analytics

curl -X GET "https://app.betterdata.co/api/inventory/analytics?locationId=loc_123&fromDate=2024-01-01&toDate=2024-12-31" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "analytics": {
    "totalValue": 50000.00,
    "totalUnits": 1000,
    "turnoverRate": 12.5,
    "averageDaysOnHand": 30,
    "slowMovingItems": 25,
    "expiringItems": 10,
    "byCategory": [
      {
        "categoryId": "cat_123",
        "categoryName": "Category",
        "value": 25000.00,
        "units": 500
      }
    ]
  },
  "period": {
    "from": "2024-01-01T00:00:00Z",
    "to": "2024-12-31T23:59:59Z"
  }
}

Common Errors

401 Unauthorized

{
  "error": "Unauthorized"
}

Cause: Missing or invalid API key.

Solution: Include a valid API key in the Authorization header.

400 Bad Request

{
  "error": "locationId is required"
}

Cause: Required query parameter missing.

Solution: Include all required query parameters in the request.

404 Not Found

{
  "error": "Location not found or not accessible"
}

Cause: Location doesn’t exist or isn’t accessible to your organization.

Solution: Verify the location ID and ensure you have access to it.

500 Internal Server Error

{
  "error": "Internal Server Error",
  "message": "ATP calculation failed"
}

Cause: Server error during ATP calculation or data retrieval.

Solution: Retry the request. If the error persists, contact support.

Query Parameters

Channel-Location ATP

• locationId (required): Location ID
• search: Search by product name or SKU
• channels: Comma-separated channel IDs to filter
• page: Page number (default: 1)
• limit: Page size (default: 50, max: 200)

List Inventory

• locationId: Filter by location
• productMasterId: Filter by product
• lotId: Filter by lot
• binId: Filter by bin
• page: Page number (default: 1)
• limit: Page size (default: 20, max: 100)

Inventory Analytics

• locationId: Filter by location
• fromDate: Start date (ISO string)
• toDate: End date (ISO string)
• categoryId: Filter by category

Request/Response Schemas

Channel ATP Cell

{
  channelId: string;
  channelName: string;
  atp: number;
  onHand: number;
  reserved: number;
  available: number;
  severity: "OK" | "LOW" | "CRITICAL";
  threshold?: number;
  policyId?: string;
}

Inventory Item

{
  id: string;
  productMasterId: string;
  locationId: string;
  quantityOnHand: number;
  quantityReserved: number;
  quantityAvailable: number;
  lotId?: string;
  expiryDate?: string; // ISO date
  binId?: string;
  createdAt: string; // ISO datetime
  updatedAt: string; // ISO datetime
}

Inventory Analytics

{
  totalValue: number;
  totalUnits: number;
  turnoverRate: number;
  averageDaysOnHand: number;
  slowMovingItems: number;
  expiringItems: number;
  byCategory: Array<{
    categoryId: string;
    categoryName: string;
    value: number;
    units: number;
  }>;
}

---

Related Pages

• API Overview
• Authentication
• Common Errors

---

Permissions & Roles

Inventory API access requires inventory.read permission. Some endpoints may require additional permissions (e.g., inventory.cyclecount for cycle count endpoints).