> 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/submit-service-order-checklist.md).

# Submit service-order checklist

Submit the checklist of one of the job types on a service order. This is the only way to record a checklist: CHECKLIST\_COMPLETED and CHECKLIST\_SKIPPED are written by Flow and are rejected on the events endpoint. The checklist is prompted at the transition that ends the work. Submit it with the outcome COMPLETED and a result for every item on the job type's checklist that holds no answer on the service order, or, once the user has confirmed the skip, with the outcome SKIPPED and no results. Either way an event is written on the timeline recording who submitted it and when, so the log always answers whether the work was tested. Unlike an answer, the submit is not limited to the states of the work, so a service order that goes straight from NOT\_STARTED to READY\_FOR\_PICKUP still records its checklist. With the outcome COMPLETED the event records a result for every item on the job type's checklist: the request's result where it carries one, and otherwise the answer the item holds on the service order, given during the work through put-serviceorders-checklist-answers. A request that leaves an item with neither is refused with a 400. The request's results are stored as those items' answers, attributed to the person submitting, so the service order's checklistAnswers read what the event records; a result equal to the answer the item already holds keeps who gave it and when. SKIPPED stores no answer and leaves the stored answers as they are. The items and their results are snapshotted on the event, so editing the job type's checklist afterwards does not change what was recorded. The created event is returned. The call is idempotent on serviceEventUid: generate the uid before the first attempt and reuse it on every retry. A repeat with a uid that is already on the timeline writes nothing and returns the event already written. Which checklists are still outstanding is read off the timeline rather than kept as a flag: they are the job types the service order carries, minus the ones a CHECKLIST\_COMPLETED or CHECKLIST\_SKIPPED event already names in its serviceJobTypeUid. Nothing is outstanding when every job type on the service order has an event of either kind. This is a write on the case, so it belongs to the store that owns the service order: at any other store it is refused with a 403, where the case can be read but not worked on.

Required permissions: SERVICE\_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":{"ServiceEventResponse":{"description":"Example response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceEventResponseSchema"}}}}},"schemas":{"ServiceEventResponseSchema":{"title":"ServiceEventResponseSchema","description":"An entry in the service order timeline. Every event has an eventType saying what it records; events created before event types existed are returned as STATUS_CHANGED.\nserviceStatusUid is set on the events that carry a status — the first entry the create writes, and every later STATUS_CHANGED and REOPENED. On every other event it is an empty string.\nAttribution is always double. tenantUserUid is the person who did the work: the caller, which on a shared screen is the person whose PIN unlocked it. It is empty on an entry no person wrote — one written under an integration token, which is no person, one the customer made in the service portal, and the creation entry of a service order whose create recorded no one — and empty when that person has since been deleted. screenAccountTenantUserUid is the screen account: the login the screen was signed in with when the work was done, which on the web app is the identity-provider login the browser holds. Under an unlock token it is read from the token; on a personal login, or under any other access token, it is the person themselves; it is empty wherever tenantUserUid is empty for want of a person, and empty when the screen account has since been deleted. Both are set when the entry is written and never edited. createdBy is not a third identity: it is the caller's display name as text, the audit column every record carries.","type":"object","required":["serviceEventUid","serviceOrderUid","serviceStatusUid","tenantUserUid","tenantUserDisplayName","screenAccountTenantUserUid","note","visibility","createdAt","createdBy","lastModifiedAt","lastModifiedBy","edited","notifications","eventType","checklistResults","quoteAmount","quoteDecisionVia","serviceJobTypeUid","movedFromStoreUid","movedToStoreUid"],"properties":{"serviceEventUid":{"$ref":"#/components/schemas/UID"},"serviceOrderUid":{"$ref":"#/components/schemas/UID"},"serviceStatusUid":{"description":"The status this event put the service order on: the status it started on, on the first entry the create writes, and the status it was moved to, on every later STATUS_CHANGED and REOPENED; an empty string on every other event.","type":"string","pattern":"^[A-Za-z0-9-_]*"},"tenantUserUid":{"$ref":"#/components/schemas/OptionalUID"},"tenantUserDisplayName":{"type":"string"},"screenAccountTenantUserUid":{"$ref":"#/components/schemas/OptionalUID"},"note":{"type":"string"},"visibility":{"$ref":"#/components/schemas/VisibilityENUM"},"createdAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string"},"lastModifiedAt":{"type":"string","format":"date-time"},"lastModifiedBy":{"type":"string"},"edited":{"type":"boolean","description":"Whether the event has been changed since it was written — the edited marker a chat message carries, and read the same way: the entry still stands, but it does not read as it first did. Who changed it and when are lastModifiedBy and lastModifiedAt; what it said before is not kept, so the marker is the whole of the disclosure.\nIt is set only by the event update endpoint. It is never derived from comparing timestamps, so an event that Flow touched for its own reasons — a backfill, a migration, a reindex — is never marked as edited by a person.\nBecause only the note and the visibility of an editable event can be changed at all, the marker only ever appears on entries a person wrote: STATUS_CHANGED, REOPENED, NOTE, DIAGNOSIS, RESOLUTION and STORE_MESSAGE. Events Flow writes itself are immutable and always return false."},"notifications":{"type":"array","items":{"$ref":"#/components/schemas/ServiceEventNotificationResponseSchema"}},"eventType":{"description":"What this timeline event records. Events created before event types existed are returned as STATUS_CHANGED.","allOf":[{"$ref":"#/components/schemas/ServiceEventTypeENUM"}]},"checklistResults":{"type":"array","description":"The job type checklist that was run, as recorded at the submit: one entry per item on the job type's checklist, each the result the submit carried or, where it carried none, the answer the item held on the service order. The entries are snapshotted so that editing the job type afterwards does not change what the event records.\nOnly a CHECKLIST_COMPLETED event carries results. It is an empty array on every other event, a CHECKLIST_SKIPPED event included — a skip records that the checklist was not run, by whom and when, and has nothing to report per item.","items":{"$ref":"#/components/schemas/ServiceEventChecklistResultSchema"}},"quoteAmount":{"type":"integer","nullable":true,"description":"The amount the quote stood at when this event was written, in the same unit as estimatedPrice and maxPrice on the service order. It is snapshotted at that moment, so a quote that is replaced afterwards never rewrites what an earlier event records — the timeline answers what was offered and what was answered, each at its own time.\nOnly QUOTE_SENT, QUOTE_APPROVED and QUOTE_DECLINED events carry an amount. It is null on every other event."},"quoteDecisionVia":{"type":"string","description":"Where the customer's answer to the quote was given, so the record says how it reached the store.\nPORTAL: the customer answered with the service portal's buttons. IN_PERSON: the customer answered over the counter. PHONE: the customer answered on the phone. WRITTEN: the customer answered in writing outside the portal's buttons — in a portal message, an SMS reply or an e-mail.\nIt reports all four origins, which is more than staff are ever asked to send. PORTAL is written by the portal itself; IN_PERSON, PHONE and WRITTEN are the three a person records, and they are the values of ServiceQuoteDecisionViaENUM.\nOnly QUOTE_APPROVED and QUOTE_DECLINED events carry it. It is an empty string on every other event, QUOTE_SENT included — sending a quote is not a decision.","enum":["","PORTAL","IN_PERSON","PHONE","WRITTEN"]},"serviceJobTypeUid":{"description":"The job type whose checklist this event records. Set on CHECKLIST_COMPLETED and CHECKLIST_SKIPPED events, which is how the outstanding checklists on a service order are worked out: the job types it carries, minus the ones a CHECKLIST_ event already names.\nAn empty string on every other event.","type":"string","pattern":"^[A-Za-z0-9-_]*"},"movedFromStoreUid":{"description":"The store the service order left, on a MOVED event. An empty string on every other event.","type":"string","pattern":"^[A-Za-z0-9-_]*"},"movedToStoreUid":{"description":"The store the service order went to, on a MOVED event. An empty string on every other event.","type":"string","pattern":"^[A-Za-z0-9-_]*"}}},"UID":{"title":"UID","type":"string","pattern":"^[A-Za-z0-9-_]+"},"OptionalUID":{"title":"OptionalUID","type":"string","pattern":"^[A-Za-z0-9-_]*"},"VisibilityENUM":{"title":"VisibilityENUM","description":"Who may read a timeline entry.\nINTERNAL: staff only — never in the service portal and never on the printed service papers. PUBLIC: shown to the customer, in the portal and on the printed papers alike. REPORT: printed on the service papers only — the service summary and the damage report, since the service confirmation carries no written entries — and never shown in the service portal.\nOn a NOTE, a DIAGNOSIS or a RESOLUTION the visibility says only where the entry is shown and never sends the customer anything. The papers carry written entries only — a NOTE, a DIAGNOSIS or a RESOLUTION — so what a visibility says about paper applies to those three. On every other event type the visibility governs the service portal alone: a status change carrying REPORT is accepted and simply does not print. A STORE_MESSAGE is not a written entry: it is always PUBLIC, shown in the portal and never printed on any paper.","type":"string","enum":["INTERNAL","PUBLIC","REPORT"]},"ServiceEventNotificationResponseSchema":{"title":"ServiceEventNotificationResponseSchema","type":"object","required":["notificationUid","type","state","recipient"],"properties":{"notificationUid":{"$ref":"#/components/schemas/UID"},"type":{"$ref":"#/components/schemas/MessageTypeENUM"},"state":{"$ref":"#/components/schemas/NotificationStateENUM"},"recipient":{"type":"string"}}},"MessageTypeENUM":{"title":"MessageTypeENUM","type":"string","enum":["EMAIL","SMS"]},"NotificationStateENUM":{"title":"NotificationStateENUM","type":"string","enum":["NOT_STARTED","IN_PROGRESS","COMPLETE","FAILED"]},"ServiceEventTypeENUM":{"title":"ServiceEventTypeENUM","description":"What a service order timeline event records. Every event has exactly one event type.\nSTATUS_CHANGED: the event put the service order on the status it carries. The first entry on every timeline is a STATUS_CHANGED written by the create, carrying the status the service order started on, with the visibility INTERNAL; it is edited like any other status change. NOTE: a note written by staff, carrying no status change. ASSIGNED: the service order was handed to another user, or unassigned, through the assign endpoint. It is written with the visibility INTERNAL and carries no status, and its note names by display name the user it went to, or records that it went back to the store on an unassign, in the tenant's own language. REOPENED: a status change that moves the service order out of a terminal state, COMPLETE or CANCELLED, is recorded and returned as REOPENED rather than as STATUS_CHANGED. It carries the status it moved to exactly as any other status change does, and it is the one Flow-typed event a person authors: reopening is the status change, there is no separate reopen action, and a service order is never reopened by anything other than someone moving it. DIAGNOSIS: what the technician found to be wrong. RESOLUTION: what was done to resolve the issue. FIELD_CHANGE: one of the tracked fields on the service order was changed. The tracked fields are claimNumber, coverage, customerUid, deductible, externalSalesOrderNumber, priority, readyAtEstimate and title; changing any other field leaves no event. One event is written per changed field, so an update that changes three of them leaves three events. Each is written with the visibility INTERNAL and carries no status, and its note says which field changed and from what to what, in the tenant's own language. A change of customer names the customer before and the customer after. A change of the deductible names the amount before and after in the tenant's currency, as an amount, never in minor units. CUSTOMER_MESSAGE: a free-text message the customer wrote in the service portal. STORE_MESSAGE: a message the store wrote to the customer — the store's half of the dialogue in the service portal, beside CUSTOMER_MESSAGE. It is always PUBLIC and carries no status; it carries its author on the staff timeline like any staff entry, while the portal never shows who wrote it, and it is never printed on any paper. TERMS_ACCEPTED: the customer accepted the terms and conditions on the service order — in the service portal, on a counter device or in the store. TERMS_VOIDED: the acceptance recorded on the service order was voided through the void endpoint, or by a change of the service order's customer — the note carries the reason given, while who voided it and when are the event's own attribution and timestamp. QUOTE_SENT: a price was offered to the customer, whether or not a message went out with it. QUOTE_APPROVED: the customer approved the quote. QUOTE_DECLINED: the customer declined the quote. All three are written with the visibility PUBLIC and carry no status: the customer sees the offer and their own answer in the portal history, each entry carrying the amount it stood at, and each with an empty note of its own — the portal words the entry from its type. CHECKLIST_COMPLETED: a job type checklist was completed through the service order's checklist endpoint, with the result of every item snapshotted on the event. CHECKLIST_SKIPPED: a job type checklist was skipped through the service order's checklist endpoint, after the user confirmed the skip. SECRET_VIEWED: a secret on the service order was revealed through the secrets reveal endpoint. SECRET_DELETED: a secret on the service order was deleted through the secrets delete endpoint before the service order finished; the note carries the label of the secret that was removed, so the timeline says what was taken off the case and by whom. MOVED: the service order was moved to another store through the move mechanism, whether by the move endpoint or by the receipt of a shipment item at another store. It is written with the visibility INTERNAL and carries no status; movedFromStoreUid and movedToStoreUid record the store it left and the store it went to, and its note records the assignment the move ended, in the tenant's own language.\nOnly STATUS_CHANGED, NOTE, DIAGNOSIS, RESOLUTION and STORE_MESSAGE can be sent when an event is created — every other type is written by Flow when the corresponding action happens, REOPENED included, which is what a STATUS_CHANGED out of a terminal state is recorded as. Editing reaches those five and REOPENED with them; every other type is immutable.","enum":["STATUS_CHANGED","NOTE","ASSIGNED","REOPENED","DIAGNOSIS","RESOLUTION","FIELD_CHANGE","CUSTOMER_MESSAGE","STORE_MESSAGE","TERMS_ACCEPTED","TERMS_VOIDED","QUOTE_SENT","QUOTE_APPROVED","QUOTE_DECLINED","CHECKLIST_COMPLETED","CHECKLIST_SKIPPED","SECRET_VIEWED","SECRET_DELETED","MOVED"],"type":"string"},"ServiceEventChecklistResultSchema":{"title":"ServiceEventChecklistResultSchema","description":"The result of one checklist item, snapshotted on the event when the checklist was submitted. Editing the job type's checklist afterwards does not change what was recorded.","type":"object","required":["item","checked"],"properties":{"item":{"type":"string","description":"The checklist item as it read on the job type when the checklist was submitted."},"checked":{"type":"boolean","description":"Whether the test passed. False records an item that was run and did not pass, which stays on the timeline together with the rest of the checklist."}}},"ServiceOrderChecklistSubmitRequestSchema":{"title":"ServiceOrderChecklistSubmitRequestSchema","description":"The submission of one job type's checklist on a service order. The checklist is prompted at the transition that ends the work and is either completed or, once the user has confirmed the skip, skipped — either way the outcome is written on the timeline with the user who submitted it and when, so the log always answers whether the work was tested.\nserviceJobTypeUid must be one of the job types the service order carries. With the outcome COMPLETED every item on the job type's checklist needs a result, one per item: the request's own, or the answer the item already holds on the service order, so results may leave out the items already answered, and a request that leaves an item with neither is refused with a 400. The results sent are stored as those items' answers. With SKIPPED no results are sent, none are recorded, and the stored answers stay as they are.\nSupply serviceEventUid to make the call idempotent.","type":"object","required":["serviceJobTypeUid","outcome"],"properties":{"serviceEventUid":{"description":"The uid the checklist event is written under. Generate it before the first attempt and reuse the same value on every retry: a second request carrying a uid that is already on the timeline writes nothing and answers the event already written, so a retry after a timeout can never record the same checklist twice.","type":"string","pattern":"^[A-Za-z0-9-_]+"},"serviceJobTypeUid":{"description":"The job type on the service order whose checklist is being submitted.","type":"string","pattern":"^[A-Za-z0-9-_]+"},"outcome":{"type":"string","description":"COMPLETED: the checklist was run, and every item has a result — in results, or as the answer the item already holds on the service order. SKIPPED: the user confirmed skipping the checklist and nothing was tested.","enum":["COMPLETED","SKIPPED"]},"results":{"type":"array","description":"Results for the items on the job type's checklist, one per item, in any order. With the outcome COMPLETED it carries every item that holds no answer on the service order and may leave out the ones that do, whose answer then stands as the item's result, so it may be empty or left out when every item is answered; it is left out when the outcome is SKIPPED. Each result sent is stored as the item's answer, attributed to the person submitting; a result equal to the answer the item already holds keeps who gave it and when.","items":{"$ref":"#/components/schemas/ServiceEventChecklistResultSchema"}},"note":{"type":"string","description":"What the user wants to add about the checklist, such as why it was skipped. Becomes the note on the event that is written."}}}},"requestBodies":{"ServiceOrderChecklistSubmitRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceOrderChecklistSubmitRequestSchema"}}}}}},"paths":{"/tenants/{tenantUid}/stores/{storeUid}/serviceorders/{serviceOrderUid}/checklist":{"post":{"summary":"Submit service-order checklist","operationId":"post-serviceorders-checklist","description":"Submit the checklist of one of the job types on a service order. This is the only way to record a checklist: CHECKLIST_COMPLETED and CHECKLIST_SKIPPED are written by Flow and are rejected on the events endpoint.\nThe checklist is prompted at the transition that ends the work. Submit it with the outcome COMPLETED and a result for every item on the job type's checklist that holds no answer on the service order, or, once the user has confirmed the skip, with the outcome SKIPPED and no results. Either way an event is written on the timeline recording who submitted it and when, so the log always answers whether the work was tested. Unlike an answer, the submit is not limited to the states of the work, so a service order that goes straight from NOT_STARTED to READY_FOR_PICKUP still records its checklist.\nWith the outcome COMPLETED the event records a result for every item on the job type's checklist: the request's result where it carries one, and otherwise the answer the item holds on the service order, given during the work through put-serviceorders-checklist-answers. A request that leaves an item with neither is refused with a 400. The request's results are stored as those items' answers, attributed to the person submitting, so the service order's checklistAnswers read what the event records; a result equal to the answer the item already holds keeps who gave it and when. SKIPPED stores no answer and leaves the stored answers as they are.\nThe items and their results are snapshotted on the event, so editing the job type's checklist afterwards does not change what was recorded. The created event is returned.\nThe call is idempotent on serviceEventUid: generate the uid before the first attempt and reuse it on every retry. A repeat with a uid that is already on the timeline writes nothing and returns the event already written.\nWhich checklists are still outstanding is read off the timeline rather than kept as a flag: they are the job types the service order carries, minus the ones a CHECKLIST_COMPLETED or CHECKLIST_SKIPPED event already names in its serviceJobTypeUid. Nothing is outstanding when every job type on the service order has an event of either kind.\nThis is a write on the case, so it belongs to the store that owns the service order: at any other store it is refused with a 403, where the case can be read but not worked on.\n\nRequired permissions: SERVICE_ORDER","responses":{"201":{"$ref":"#/components/responses/ServiceEventResponse"}},"requestBody":{"$ref":"#/components/requestBodies/ServiceOrderChecklistSubmitRequest"},"tags":["Service"]}}}}
```


---

# 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/submit-service-order-checklist.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.
