Inventory API
Required scope: inventory:read (read) · inventory:write (write)
Stock Levels
Stock levels are included in the Products API response (which needs products:read):
current_stock— Total stock on handin_stock— Whether the product is in stockreorder_point— The reorder point (also sent aslow_stock_threshold, its old name)low_stock_level— The stock level at which the product counts as low
For products with variations, each variation includes its own current_stock.
List Stock Adjustments
GET /api/v1/stock_adjustments
Required scope: inventory:read
Returns the stock adjustment ledger — every recorded movement, newest first, with the quantity before and after. This is the audit trail behind a stock number: if the count changed, one of these rows says why.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
page | integer | Page number (default: 1) |
per_page | integer | Results per page (default: 100, max: 100) |
product_id | integer | Only adjustments for this product |
warehouse_location_id | integer | Only adjustments at this stock location |
adjustment_type | string | Filter by type, e.g. sale, void, receive, count, inventory, spoilage, damage, transfer_in, transfer_out |
since | ISO 8601 | Adjustments created after this timestamp (exclusive) |
until | ISO 8601 | Adjustments created up to and including this timestamp |
since and until filter on when the adjustment was recorded. A value that cannot be parsed returns 422 Unprocessable Entity (since must be a valid timestamp).
Example
curl -H "X-API-Key: bpos_..." \
"https://yourstore.brotherpos.ca/api/v1/stock_adjustments?product_id=1&since=2026-08-01T00:00:00Z"
Response
{
"data": [
{
"id": 101,
"product_id": 1,
"product_name": "Blue Dream 3.5g",
"sku": "BD-35",
"adjustment_type": "receive",
"quantity_change": 26.0,
"quantity_before": 24.0,
"quantity_after": 50.0,
"reason": "Weekly shipment received",
"notes": null,
"user": { "id": 4, "name": "Dana R." },
"approved_by": null,
"warehouse_location": null,
"reconciliation_id": null,
"created_at": "2026-08-14T14:30:00.000Z"
}
],
"pagination": { "current_page": 1, "per_page": 100, "total_count": 37, "total_pages": 1 },
"meta": { "request_id": "...", "timestamp": "2026-08-19T12:00:00Z" }
}
| Field | Type | Notes |
|---|---|---|
quantity_change | number | Signed — negative for stock removed |
quantity_before / quantity_after | number | Stock on hand either side of the movement |
user | object or null | Who made the adjustment. Adjustments made through an API key show the admin who created the key. |
approved_by | object or null | Who approved it, where approval applies |
warehouse_location | object or null | { "id", "name" } of the stock location, when one was recorded |
reconciliation_id | integer or null | Set when the row came from a stock count reconciliation rather than a one-off adjustment |
since as a reconciliation cursorStore the timestamp of your last successful pull and pass it as since on the next run, so you only fetch new movements. See Recommended Sync Architecture.
Create a Stock Adjustment
POST /api/v1/stock_adjustments
Required scope: inventory:write
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
product_id | integer | yes | The product to adjust |
adjustment_type | string | yes | One of: receive, count, inventory, spoilage, damage, reweigh, moisture_loss, check_out |
quantity_change | decimal | yes, except for inventory | The quantity to add (positive) or remove (negative). Zero is rejected. receive must be positive; spoilage, damage, moisture_loss and check_out must not be positive. |
counted_quantity | decimal | for inventory | The quantity actually counted. The API records the difference from current stock (or from the stock at warehouse_location_id, if sent) as the change. Must not be negative. |
warehouse_location_id | integer | no | The stock location the movement applies to. A removal larger than what that location holds is rejected. |
reason | string | no | Free-text reason for the adjustment (used as the note when reason_code is sent) |
reason_code | string | no | A stock reason code, e.g. received, found, count_correction, damaged, expired, lost_theft, other. Must match the direction of the change. If the field is sent at a store that requires stock reasons, it must not be blank, and other also needs reason (omitting the field skips this check). With check_out, the code decides whether the row is recorded as damage, spoilage or check_out. |
unit_cost | decimal | no | receive only: the cost per unit paid, blended into the product's average cost. Honoured only when the key's creator can see financial data. |
idempotency_key | string | no | Up to 120 characters. Resending the same key returns the adjustment already made (200 OK) instead of making a second one. |
The parameters are sent at the top level of the body, not wrapped in an object.
Example
curl -X POST \
-H "X-API-Key: bpos_..." \
-H "Content-Type: application/json" \
-d '{
"product_id": 1,
"adjustment_type": "receive",
"quantity_change": 26.0,
"reason": "Weekly shipment received"
}' \
https://yourstore.brotherpos.ca/api/v1/stock_adjustments
Response
201 Created:
{
"data": {
"id": 101,
"product_id": 1,
"product_name": "Blue Dream 3.5g",
"adjustment_type": "receive",
"quantity_change": 26.0,
"quantity_before": 24.0,
"quantity_after": 50.0,
"reason": "Weekly shipment received",
"warehouse_location_id": null,
"warehouse_location_name": null,
"unit_cost": null,
"product_unit_cost": 11.75,
"created_at": "2026-03-22T14:30:00.000Z"
},
"meta": { ... }
}
When the store tracks stock by location, the response also includes floor_stock and back_stock.
unit_cost (the cost recorded on this row) and product_unit_cost (the product's unit cost now) are numbers when the key's creator can see financial data, and null otherwise. They follow the creator's role permission, not the costs:read scope.
An unknown adjustment_type, a zero quantity_change, a quantity in the wrong direction for its type, a negative counted_quantity, a fractional quantity of a product counted in whole units, a blank or wrong-direction reason_code, stock that would go below zero on a product that does not allow negative stock, or any adjustment to a bundle product (its stock comes from its components) returns 422. An unknown product_id returns 404.
What's Next?
- Purchasing & Receiving — What was ordered, invoiced, and what actually arrived
- Products — Stock levels, and cost behind the
costs:readscope