> 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/update-service-status-message-rule.md).

# Update service status message rule

Update a status message rule: the channel it sends on, the template it sends, and whether it sends at all. The status it fires on cannot be changed — create a rule on the other status instead. The change takes effect for status changes from now on and never touches messages already sent. Switching a rule off with active is what stops a message without losing the template it points at.

Required permissions: SERVICE\_CONFIG

```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":{"ServiceStatusRuleResponse":{"description":"Example response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceStatusRuleResponseSchema"}}}}},"schemas":{"ServiceStatusRuleResponseSchema":{"title":"ServiceStatusRuleResponseSchema","description":"A rule that sends the customer a message when a service order arrives at a status. Telling the customer is the point of the module: they are told their service order was registered and given the link that follows it, and told again at every step the tenant chooses to speak at.\nOne rule is one status, one channel and one template. Two rules on the same status reach the customer on both channels; a status with no rules passes silently.\nWhen a rule fires: after the status change has been committed, never inside it — a message that cannot be sent never holds up or undoes the work on the service order. One status change fires a rule at most once, enforced in the database rather than trusted to the sender, so a retried or concurrent transition cannot send the same message twice. Arriving at a status the service order has been in before sends again: it is a new arrival, and the customer is told about it. A rule never fires for status changes that happened before the rule existed.\nA message that has not gone out yet when the service order has already moved on to another status is not sent late: the execution is recorded as skipped instead of telling the customer about a status the case has already left.\nA rule on the status a service order is created in fires on creation too. That is the registration message carrying the portal link, and it is how the customer comes to have the link at all.\nAn e-mail rule carries a service paper as a PDF attachment when attachDocumentType names one — for example the service confirmation on the registration e-mail, or the service summary on the ready-for-pickup e-mail; any EMAIL rule may carry either. The paper is rendered when the message is composed, just before it goes out, so a message held while serviceMessagesPaused was on carries the paper as the case stands when it is sent. A paper that cannot be rendered does not hold the message back: the e-mail goes out without the attachment, its text and the portal link still reach the customer, and the notification log records that the paper could not be attached.\nWhat became of the message is recorded in the notification log, which stays the authority on delivery. When the provider's answer is ambiguous — the message may or may not have gone out — the attempt is recorded and flagged for a person to look at, never blindly retried.","type":"object","required":["serviceStatusRuleUid","tenantUid","serviceStatusUid","messageType","templateType","attachDocumentType","active","createdAt","createdBy","lastModifiedAt","lastModifiedBy"],"properties":{"serviceStatusRuleUid":{"$ref":"#/components/schemas/UID"},"tenantUid":{"$ref":"#/components/schemas/UID"},"serviceStatusUid":{"description":"The status whose arrival fires the rule. It is set when the rule is created and never changes — a rule for another status is another rule.","type":"string","pattern":"^[A-Za-z0-9-_]+"},"messageType":{"description":"The channel the message goes out on, and the channel the rule's templateType names where that type names one. The customer on the service order needs a contact point for it: a rule with nothing to send to records the failure in the notification log and leaves the status change as it is.","allOf":[{"$ref":"#/components/schemas/MessageTypeENUM"}]},"templateType":{"type":"string","description":"The template to send, by its type — a service template type the tenant has created itself, and one the tenant has text for. The platform's own types, listed on the `/metadata/templates` endpoint, are written around a sales order and its product lines, which a service order has none of, so naming one here is refused with a 400. The text is the tenant's own, written once per language; which wording the customer reads is resolved when the message is composed: the language they prefer, otherwise the tenant's own. A service template always carries a language, and the tenant's own version is the floor a type must have — a type without it has no text to fall back to."},"attachDocumentType":{"nullable":true,"description":"The service paper the message carries as a PDF attachment, or null for none, which is how a rule starts. Only an EMAIL rule carries one, and the paper is INTAKE_CONFIRMATION or SERVICE_SUMMARY. It is rendered when the message is composed, just before it goes out, exactly as the printable paper renders at that moment — except that an e-mailed paper never prints the blank signature line: where no acceptance stands, the confirmation prints the terms and nothing under them, and a standing acceptance prints as it does on paper. It is rendered in the customer's preferred language and in the tenant's where the customer has none, it never carries photos, and the PDF is named with the paper's localized name and the service number. A paper that cannot be rendered does not hold the message back: the e-mail goes out without it, and the notification log records that the paper could not be attached.","allOf":[{"$ref":"#/components/schemas/ServiceOrderDocumentTypeENUM"}]},"active":{"type":"boolean","description":"An inactive rule stays configured and sends nothing. It is how a message is switched off for a while without losing the template it points at."},"createdAt":{"type":"string","format":"date-time"},"createdBy":{"type":"string"},"lastModifiedAt":{"type":"string","format":"date-time"},"lastModifiedBy":{"type":"string"}}},"UID":{"title":"UID","type":"string","pattern":"^[A-Za-z0-9-_]+"},"MessageTypeENUM":{"title":"MessageTypeENUM","type":"string","enum":["EMAIL","SMS"]},"ServiceOrderDocumentTypeENUM":{"title":"ServiceOrderDocumentTypeENUM","description":"Which of the three printable service papers is meant. It is never derived from the state of the case — the caller names it, or the tenant names it on a status rule.\nINTAKE_CONFIRMATION: the service confirmation, for the customer, handed across the counter at intake — the record of what was handed in, and the sheet the customer can sign where the terms are accepted in the store. SERVICE_SUMMARY: the service summary, for the customer, handed back with the unit when the work is done — the record of what was done. DAMAGE_REPORT: the damage report, written for a third party — an insurer, a manufacturer, or a seller in a complaint — carrying the unit, the coverage, the findings, the customer-visible photos the caller names and the price of the work, and nothing of the dialogue between the customer and the store.\nAny of the three can be asked for at any time and under any coverage.","type":"string","enum":["INTAKE_CONFIRMATION","SERVICE_SUMMARY","DAMAGE_REPORT"]},"ServiceStatusRuleUpdateRequestSchema":{"title":"ServiceStatusRuleUpdateRequestSchema","description":"The editable parts of a status message rule: which channel it sends on, which template it sends, which service paper an e-mail carries attached, and whether it sends at all.\nThe status the rule fires on is not among them — it is fixed when the rule is created. Editing a rule changes what is sent from now on and never touches the messages already sent.","type":"object","required":["messageType","templateType"],"properties":{"messageType":{"description":"The channel the message goes out on. It must be the channel the templateType names: a service template type begins with SMS_ or EMAIL_ and so always names one, and a rule whose channel is not that one is refused with a 400.","allOf":[{"$ref":"#/components/schemas/MessageTypeENUM"}]},"templateType":{"type":"string","description":"The template to send, by its type — a service template type the tenant has created itself, and one the tenant has text for; the language is resolved per customer when the message is composed and is not chosen here. The platform's own types are written around a sales order and are refused here with a 400. EMAIL_SERVICE_DOCUMENT_SENT, the text written to accompany a paper, is accepted only on a rule whose attachDocumentType names a paper; on a rule that attaches none it is refused with a 400. That is judged on the rule as it stands after the update, so taking the paper off a rule that uses that type is refused unless the same request changes the type too. SMS_SERVICE_ORDER_UPDATED and EMAIL_SERVICE_ORDER_UPDATED are refused with a 400: they carry the message staff write, which a rule has none of."},"attachDocumentType":{"nullable":true,"description":"The service paper to attach to the message as a PDF, rendered when the message is composed, just before it goes out, and never with photos. INTAKE_CONFIRMATION and SERVICE_SUMMARY are accepted; DAMAGE_REPORT is refused with a 400, being the paper for a third party, and so is a rule that would carry a paper while its messageType is not EMAIL. That is judged on the rule as it stands after the update: switching messageType to SMS on a rule that carries a paper is refused unless the same request sets attachDocumentType to null. On an update, left out, the rule keeps what it has, and null takes the paper off. On a create, left out or null, the rule attaches no paper.","allOf":[{"$ref":"#/components/schemas/ServiceOrderDocumentTypeENUM"}]},"active":{"type":"boolean","description":"Send false to switch the rule off while keeping it configured, and true to switch it back on. Left out, the rule keeps what it has."}}}},"requestBodies":{"ServiceStatusRuleUpdateRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceStatusRuleUpdateRequestSchema"}}}}}},"paths":{"/tenants/{tenantUid}/serviceorders/statusrules/{serviceStatusRuleUid}":{"put":{"summary":"Update service status message rule","operationId":"put-serviceorders-statusrules","description":"Update a status message rule: the channel it sends on, the template it sends, and whether it sends at all. The status it fires on cannot be changed — create a rule on the other status instead.\nThe change takes effect for status changes from now on and never touches messages already sent. Switching a rule off with active is what stops a message without losing the template it points at.\n\nRequired permissions: SERVICE_CONFIG","responses":{"200":{"$ref":"#/components/responses/ServiceStatusRuleResponse"}},"tags":["Service"],"requestBody":{"$ref":"#/components/requestBodies/ServiceStatusRuleUpdateRequest"}}}}}
```


---

# 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/update-service-status-message-rule.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.
