Docs
API Reference

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:

FieldMeaning
catalogueItemIdThe inventory item the line was picked from
tracksStocktrue 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
reasonSendEffect
receivedquantityAdds quantity at the location
damagedOrLostquantityRemoves quantity at the location
stockCountcountedSets 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.status is done and data.result holds the new balances.
  • 202 — accepted and still being applied (rare, usually under a second or two). Poll GET /stock-requests/{requestId} until status is done or failed. Do not send the request again with a new requestId.
  • 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 codeWhen
STOCK_COUNT_SERVER_OWNEDPUT /inventory/{id} tried to change stockCount
STOCK_ITEM_NOT_TRACKEDThe item has tracksStock off
STOCK_LOCATION_NOT_ACTIVEA transfer's to location is archived
STOCK_REQUEST_ID_REUSEDThe requestId was already used for a different request (also when the first request is older than 30 days and has been removed)
STOCK_REQUEST_REFUSEDAny 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 appCredited as
Identified by a metadata document (its client id is an https URL) on a hostname of its ownThe 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 organisationThe name your admin gave it
Registered itself, or registered in another organisation's portalIts 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.