Low Stock Report

Retrieve current low-stock inventory, including individual variation/location records, without replenishment suggestions.

Low Stock Report

GET/api/v3/reports/low-stock

Required scope: reports:read

Requires live inventory-list permission and an accessible account. As with the low-stock inventory screen, invoice and financial-report permissions are not required. Restricted credentials must include reports:read; items:read alone does not grant access to this endpoint.

An assigned inventory location restricts both rows and counts and is echoed in filters.location_id. Explicitly requesting a different location returns 403 permission_denied. The authenticated identity determines the SalesBinder account.

Query parameters

Parameter	Default	Description
`location_id`	All permitted locations	Optional account-owned active location UUID.
`supplier_id`	All suppliers	Optional account-owned supplier UUID, or `none` for items with no account-owned supplier associations.
`category_id`	All categories	Optional account-owned category UUID, including its immediate subcategories as in the existing report.
`stock_filter`	`below_threshold`	`below_threshold` or `below_threshold_or_zero`.
`sort`	`item_number`	`item_number`, `item_name`, `sku`, `quantity`, or `threshold`.
`direction`	`asc`	`asc` or `desc`. Item and stock-record IDs break ties.
`page`	`1`	Page number, normalized to at least 1.
`limit`	`20`	Rows per page, clamped to 1–100.
`include_total`	`true`	Include exact row counts; accepts `true`, `false`, `1`, or `0`.

Invalid values and unknown or other-account filter targets return 422 invalid_query_parameter with the offending param. A supplier filter matches any supplier associated with the parent item and never duplicates rows. No date range is used: this is current inventory.

curl 'https://yourbusiness.salesbinder.com/api/v3/reports/low-stock?stock_filter=below_threshold_or_zero&limit=100' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Low-stock rules

below_threshold: quantity + quantity_incoming < threshold. Equality does not qualify. A null incoming quantity is treated as zero; a null threshold does not qualify under this rule.
below_threshold_or_zero: the preceding condition or stored quantity = 0, even when incoming stock exists or the threshold is zero/null.
Reserved quantities are returned for context but are not subtracted by the inclusion rule. This preserves the existing report query's rule, rather than its displayed available-quantity calculation.
Archived items, unique items, and kits are excluded. Negative and fractional quantities are preserved.

An item without account-owned variation/location records produces one item row at its own location. When location records exist, each is evaluated separately using its own quantity, incoming quantity, and threshold. Only qualifying location records are returned; the parent aggregate is not returned as an additional row. This prevents healthy stock in another variation or location from hiding a low stock record. Unlike the current screen's grouped item presentation, this API intentionally returns individual stock records.

Response

Uses the standard paginated list envelope with object, url, has_more, data, pagination, and effective filters.

Row field	Description
`id`	Stable scope ID: `item:<UUID>` or `variation_location:<integer>`.
`object`	`low_stock_record`.
`scope_type`	`item` or `variation_location`.
`item_id`, `item_number`, `item_name`	Parent inventory identity.
`sku`, `barcode`	Parent item SKU and barcode.
`category_id`, `category_name`	Parent item's category; name may be null when unavailable.
`location_id`, `location_name`	The stock record's location; nullable.
`variation_id`, `variation_location_id`	Nullable variation UUID and integer stock-record ID. Location-only records may have no variation UUID.
`variation_barcode`	Nullable barcode of the linked variation.
`variation_attributes`	Array of readable `{name, value}` strings; empty when no attributes are available. Pricing attributes are not exposed.
`quantity`, `quantity_reserved`, `quantity_incoming`, `threshold`	Decimal strings preserving stored fractional precision, or null when the stored value is null.

No price, cost, replenishment percentage, minimum-needed amount, or suggested replenishment quantity is returned.

include_total=false omits pagination.total_records and pagination.total_pages and skips the exact count query. Counts refer to qualifying stock records, not distinct parent items. Empty results return an empty data array. Stock can change while paging; process records by stable id. Responses carry Cache-Control: no-store.