Get the timeline of a serial number
The movement story of one physical unit, across stock, sales, service and supplier claims. It answers the question staff actually ask when a device comes back over the counter: where has this one been. Taken into stock, sold, handed in for service, opened up and had a part put in or taken out, finished, sent to a supplier on a claim, counted on a stocktaking — end to end, oldest first. It is assembled from the stock ledger and the service order events, which is why it crosses a boundary no single endpoint answers over. It is open to a caller holding any one of SERVICE_ORDER, SALES_ORDER, RETURN_ORDER, RMA_ORDER and REPORTING at any level — tenant-wide, at an organization or at any one store — or holding WAREHOUSE tenant-wide or at an organization; WAREHOUSE is a tenant-level permission, so a grant of it at a store alone does not open the timeline. A caller holding none of them, a user with no role assignments included, is refused with a 403. Every entry covers the whole tenant for every such caller: the stock movements, the sales and the supplier claims at every store, and the service entries of every service order whichever store owns the case and whichever store took it in. The history of a unit is the same wherever it is asked for and whoever asks. Every kind of entry is returned to every caller, whichever of those permissions they hold: a caller without SERVICE_ORDER sees the service entries too. Opening the record an entry names is judged by that record's own endpoint, so such a caller is refused when opening the service order a service entry names through get-serviceorders-by-id. It is answered for every tenant, whether or not the SERVICE_WORKSHOP extension is active on it. A tenant without the extension is answered out of its stock movements, sales and supplier claims, and out of the service entries of any service orders it holds. Each entry names the store it happened at, the product and the one record it is about in objects of their own, so a client opens the record from the entry itself (see SerialTimelineEntrySchema). A sale is here once the unit was actually handed over, never while it merely sits on an order: a basket open at the till, a parked sale and a credit line show nothing, while an order whose second line is months away still shows the unit that did go out; a quote and a cancelled order never count, whatever was delivered on them. A supplier claim is here once the claim has been sent to the supplier or completed — one still being prepared, waiting for approval or declined shows nothing, though a claim that shipped and was declined afterwards still answers out of the stock movement it made — and it is dated from the unit's own stock movement where there is one, and otherwise from the day the line was put on the claim. Serial numbers are only tracked in stock for products that require a serial on receive. For everything else there are no stock rows to show, and the timeline is made up of the sale, service and claim entries alone — a unit that was never serial-tracked in stock still has a story here. Pass productUid whenever it is known. A serial number is unique per product at best, so leaving it out can bring back the history of two different units that happen to carry the same serial.
Required permissions: SERVICE_ORDER,SALES_ORDER,RETURN_ORDER,RMA_ORDER,WAREHOUSE,REPORTING
Access token recevied after user login with a deviceToken
Reference to a tenant.
^[A-Za-z0-9-_]+The serial number or IMEI of the unit to follow, URL-encoded where it carries reserved characters. Matches either, case insensitively, and matches the whole value rather than a part of it.
The product the unit is of. Recommended: a serial number is only unique per product at best, so leaving this out can bring back the history of two different units that happen to carry the same serial.
^[A-Za-z0-9-_]+Reference to a specific page in a result set.
The number of items per page in a result set.
Example response
GET /v2/tenants/{tenantUid}/serialnumbers/{serial}/timeline HTTP/1.1
Host: api.flowretail.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Example response
{
"items": [
{
"occurredAt": "2026-01-01T00:00:00.000Z",
"kind": "STOCK_RECEIVED",
"title": "text",
"store": {
"storeUid": "text",
"name": "text"
},
"product": {
"productUid": "text",
"name": "text",
"sku": "text"
},
"serviceOrder": {
"serviceOrderUid": "text",
"serviceNumber": "text"
},
"salesOrder": {
"orderUid": "text",
"orderNumber": "text"
},
"receivement": {
"receivementUid": "text",
"packingList": "text"
},
"rmaOrder": {
"rmaOrderUid": "text",
"rmaNumber": "text"
},
"stocktaking": {
"stocktakingUid": "text"
}
}
],
"paging": {
"pageNumber": 1,
"pageSize": 1,
"totalCount": 1
}
}Last updated
Was this helpful?

