Skip to main content
Sign in with your store to see only the help that applies to you.

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 hand
  • in_stock — Whether the product is in stock
  • reorder_point — The reorder point (also sent as low_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​

ParameterTypeDescription
pageintegerPage number (default: 1)
per_pageintegerResults per page (default: 100, max: 100)
product_idintegerOnly adjustments for this product
warehouse_location_idintegerOnly adjustments at this stock location
adjustment_typestringFilter by type, e.g. sale, void, receive, count, inventory, spoilage, damage, transfer_in, transfer_out
sinceISO 8601Adjustments created after this timestamp (exclusive)
untilISO 8601Adjustments 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" }
}
FieldTypeNotes
quantity_changenumberSigned — negative for stock removed
quantity_before / quantity_afternumberStock on hand either side of the movement
userobject or nullWho made the adjustment. Adjustments made through an API key show the admin who created the key.
approved_byobject or nullWho approved it, where approval applies
warehouse_locationobject or null{ "id", "name" } of the stock location, when one was recorded
reconciliation_idinteger or nullSet when the row came from a stock count reconciliation rather than a one-off adjustment
Use since as a reconciliation cursor

Store 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​

ParameterTypeRequiredDescription
product_idintegeryesThe product to adjust
adjustment_typestringyesOne of: receive, count, inventory, spoilage, damage, reweigh, moisture_loss, check_out
quantity_changedecimalyes, except for inventoryThe 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_quantitydecimalfor inventoryThe 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_idintegernoThe stock location the movement applies to. A removal larger than what that location holds is rejected.
reasonstringnoFree-text reason for the adjustment (used as the note when reason_code is sent)
reason_codestringnoA 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_costdecimalnoreceive 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_keystringnoUp 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?​