> 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/list-service-orders-on-order.md).

# List service orders on order

List the service orders connected to a sales order, so a sale can be opened from the service it came out of and a service from the sale it belongs to. Each entry says how the two are connected: BILLED for a sales order that was generated from the service order to bill the work done on it, SOLD\_ITEM for a service order about an item that was sold on this sales order. The entries are slimmed down to what is needed to show them and open them — read the whole service order through the service order endpoints. Every service order of the tenant connected to the sales order is returned to a caller holding any one of SERVICE\_ORDER, SALES\_ORDER and RETURN\_ORDER at any level — tenant-wide, at an organization or at any one store — whichever store owns it and whichever store took it in. A caller holding none of them, a user with no role assignments included, is refused with a 403. At a tenant whose SERVICE\_WORKSHOP extension is not active the list is refused with a 403 for every caller. Opening a service order from the list through get-serviceorders-by-id asks for SERVICE\_ORDER, so a caller holding only SALES\_ORDER or RETURN\_ORDER sees the entry and is refused on opening it.

Required permissions: SERVICE\_ORDER,SALES\_ORDER,RETURN\_ORDER

```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":{"ServiceOrderLinkListResponse":{"description":"Example response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ServiceOrderLinkSchema"}},"paging":{"$ref":"#/components/schemas/Paging"}},"required":["items","paging"]}}}}},"schemas":{"ServiceOrderLinkSchema":{"title":"ServiceOrderLinkSchema","description":"A service order connected to a sales order, slimmed down to what is needed to show it in a list and open it. relation says how the two are connected.\nRead the whole service order through get-serviceorders-by-id, which asks for SERVICE_ORDER.","type":"object","required":["serviceOrderUid","storeUid","createdFromStoreUid","serviceNumber","title","serviceState","serviceStatusUid","serviceStatusName","serviceStatusColor","relation"],"properties":{"serviceOrderUid":{"$ref":"#/components/schemas/UID"},"storeUid":{"description":"The store that owns the service order now — the store the detail route is opened at. A service order that is moved to another store carries its new store here.","type":"string","pattern":"^[A-Za-z0-9-_]+"},"createdFromStoreUid":{"description":"The store the service order was taken in at, which never changes. storeUid is the store that owns it now, so the two differ once the service order has been moved between stores.","type":"string","pattern":"^[A-Za-z0-9-_]+"},"serviceNumber":{"type":"string","description":"The running service number the service order is known by."},"title":{"type":"string","description":"What the service order is about, as it is shown in a list."},"serviceState":{"$ref":"#/components/schemas/ServiceStateENUM"},"serviceStatusUid":{"description":"The status the service order is on now — the one serviceStatusName and serviceStatusColor are read from.","type":"string","pattern":"^[A-Za-z0-9-_]+"},"serviceStatusName":{"type":"string","description":"The name of the service order's status as it reads now. Renaming the status changes what is returned here."},"serviceStatusColor":{"type":"string","description":"The color the service order's status is drawn in, as it reads now: the same value as color in ServiceStatusResponseSchema, a hex color such as #0065d2, or an empty string when no color has been chosen, which leaves the chip in the client's default color. Changing the status's color changes what is returned here. It is carried on the entry because a caller holding only SALES_ORDER or RETURN_ORDER cannot read the service statuses through get-serviceorders-statuses or get-serviceorders-statuses-id."},"relation":{"type":"string","description":"How the service order and the sales order are connected.\nBILLED: the sales order was generated from the service order, to bill the work done on it. SOLD_ITEM: the service order is about an item that was sold on this sales order.","enum":["BILLED","SOLD_ITEM"]}}},"UID":{"title":"UID","type":"string","pattern":"^[A-Za-z0-9-_]+"},"ServiceStateENUM":{"title":"ServiceStateENUM","description":"Where a service order stands, as the platform understands it. Every status a tenant defines maps to exactly one state, and it is the state Flow reasons about: the workspace filters, the wording the portal shows the customer and the turnaround figures all follow the state rather than the name the status was given.\nAWAITING_PRODUCT: the service order is registered, but the device has not arrived yet.\nNOT_STARTED: the device is here and the work is queued.\nIN_TRANSIT: the service order is in a box on its way between locations.\nIN_PROGRESS: the work is being done.\nWAITING_CUSTOMER: waiting for an answer from the customer — never for the device, which is what AWAITING_PRODUCT is for.\nWAITING_SUPPLIER: waiting for parts or for an answer from a supplier.\nREADY_FOR_PICKUP: the outcome is ready to be handed over.\nCOMPLETE: the customer has the device back. This is the handover, never the payment.\nCANCELLED: the service order ended without a completed repair.\nCOMPLETE and CANCELLED are the terminal states.\nThe states are owned by the platform: tenants never define or rename them, and only decide which state each of their own statuses maps to. A status that exists today keeps the state it has until the tenant remaps it — nothing is remapped for them.\nExtensible — new states may be added, so clients must not fail on a value they do not know.","type":"string","enum":["AWAITING_PRODUCT","NOT_STARTED","IN_TRANSIT","IN_PROGRESS","WAITING_CUSTOMER","WAITING_SUPPLIER","READY_FOR_PICKUP","COMPLETE","CANCELLED"]},"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":{"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}/orders/{orderUid}/serviceorders":{"get":{"summary":"List service orders on order","tags":["Service"],"responses":{"200":{"$ref":"#/components/responses/ServiceOrderLinkListResponse"}},"operationId":"list-orders-serviceorders","description":"List the service orders connected to a sales order, so a sale can be opened from the service it came out of and a service from the sale it belongs to. Each entry says how the two are connected: BILLED for a sales order that was generated from the service order to bill the work done on it, SOLD_ITEM for a service order about an item that was sold on this sales order.\nThe entries are slimmed down to what is needed to show them and open them — read the whole service order through the service order endpoints.\nEvery service order of the tenant connected to the sales order is returned to a caller holding any one of SERVICE_ORDER, SALES_ORDER and RETURN_ORDER at any level — tenant-wide, at an organization or at any one store — whichever store owns it and whichever store took it in. A caller holding none of them, a user with no role assignments included, is refused with a 403. At a tenant whose SERVICE_WORKSHOP extension is not active the list is refused with a 403 for every caller. Opening a service order from the list through get-serviceorders-by-id asks for SERVICE_ORDER, so a caller holding only SALES_ORDER or RETURN_ORDER sees the entry and is refused on opening it.\n\nRequired permissions: SERVICE_ORDER,SALES_ORDER,RETURN_ORDER","parameters":[{"$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/list-service-orders-on-order.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.
