> 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-monthly-service-order-report-for-a-year.md).

# Get the monthly service order report for a year

Get one year of service order figures broken down by month — the long-horizon report behind the KPI page, where a season is seen rather than a week. Exactly twelve entries are returned, January through December; a month nothing happened in comes back with its counts 0 and its averages and overdueRate null rather than being left out. Each month's figures are computed exactly as the figures of the same name on the service order statistics endpoint, with that month as the period: registeredCount counts the service orders registered within the month, and completedCount, avgQueueDays, avgWorkDays, avgWorkOpenDays, avgPickupDays and overdueRate read the ones completed within it. The months run in the tenant's timezone, so a service order registered late on the last evening of a month belongs to that month rather than to the next. Year against year is two calls, one per year, shown side by side. There is no comparison built into the response and no rolling window: one call answers for one year. storeUids narrows every month to the stores that own the service orders — the stores the work sits with and where the customers collect, not the stores the service orders were taken in at. Left out, every store the caller holds SERVICE\_ORDER or REPORTING at is reported. The figures key on the store that owns a service order, never on the store it was taken in at: a case that has moved counts for the store it moved to, and for no other. Being able to read a case from another store, the store it was taken in at included, does not make it that store's work here. The figures count only the service orders owned by the stores the caller holds SERVICE\_ORDER or REPORTING at — every store of the tenant for a tenant-wide holder, the organization's stores for an organization holder, the assigned stores for a store-level holder, the two permissions adding up — because a figure is a store's work, not a case to find; the tenant-level service order search reaches further, to every service order of the tenant, for a caller holding SERVICE\_ORDER. A caller holding REPORTING and not SERVICE\_ORDER is answered exactly as a caller holding SERVICE\_ORDER at the same stores is. A caller holding neither, a user with no role assignments included, is refused with a 403.

Required permissions: SERVICE\_ORDER,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":{"ServiceOrderReportMonthlyResponse":{"description":"Example response","content":{"application/json":{"schema":{"type":"object","properties":{"months":{"type":"array","items":{"$ref":"#/components/schemas/ServiceOrderReportMonthSchema"}}},"required":["months"]}}}}},"schemas":{"ServiceOrderReportMonthSchema":{"title":"ServiceOrderReportMonthSchema","description":"One month of the yearly service order report. Every figure is computed exactly as the figure of the same name on the service order statistics endpoint, with that month as the period.\nA month nothing happened in is returned rather than left out, its counts 0 and its averages and overdueRate null, so the twelve entries always line up with the twelve months and a chart never has to fill a gap itself.","type":"object","required":["month","registeredCount","completedCount","avgQueueDays","avgWorkDays","avgWorkOpenDays","avgPickupDays","overdueRate"],"properties":{"month":{"type":"integer","minimum":1,"maximum":12,"description":"The month of the year the figures cover: 1 for January through 12 for December. The month runs in the tenant's timezone."},"registeredCount":{"type":"integer","description":"The number of service orders registered within the month."},"completedCount":{"type":"integer","description":"The number of service orders completed within the month. avgQueueDays and avgWorkDays are computed over the ones among them that entered IN_PROGRESS, avgWorkOpenDays over the ones among them that entered IN_PROGRESS and whose store has openDays, avgPickupDays over the ones that entered READY_FOR_PICKUP and overdueRate over the ones carrying a readyAtEstimate, exactly as on the statistics response."},"avgQueueDays":{"type":"number","nullable":true,"description":"The average number of days from registration to the first time work started, over the service orders completed within the month that entered IN_PROGRESS. null when none of them did."},"avgWorkDays":{"type":"number","nullable":true,"description":"The average number of days from the first time work started to completion, over the same service orders as avgQueueDays. null when none of them entered IN_PROGRESS."},"avgWorkOpenDays":{"type":"number","nullable":true,"description":"avgWorkDays counted only inside the opening hours of the store that owns the service order, on the store's working days (serviceCountWeekendsAsWorkingDays), in the tenant's timezone: a full working day counts 1, and part of one its share of that day's open hours. Like avgWorkDays, it is taken over the same service orders as avgQueueDays. Service orders whose store has no openDays are left out; null when none is left."},"avgPickupDays":{"type":"number","nullable":true,"description":"The average number of days finished work waited to be collected, over the same service orders. The ones that never entered READY_FOR_PICKUP are left out, and it is null when none of them did."},"overdueRate":{"type":"number","nullable":true,"description":"The share of the same service orders whose work was ready after their readyAtEstimate, from 0 to 1. It means exactly what overdueRate means on the statistics response: the ones carrying no readyAtEstimate are left out, and it is null when none of them carried one."}}},"UID":{"title":"UID","type":"string","pattern":"^[A-Za-z0-9-_]+"}},"parameters":{"serviceOrderReportYearQuery":{"name":"year","in":"query","required":true,"schema":{"type":"integer","minimum":2000,"maximum":2999},"description":"The year the twelve months are reported for, as four digits, e.g. 2026. The months run in the tenant's timezone, so a service order registered late on the last evening of a month belongs to that month rather than the next. Two years side by side are two calls, one per year."},"serviceOrderStatsStoreUidsQuery":{"name":"storeUids","in":"query","required":false,"schema":{"items":{"$ref":"#/components/schemas/UID"},"type":"array"},"description":"Narrow every figure to the stores that own the service orders — the stores the work sits with and where the customers collect. This is the owning store, not the store a service order was taken in at, and the two differ whenever a service order has been moved between stores. Leave it out to get every store the caller holds SERVICE_ORDER or REPORTING at — every store of the tenant for a tenant-wide holder, the organization's stores for an organization holder, the assigned stores for a store-level holder, the two permissions adding up. Naming a store the caller holds neither SERVICE_ORDER nor REPORTING at is not refused and adds nothing: storeUids narrows within the caller's stores and never widens them. A storeUid naming no store of the tenant answers 400."}}},"paths":{"/tenants/{tenantUid}/serviceorders/reports/monthly":{"get":{"summary":"Get the monthly service order report for a year","tags":["Service"],"responses":{"200":{"$ref":"#/components/responses/ServiceOrderReportMonthlyResponse"}},"operationId":"get-serviceorders-reports-monthly","description":"Get one year of service order figures broken down by month — the long-horizon report behind the KPI page, where a season is seen rather than a week. Exactly twelve entries are returned, January through December; a month nothing happened in comes back with its counts 0 and its averages and overdueRate null rather than being left out.\nEach month's figures are computed exactly as the figures of the same name on the service order statistics endpoint, with that month as the period: registeredCount counts the service orders registered within the month, and completedCount, avgQueueDays, avgWorkDays, avgWorkOpenDays, avgPickupDays and overdueRate read the ones completed within it.\nThe months run in the tenant's timezone, so a service order registered late on the last evening of a month belongs to that month rather than to the next.\nYear against year is two calls, one per year, shown side by side. There is no comparison built into the response and no rolling window: one call answers for one year.\nstoreUids narrows every month to the stores that own the service orders — the stores the work sits with and where the customers collect, not the stores the service orders were taken in at. Left out, every store the caller holds SERVICE_ORDER or REPORTING at is reported.\nThe figures key on the store that owns a service order, never on the store it was taken in at: a case that has moved counts for the store it moved to, and for no other. Being able to read a case from another store, the store it was taken in at included, does not make it that store's work here. The figures count only the service orders owned by the stores the caller holds SERVICE_ORDER or REPORTING at — every store of the tenant for a tenant-wide holder, the organization's stores for an organization holder, the assigned stores for a store-level holder, the two permissions adding up — because a figure is a store's work, not a case to find; the tenant-level service order search reaches further, to every service order of the tenant, for a caller holding SERVICE_ORDER.\nA caller holding REPORTING and not SERVICE_ORDER is answered exactly as a caller holding SERVICE_ORDER at the same stores is. A caller holding neither, a user with no role assignments included, is refused with a 403.\n\nRequired permissions: SERVICE_ORDER,REPORTING","parameters":[{"$ref":"#/components/parameters/serviceOrderReportYearQuery"},{"$ref":"#/components/parameters/serviceOrderStatsStoreUidsQuery"}]}}}}
```


---

# 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-monthly-service-order-report-for-a-year.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.
