> For the complete documentation index, see [llms.txt](https://docs.flowretail.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flowretail.com/docs/developers/api-documentation/service/get-the-timeline-of-a-serial-number.md).

# 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

```json
{"openapi":"3.0.2","info":{"title":"Flow Retail API version 2","version":"2.0.0"},"tags":[{"name":"Service","description":"Service"}],"servers":[{"description":"Flow Retail Production","url":"https://api.flowretail.com/v2"},{"description":"Flow Retail Stage","url":"https://api.stage.flowretail.com/v2"}],"security":[{"accessToken":[]},{"authToken":[]},{"integrationToken":[]}],"components":{"securitySchemes":{"accessToken":{"description":"Access token recevied after user login with a deviceToken","scheme":"bearer","type":"http"},"authToken":{"description":"Token received from the auth service","scheme":"bearer","type":"http"},"integrationToken":{"scheme":"bearer","type":"http"}},"responses":{"SerialTimelineListResponse":{"description":"Example response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/SerialTimelineEntrySchema"}},"paging":{"$ref":"#/components/schemas/Paging"}},"required":["items","paging"]}}}}},"schemas":{"SerialTimelineEntrySchema":{"title":"SerialTimelineEntrySchema","description":"One thing that happened to one physical unit, identified by its serial number or IMEI. Put end to end the entries are the unit's movement story: 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.\nThe story is assembled from two places — the stock ledger and the service order events — so it crosses the boundary between stock, sales, service and supplier claims that no single endpoint answers over.\nAn entry names what it is about in objects of their own: store, the store it happened at, with its name as it reads now; product, the catalogue product the unit is; and the one record kind names — serviceOrder on SERVICE_REGISTERED, SERVICE_PART_INSTALLED, SERVICE_PART_REMOVED and SERVICE_COMPLETED, salesOrder on SOLD, receivement on STOCK_RECEIVED, rmaOrder on RMA_SENT and stocktaking on STOCK_COUNTED. An object the entry is not about is absent, never present and empty, so a client opens the record from the record object when it is there. One entry never stands on more than one record. store is on every entry.\nproduct is absent on SERVICE_PART_REMOVED, because nothing records which product the part taken out was — the service order item names the part that replaced it, which is another unit — and on SERVICE_REGISTERED and SERVICE_COMPLETED when the service order names no product. receivement is absent on a STOCK_RECEIVED entry whose stock movement records no receivement, and stocktaking on a STOCK_COUNTED entry whose stock movement records no stocktaking; the entry is returned all the same, because nothing else records that movement.\nEntries are returned oldest first, which is the order the unit actually moved in.","type":"object","required":["occurredAt","kind","title","store"],"properties":{"occurredAt":{"type":"string","format":"date-time","description":"When it happened. Entries are ordered by this, ascending."},"kind":{"type":"string","description":"What happened to the unit.\nSTOCK_RECEIVED: the unit was taken into stock on a receivement. SOLD: it was sold to a customer. SERVICE_REGISTERED: it was handed in for service. SERVICE_PART_INSTALLED: a part carrying this serial was put into a device on a service order. SERVICE_PART_REMOVED: a part carrying this serial was taken out of a device on a service order. SERVICE_COMPLETED: a service order on this unit was finished. RMA_SENT: it was sent to a supplier on a claim. STOCK_COUNTED: it was counted on a stocktaking.\nExtensible — new kinds may be added, so clients must not fail on a value they do not know.","enum":["STOCK_RECEIVED","SOLD","SERVICE_REGISTERED","SERVICE_PART_INSTALLED","SERVICE_PART_REMOVED","SERVICE_COMPLETED","RMA_SENT","STOCK_COUNTED"]},"title":{"type":"string","description":"What happened, in one line, ready to be shown as it is."},"store":{"$ref":"#/components/schemas/StoreNameResponseSchema"},"product":{"$ref":"#/components/schemas/SerialTimelineProductSchema"},"serviceOrder":{"$ref":"#/components/schemas/SerialTimelineServiceOrderSchema"},"salesOrder":{"$ref":"#/components/schemas/SerialTimelineSalesOrderSchema"},"receivement":{"$ref":"#/components/schemas/SerialTimelineReceivementSchema"},"rmaOrder":{"$ref":"#/components/schemas/SerialTimelineRmaOrderSchema"},"stocktaking":{"$ref":"#/components/schemas/SerialTimelineStocktakingSchema"}}},"StoreNameResponseSchema":{"title":"StoreNameResponseSchema","type":"object","required":["storeUid","name"],"properties":{"storeUid":{"$ref":"#/components/schemas/UID"},"name":{"type":"string"}}},"UID":{"title":"UID","type":"string","pattern":"^[A-Za-z0-9-_]+"},"SerialTimelineProductSchema":{"title":"SerialTimelineProductSchema","description":"The catalogue product a serial timeline entry is about: the product of the stock movement, of the sold line, of the part put in, of the item on the claim, or the product the service order names on a hand-in and a completion. It is the product as the catalogue carries it now, its own name and SKU, never a name stored on a sales line or a service order item.","type":"object","required":["productUid","name","sku"],"properties":{"productUid":{"$ref":"#/components/schemas/UID"},"name":{"type":"string","description":"The product's name."},"sku":{"type":"string","description":"The product's SKU."}}},"SerialTimelineServiceOrderSchema":{"title":"SerialTimelineServiceOrderSchema","description":"The service order a serial timeline entry is about, under the names ServiceOrderResponseSchema serves them with.\nIt is served to every caller of the timeline, with or without SERVICE_ORDER. Opening the service order through get-serviceorders-by-id asks for SERVICE_ORDER.","type":"object","required":["serviceOrderUid","serviceNumber"],"properties":{"serviceOrderUid":{"$ref":"#/components/schemas/UID"},"serviceNumber":{"type":"string","description":"The running service number the service order is known by."}}},"SerialTimelineSalesOrderSchema":{"title":"SerialTimelineSalesOrderSchema","description":"The sales order the unit was sold on, under the names OrderResponseSchema serves them with.","type":"object","required":["orderUid","orderNumber"],"properties":{"orderUid":{"$ref":"#/components/schemas/UID"},"orderNumber":{"type":"string","description":"The sales order's number. An empty string on a sales order that has not been given one yet."}}},"SerialTimelineReceivementSchema":{"title":"SerialTimelineReceivementSchema","description":"The receivement the unit was taken into stock on, under the names ReceivementResponseSchema serves them with.","type":"object","required":["receivementUid","packingList"],"properties":{"receivementUid":{"$ref":"#/components/schemas/UID"},"packingList":{"type":"string","description":"The receivement's packing list number. An empty string on a receivement given none."}}},"SerialTimelineRmaOrderSchema":{"title":"SerialTimelineRmaOrderSchema","description":"The supplier claim the unit was sent to the supplier on, under the names RMAOrderResponseSchema serves them with.","type":"object","required":["rmaOrderUid","rmaNumber"],"properties":{"rmaOrderUid":{"$ref":"#/components/schemas/UID"},"rmaNumber":{"type":"string","description":"The claim's RMA number."}}},"SerialTimelineStocktakingSchema":{"title":"SerialTimelineStocktakingSchema","description":"The stocktaking the unit was counted on. A stocktaking has no number, so its uid is all that identifies it.","type":"object","required":["stocktakingUid"],"properties":{"stocktakingUid":{"$ref":"#/components/schemas/UID"}}},"Paging":{"description":"totalCount The total number of items in the result set.\n\npageSize The number of items per page.\n\npageNumber The current page in the result set.","properties":{"pageNumber":{"type":"integer"},"pageSize":{"type":"integer"},"totalCount":{"type":"integer"}},"required":["totalCount","pageSize","pageNumber"],"title":"Paging","type":"object"}},"parameters":{"serialTimelineProductUidQuery":{"name":"productUid","in":"query","required":false,"schema":{"$ref":"#/components/schemas/UID"},"description":"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."},"pageNumberQuery":{"description":"Reference to a specific page in a result set.","in":"query","name":"pageNumber","required":false,"schema":{"type":"integer"}},"pageSizeQuery":{"description":"The number of items per page in a result set.","in":"query","name":"pageSize","required":false,"schema":{"type":"integer"}}}},"paths":{"/tenants/{tenantUid}/serialnumbers/{serial}/timeline":{"get":{"summary":"Get the timeline of a serial number","tags":["Service"],"responses":{"200":{"$ref":"#/components/responses/SerialTimelineListResponse"}},"operationId":"get-serialnumbers-timeline","description":"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.\nIt 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.\nEvery 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.\nIt 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.\nEach 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).\nA 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.\nSerial 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.\nPass 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.\n\nRequired permissions: SERVICE_ORDER,SALES_ORDER,RETURN_ORDER,RMA_ORDER,WAREHOUSE,REPORTING","parameters":[{"$ref":"#/components/parameters/serialTimelineProductUidQuery"},{"$ref":"#/components/parameters/pageNumberQuery"},{"$ref":"#/components/parameters/pageSizeQuery"}]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flowretail.com/docs/developers/api-documentation/service/get-the-timeline-of-a-serial-number.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
