Stock
Stock levels that move with jobs and invoices, stock history, locations, and adjustments
Servicebay keeps a stock count for every inventory item that has
tracksStock: true. The count is never edited directly. It changes when:
- a tracked part is added to, changed on, or removed from a job;
- an invoice that was not made from a job is created, edited or deleted (an invoice made from a job never moves stock, because the job's lines already did);
- someone records an adjustment, a transfer or a return.
Every change writes a row to the stock history, so the count and its history always agree. Stock is allowed to go below zero; nothing is ever blocked.
Required scopes: inventory:read to read stock, inventory:write to
adjust, transfer and return it.
Making a line move stock
A job's inventory line, or an entry in an invoice's inventoryItems, moves
stock only when it carries both:
| Field | Meaning |
|---|---|
catalogueItemId | The inventory item the line was picked from |
tracksStock | true when that item tracked stock at the time the line was added |
Send catalogueItemId and leave tracksStock out: the API copies it from the
inventory item. On a job line the item must exist (otherwise 400). A line
without catalogueItemId is a one-time part and never moves stock.
curl -X POST "https://developer.servicebay.io/api/v1/organisations/$ORG/tickets/1042/inventory" \
-H "X-API-Key: $KEY" -H "Content-Type: application/json" \
-d '{ "itemName": "Ball valve 15mm", "price": 18.5, "quantity": 2, "catalogueItemId": "ITEM_ID" }'Stock is taken a moment after the write, by Servicebay's stock functions. Read the item again, or its history, to see the new count.
Keep the link when you write lines back
PUT /invoices/{id} replaces the whole inventoryItems array. Send each
line back with the catalogueItemId and tracksStock it came with. A line
that loses its catalogueItemId reads as removed, and its stock goes back.
An explicit tracksStock: false or null is kept as it is: it marks a line
added while the item was not tracked.
Changing a stock count
stockCount can be set once, when the item is created (its opening count).
After that, PUT /inventory/{itemId} with a different stockCount returns
409 STOCK_COUNT_SERVER_OWNED. Sending the stored count back is accepted,
so reading an item and writing it back still works.
Record the change instead:
- POST
/organisations/{orgId}/inventory/{itemId}/stock-adjustments— Received, damaged or lost, or a stock count - POST
/organisations/{orgId}/stock-transfers— Move stock between locations - POST
/organisations/{orgId}/stock-returns— Return a job's or an invoice's parts to stock - GET
/organisations/{orgId}/stock-requests/{requestId}— The state of one of the above
reason | Send | Effect |
|---|---|---|
received | quantity | Adds quantity at the location |
damagedOrLost | quantity | Removes quantity at the location |
stockCount | counted | Sets the location's count to counted (records 0 when it already matches) |
locationId is optional and defaults to main. A stock count is always a
count of that location, not of the item's total.
200, 202 and requestId
These three endpoints hand the change to the same code the Servicebay app uses, so the stock history, per-location counts and low-stock alerts are exactly what the app would produce.
- 200 — applied.
data.statusisdoneanddata.resultholds the new balances. - 202 — accepted and still being applied (rare, usually under a second or
two). Poll
GET /stock-requests/{requestId}untilstatusisdoneorfailed. Do not send the request again with a newrequestId. - 409 / 404 / 400 — refused, with the reason (see below).
Send your own requestId (1–100 characters of A-Z a-z 0-9 _ -) to make a
retry safe. The same requestId with the same body returns the first
request's outcome and changes nothing — whatever has happened to the item
since. The same requestId with a different
body is 409 STOCK_REQUEST_ID_REUSED. Requests are kept for 30 days.
curl -X POST "https://developer.servicebay.io/api/v1/organisations/$ORG/inventory/$ITEM/stock-adjustments" \
-H "X-API-Key: $KEY" -H "Content-Type: application/json" \
-d '{ "reason": "received", "quantity": 10, "note": "Supplier delivery", "requestId": "delivery-2026-11-17-01" }'{
"success": true,
"data": {
"requestId": "delivery-2026-11-17-01",
"op": "adjust",
"status": "done",
"result": { "quantity": 10, "balanceAfter": 22, "locationBalanceAfter": 22 },
"movementIds": ["adj_delivery-2026-11-17-01"]
}
}409 code | When |
|---|---|
STOCK_COUNT_SERVER_OWNED | PUT /inventory/{id} tried to change stockCount |
STOCK_ITEM_NOT_TRACKED | The item has tracksStock off |
STOCK_LOCATION_NOT_ACTIVE | A transfer's to location is archived |
STOCK_REQUEST_ID_REUSED | The requestId was already used for a different request (also when the first request is older than 30 days and has been removed) |
STOCK_REQUEST_REFUSED | Any other refusal; data.reason says which |
In the stock history, changes made through the API are credited to API followed by the name of the API key or connected app. A connected app is named by what Servicebay could verify about it:
| The app | Credited as |
|---|---|
Identified by a metadata document (its client id is an https URL) on a hostname of its own | The document's hostname, e.g. API · tools.example |
Identified by a metadata document on shared hosting, where anyone can pick the hostname (*.pages.dev, *.github.io, *.vercel.app, *.netlify.app, a storage bucket, …) | The hostname followed by (unverified), e.g. API · acme.pages.dev (unverified) |
| Registered in the developer portal by your own organisation | The name your admin gave it |
| Registered itself, or registered in another organisation's portal | Its own name followed by (unverified), e.g. API · Acme (unverified) |
The same name appears in the job log for changes the app makes.
Stock locations
- GET
/organisations/{orgId}/stock-locations— List locations and each member's default
An organisation that has never added a location has one, main. Locations are
added, renamed and archived in the Servicebay app (Settings → Stock
Locations). An archived location stays in the list: the history still names it.
Stock From is the location a job or an invoice takes its parts from:
stockLocationId on a job or on an
invoice that was not made from a job. It must name an
active location (400 otherwise). When it is not set, parts come from where
the job already holds parts, then from the assigned member's default location,
then from main. Changing it moves the parts the job holds to the new
location.
An item's stockByLocation gives the count at each location. It is absent
until stock first moves somewhere other than main; until then all of
stockCount is at main.
Stock history
- GET
/organisations/{orgId}/stock-movements— List movements, newest first (?itemId=for one item) - GET
/organisations/{orgId}/stock-movements/{movementId}— Get one movement
Each movement has a signed quantity (the change at its locationId),
balanceAfter (the item's total afterwards), locationBalanceAfter, a
reason, and a source linking it to the job or invoice that caused it. A
transfer, or parts moving with their job, is two movements that share a
transferId.
reason is one of opening, usedOnJob, returnedFromJob, soldOnInvoice,
returnedFromInvoice, refundReturn, returned, received, stockCount,
damagedOrLost, transferOut, transferIn, movedWithJob,
movedWithInvoice. Treat an unknown value as a movement you do not need to
interpret: more reasons may be added.
Low stock
An item is low at or below its reorderLevel (set it with
PUT /inventory/{itemId}; null clears it), or out of stock when it has
none. lowStockAlertedAt is set while the item is low and its alert has gone
to the organisation's admins.
Machine-readable version: OpenAPI spec.