Inventory balances

Review current physical stock by product and warehouse, focus on an availability state, and use complete product and product-and-warehouse stock-out counts.

Use GET /inventory-balances when a workflow needs the current physical balance for one product, a product family, one warehouse, or the complete visible inventory population.

Access

The endpoint requires inventory:read plus the acting user's current access to view Products and Lots. GET /me reports the result through effectiveCapabilities.inventory.balances.view and effectiveCapabilities.inventory.balances.currentStateRefresh.

curl "$SHELFCYCLE_API_BASE_URL/inventory-balances?productFamilyId=product-family-id&warehouseId=warehouse-id&limit=25" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Inventory availability dashboard"

Filters

Filters can be combined on the first request. An exact active and visible productId plus warehouseId request can return a zero row when no balance activity is present for that pair, making the zero explicit rather than leaving the match uncertain.

Availability states are based on the complete product-and-warehouse balance:

• zero_on_hand means on hand is zero.
• fully_allocated means on hand is positive and available is zero.
• positive_available means available is greater than zero.

To find every product-and-warehouse position with nothing available, request zero_on_hand and fully_allocated separately or use the complete meta.census.pairs.zeroAvailable count.

Read a balance row

{
  "data": [
    {
      "type": "inventory_balance",
      "product": {
        "id": "product-id",
        "code": "IPA-DRUM",
        "archived": false,
        "family": { "id": "product-family-id", "name": "Isopropyl Alcohol" }
      },
      "warehouse": {
        "id": "warehouse-id",
        "name": "Main Warehouse",
        "archived": false
      },
      "basis": {
        "type": "package_count",
        "unitOfMeasure": "GALLON",
        "packaging": { "id": "packaging-id", "name": "55 gallon drum" }
      },
      "onHand": "24",
      "allocated": "6",
      "available": "18",
      "quarantinedOnHand": "2"
    },
    {
      "type": "inventory_balance",
      "product": {
        "id": "variable-product-id",
        "code": "IPA-BULK",
        "archived": false,
        "family": { "id": "product-family-id", "name": "Isopropyl Alcohol" }
      },
      "warehouse": {
        "id": "warehouse-id",
        "name": "Main Warehouse",
        "archived": false
      },
      "basis": {
        "type": "base_uom",
        "unitOfMeasure": "POUND",
        "packaging": { "id": "base-packaging-id", "name": "Tank truck" }
      },
      "onHand": "12500.5",
      "allocated": "2500",
      "available": "10000.5",
      "quarantinedOnHand": "0"
    }
  ],
  "meta": {
    "populationCount": 2,
    "returnedRows": 2,
    "hasMore": false,
    "nextCursor": null,
    "ordering": "product_id_asc_warehouse_id_asc",
    "observedAt": "2026-08-24T16:30:00.000Z",
    "currentState": true,
    "snapshotIsolatedAcrossRequests": false,
    "census": {
      "population": "participating_physical_inventory_pairs",
      "scope": "entity_filters_excluding_availability",
      "pairs": {
        "zeroOnHand": 12,
        "fullyAllocated": 3,
        "positiveAvailable": 27,
        "zeroAvailable": 15,
        "archived": 1
      },
      "products": {
        "withParticipatingPairs": 36,
        "noneAvailableInScope": 11
      }
    },
    "requestId": "request-id"
  }
}

All quantities are decimal strings. available is onHand less allocated. quarantinedOnHand identifies the on-hand quantity currently in quarantine; it is part of on-hand, not an additional quantity.

The basis object tells you how to interpret every quantity on that row:

• package_count means the values count the named package and unit of measure.
• base_uom means the values use the product's named base unit, with the packaging record included as context.

Continue larger results

When meta.hasMore is true, call the endpoint again with meta.nextCursor by itself:

curl "$SHELFCYCLE_API_BASE_URL/inventory-balances?cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"

Do not combine a cursor with the original filters. The cursor retains the filter set, page size, ordering, organization, and API key needed for continuation. If a cursor is no longer valid, restart from the original filters.

populationCount reports the complete matched population, while returnedRows, hasMore, and nextCursor describe the current page and continuation.

Count stock outs

Use meta.census for complete counts instead of counting the current page:

• products.noneAvailableInScope counts products with no available stock anywhere in the selected product, family, and warehouse scope.
• pairs.zeroAvailable counts product-and-warehouse positions with no available stock. It equals zeroOnHand plus fullyAllocated.
• products.withParticipatingPairs counts products with physical inventory records in the selected scope.

Keep the product and position counts distinct in every summary. For the example above, say "11 products have no available stock across 15 product-and-warehouse positions."

The census follows the product, product-family, and warehouse filters but is calculated before availabilityState. That lets a filtered page of physically empty or fully allocated positions retain the complete stock-out summary for the selected scope.

Products without a physical inventory record are not part of the balance census. Under a warehouse filter, noneAvailableInScope means the product has no available stock at the selected warehouse.

Refresh current state

Each response includes observedAt, currentState: true, and snapshotIsolatedAcrossRequests: false. Treat it as the current view observed at that time. For a complete refresh, restart from the original filters and continue through the newly returned cursors.

Because inventory can change between pages, deduplicate by the product and warehouse ids when reconciling a refresh. Broader reads return current participating pairs. Archived products or warehouses with a nonzero balance remain clearly marked, while archived zero pairs are omitted. Quarantined quantities remain part of on hand when balances and availability states are calculated.