> 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-the-tenants-service-settings.md).

# Update the tenant's service settings

Change the tenant-wide service settings. Every field is optional and a field left out keeps its value, so a client sends only what it changes; the full settings are returned, exactly as the read returns them. A termsUrl that is neither empty nor an absolute http\:// or https\:// address naming a host is refused with a 400, and nothing is saved. A serviceAccentColor that is neither empty nor a # followed by six hex digits is refused with a 400, and nothing is saved. A serviceBannerExpiresAt that is not later than the server's clock when the update is handled is refused with a 400, and nothing is saved, unless serviceBannerText is or becomes empty. Configuring the service module is separated from working on the service orders that run through it: this is a configuration write and asks for SERVICE\_CONFIG, while reading asks for any service permission.

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":{"ServiceSettingsResponse":{"description":"Example response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceSettingsResponseSchema"}}}}},"schemas":{"ServiceSettingsResponseSchema":{"title":"ServiceSettingsResponseSchema","description":"The tenant-wide settings of the service module: the lock-screen regime, the portal link lifetime, the status a new service order starts on, the messaging kill switch, the staff banner and when it stops being shown, the accent color the web app and the service portal are drawn in, and the terms and conditions customers accept. They are service configuration — written under SERVICE_CONFIG through the service settings operation, never through the tenant itself — and read under any service permission, by whoever works service or configures it.","type":"object","required":["tenantUid","requirePinCodeForService","servicePortalTokenExpiryDays","serviceMessagesPaused","serviceDefaultStartStatusUid","serviceBannerText","serviceBannerExpiresAt","serviceAccentColor","termsText","termsUrl","termsAcceptanceRequired"],"properties":{"tenantUid":{"$ref":"#/components/schemas/UID"},"requirePinCodeForService":{"type":"boolean","description":"When it is on, the service part of the web app locks between users. Each person unlocks it with their own user id and PIN through the tenant user verify-pin operation, which checks the PIN server-side and answers an unlock token for that person. The app sends the unlock token as the bearer on everything that follows, so the caller of every request is the person the platform authenticated: everything they do on a service order is attributed to them on the timeline and in the audit entries and judged on their own permissions, never on a uid a client chose to send.\nThe screen account, the login the screen itself is signed in with, is used only while the screen is locked. It is not a person and never stands in for one: every timeline entry written under an unlock token records it as screenAccountTenantUserUid, beside the person who did the work.\nRevealing a secret on a service order verifies the PIN again every time, whatever the lock screen has already established."},"servicePortalTokenExpiryDays":{"type":"integer","description":"How many days a service portal link keeps working after the service order has reached a terminal state, COMPLETE or CANCELLED. It is what keeps the pickup and completion messages useful: the link in them opens a live page on a case that is already finished. 0 means the links die at the terminal state."},"serviceMessagesPaused":{"type":"boolean","description":"The kill switch for outbound service messages. While it is on, every message the service module would send the customer for this tenant is stopped, on any channel and from any store.\nThe two kinds of send stop differently. The automatic sends a status rule fires are held: they wait, and are then subject to the staleness rule when the switch is turned off again, so a message whose service order has moved on to another status in the meantime is recorded as skipped rather than reaching the customer about a status the case has left. Everything a person asks for is refused up front instead — a timeline event that names a channel to tell the customer on, a message sent by hand from a service order, a resend, a quote that names a channel to send the offer on, and a portal link regeneration that carries a resend — so nothing that is not tied to a status ever waits in the queue for a moment that has no meaning left.\nIt is meant for the day something is wrong — a template that says the wrong thing, a provider misbehaving — and is turned on and off by the service admin."},"serviceDefaultStartStatusUid":{"type":"string","nullable":true,"pattern":"^[A-Za-z0-9-_]+","description":"The status a new service order starts on when the create request names none. It is one of the tenant's statuses that is not deprecated, whose state is AWAITING_PRODUCT or NOT_STARTED, or null when the tenant has not chosen one; then the fallback is the tenant's one NOT_STARTED status that is not deprecated, and a create that names no status is refused with a 400 unless the tenant has exactly one such status. A status whose state is AWAITING_PRODUCT is never the fallback."},"serviceBannerText":{"type":"string","description":"A notice the service admin has written for their own staff, shown to service staff on the service screens of every store in the tenant — the one place to say something that everybody working service is to read, such as that a supplier is closed for the week. A store's own banner, serviceBannerText in that store's service settings, is shown beside it at that store. An empty string means there is no banner and nothing is shown, and it is what is served once the banner has ended (serviceBannerExpiresAt).\nIt is plain text and is to be rendered as plain text: no markup, no links, no formatting. Nothing follows from it beyond being shown — it filters nothing, blocks nothing, and never reaches the customer."},"serviceBannerExpiresAt":{"type":"string","format":"date-time","nullable":true,"description":"The moment the banner stops being shown, or null when it is shown until somebody takes it down. It is null whenever serviceBannerText is empty. A moment that reads 23:59:59 in the tenant's timezone is the end of that day and is shown as such, as readyAtEstimate is; any other moment is shown as its day and time.\nThe banner ends by itself: a read at this moment or later serves serviceBannerText as an empty string and this as null, exactly as if the banner had been taken down. A client shows the banner it reads, and drops an ended one at its next read. A client may also take a banner on show down when its own clock reaches this moment, so a banner set to end at noon is gone at noon from a screen nobody has touched. Nothing is written when it ends; the next update starts from the settings as served."},"serviceAccentColor":{"type":"string","description":"The tenant's own accent color, as a # followed by six lowercase hex digits, such as #f97316: the color the Flow Service web app and the service portal draw their buttons, links and highlights in for this tenant, in place of their default. An empty string when the tenant has not chosen one, and the clients then use their default accent color. The service portal and the counter signing page carry it as accentColor.\nOnly the color itself is stored. Its lighter and darker shades, and whether text drawn on it is black or white, are derived from it by the client, so that any color stays readable. Nothing the server renders is colored by it — the service papers, the intake slip and the e-mails and text messages to the customer never carry it — and status chips keep their own colors."},"termsText":{"type":"string","description":"The tenant's terms and conditions — the wording the customer accepts when a device is taken in. It is the same for every store and every service type; a service type may add to it with its additionalTermsText, never replace it. Shown to the customer in the service portal and on the counter signing page, and printed on the service confirmation.\nEvery service order is created with the wording in force at that moment and keeps it: saving a changed text records a new version, which applies to the service orders created from then on and changes nothing on the ones that exist. An empty string when the tenant has no terms text; then, unless termsUrl is set or a service type adds some, service orders have no terms, nothing is shown or asked, and no acceptance can be recorded.\nIt is written in the terms format, the one format of every terms text in this API: this field, a service type's additionalTermsText, and the termsText a service order, an acceptance, the portal page and the signing page carry. Flow stores and returns the text exactly as written, markers included; a client that shows it renders the format, and the service confirmation prints it rendered. In the format a space is the space character, a tab or a no-break space (U+00A0), and nothing else. The format:\n- `**text**` is bold and `*text*` is italic. Asterisks are read in runs: a run of one marks italic, a run of two bold, a run of three bold and italic together, and a run of four or more is literal text. A marker opens only when the character after it is not a space and closes only when the character before it is not a space, and it pairs only with a marker of the same run length on the same line. Reading from left to right, a marker that can open and is not yet paired pairs with the first unpaired marker after it that can close it — and, when it sits inside a stretch, only with one before that stretch's end. One stretch may sit inside another — italic inside bold, bold inside italic — and a marker left without a partner is literal text, so the rendered stretches always nest.\n- A line whose first characters other than spaces are `-` or `•`, followed by one or more spaces and then a character that is not a space, is a bullet item; its text is the rest of the line after the marker and the spaces following it. Bold and italic work inside an item. Consecutive bullet lines form one list, and indentation never nests one list in another. An asterisk never marks a bullet.\n- A blank line — empty or holding only spaces — ends a paragraph or a list; several in a row are one break, and blank lines at the start and the end are dropped. A single line break inside a paragraph is kept as a line break. A bullet line directly after a line of text ends that paragraph, and a line of text directly after a bullet line ends the list and starts a new paragraph. `\\r\\n` is one line break, and so is a lone `\\r`, as `\\n` is; nothing else is a line break.\n- Everything else is literal text, always HTML-escaped where it is rendered as HTML: no HTML, no links, no headings, no other markdown, and no escape character — a backslash is shown as typed, and a URL is plain text, never a link, with markers inside it read as anywhere else. Other spaces render as HTML renders them: a run of spaces and tabs shows as one and a line's leading spaces and tabs are not shown, while a no-break space always shows. Every string is valid: nothing is validated, and an unmatched marker is never an error."},"termsUrl":{"type":"string","description":"Where the tenant publishes their terms, for a tenant who keeps the wording on their own website — shown to the customer as a link alongside termsText and printed on the service confirmation and the intake slip. A service order keeps the URL in force when it was created, the same way it keeps the text; what the page behind the URL says later is not recorded. An empty string when there is none. A URL alone counts as terms: service orders created with it have terms to accept even when termsText is empty."},"termsAcceptanceRequired":{"type":"boolean","description":"Whether the customer has to accept the terms before work starts. While it is on, every status change into the state IN_PROGRESS on a service order that has terms is refused until a standing acceptance exists on it — not only the first: a service order that has left IN_PROGRESS does not come back in without one, and a service order already in work is never un-started by a void. Moving a status itself into IN_PROGRESS is a configuration change and is never held: the service orders on it move whether or not their terms have been accepted. A service order without terms is never held.\nIt asks for an acceptance, not a signature: a tap in the service portal satisfies it exactly as a signature drawn at the counter or an acceptance recorded by staff in the store does. It applies immediately, to the service orders that exist as well as to new ones, and while it is off the terms are still shown and an acceptance can still be recorded — nothing waits on it."}}},"UID":{"title":"UID","type":"string","pattern":"^[A-Za-z0-9-_]+"},"ServiceSettingsUpdateRequestSchema":{"title":"ServiceSettingsUpdateRequestSchema","description":"The tenant-wide service settings to change. Every field is optional: a field left out keeps its value, so a client sends only what it changes. The terms and conditions are among them: a changed text or URL is recorded as a new version that the service orders created from then on carry.","type":"object","properties":{"requirePinCodeForService":{"type":"boolean","description":"When it is on, the service part of the web app locks between users. Each person unlocks it with their own user id and PIN through the tenant user verify-pin operation, which checks the PIN server-side and answers an unlock token for that person. The app sends the unlock token as the bearer on everything that follows, so the caller of every request is the person the platform authenticated: everything they do on a service order is attributed to them on the timeline and in the audit entries and judged on their own permissions, never on a uid a client chose to send.\nThe screen account, the login the screen itself is signed in with, is used only while the screen is locked. It is not a person and never stands in for one: every timeline entry written under an unlock token records it as screenAccountTenantUserUid, beside the person who did the work.\nRevealing a secret on a service order verifies the PIN again every time, whatever the lock screen has already established."},"servicePortalTokenExpiryDays":{"type":"integer","description":"How many days a service portal link keeps working after the service order has reached a terminal state, COMPLETE or CANCELLED. It is what keeps the pickup and completion messages useful: the link in them opens a live page on a case that is already finished. Send 0 to have the links die at the terminal state."},"serviceMessagesPaused":{"type":"boolean","description":"The kill switch for outbound service messages. Send true to stop every message the service module would send the customer for this tenant, on any channel and from any store.\nThe two kinds of send stop differently. The automatic sends a status rule fires are held: they wait, and are then subject to the staleness rule when the switch is turned off again, so a message whose service order has moved on to another status in the meantime is recorded as skipped rather than reaching the customer about a status the case has left. Everything a person asks for is refused up front instead — a timeline event that names a channel to tell the customer on, a message sent by hand from a service order, a resend, a quote that names a channel to send the offer on, and a portal link regeneration that carries a resend — so nothing that is not tied to a status ever waits in the queue for a moment that has no meaning left.\nIt is meant for the day something is wrong — a template that says the wrong thing, a provider misbehaving — and is turned on and off by the service admin."},"serviceDefaultStartStatusUid":{"type":"string","nullable":true,"pattern":"^[A-Za-z0-9-_]+","description":"The status a new service order is to start on when the create request names none. It must be one of the tenant's statuses that is not deprecated and whose state is AWAITING_PRODUCT or NOT_STARTED; any other value is refused with a 400, the empty string among them. Send null to clear the setting — that is the only way to clear it — after which the fallback is the tenant's one NOT_STARTED status that is not deprecated, and a create that names no status is refused with a 400 unless the tenant has exactly one such status. A status whose state is AWAITING_PRODUCT is never the fallback. Left out, it keeps its value."},"serviceBannerText":{"type":"string","description":"A notice the service admin writes for their own staff, shown to service staff on the service screens of every store in the tenant — the one place to say something that everybody working service is to read, such as that a supplier is closed for the week. Send an empty string to take the banner down, which also clears serviceBannerExpiresAt. Left out, it keeps the value the read serves; an update applies to the banner as the read serves it (serviceBannerExpiresAt).\nIt is plain text and is rendered as plain text: no markup, no links, no formatting. Nothing follows from it beyond being shown — it filters nothing, blocks nothing, and never reaches the customer."},"serviceBannerExpiresAt":{"type":"string","format":"date-time","nullable":true,"description":"The moment the banner is to stop being shown. The client turns the day and time the user picks, in the tenant's timezone, into this moment: 12:00 today to have it shown until noon. A day picked without a time is sent as 23:59:59 on that day in the tenant's timezone, as for readyAtEstimate, to have it shown for the whole of that day. The tenant's timezone is timezone on the tenant, Europe/Oslo when none is set, as readyAtEstimate on the service order states. Any UTC offset is accepted and means the same moment. Send null to have it shown until somebody takes it down. Left out, it keeps its value.\nA moment that is not later than the server's clock when the update is handled is refused with a 400 and nothing is saved, unless serviceBannerText is or becomes empty: a moment that is not kept is not judged. The client's clock picks the moment and the server's clock judges it, so a moment a browser running behind still sees ahead can be refused.\nAn update applies to the settings as the read serves them. A serviceBannerText sent without serviceBannerExpiresAt keeps the moment the read serves: a banner edited while it is shown still ends at its moment, and a text sent after the banner has ended is shown until it is taken down rather than ending at once at the old moment. A moment sent while serviceBannerText is or becomes empty is not kept: the update is accepted and serviceBannerExpiresAt is served as null. After the banner has ended, an update that sends serviceBannerExpiresAt without serviceBannerText, null included, leaves the banner down; the ended text never comes back. An update that sends serviceBannerText or serviceBannerExpiresAt saves both, exactly as the response then serves them, so nothing of an ended banner stays behind to come back."},"serviceAccentColor":{"type":"string","description":"The tenant's own accent color for the Flow Service web app and the service portal, as a # followed by six hex digits, such as #f97316. Uppercase and lowercase letters are both accepted, and the color is stored and answered in lowercase. Send an empty string to go back to the clients' default accent color. A value that is neither empty nor a # followed by six hex digits is refused with a 400 and nothing is saved, a value with surrounding spaces among them. Left out, it keeps its value."},"termsText":{"type":"string","description":"The tenant's terms and conditions as they are to read from now on, in the terms format that termsText in the service settings describes, stored exactly as written, markers included. When the text differs from the one in force, Flow records a new version and the service orders created from then on carry it; the service orders that already exist keep the wording they were created under, and nothing is re-asked. Sending the same text again records nothing.\nSend an empty string to have no terms text: service orders created from then on have no terms unless termsUrl is set or their service type adds some. Left out, it keeps its value."},"termsUrl":{"type":"string","description":"Where the tenant publishes their terms, for a tenant who keeps the wording on their own website. It is an absolute address starting with http:// or https:// and naming a host, because it is printed on the service papers and opened by the customer as a link from the portal and the signing page; any other value is refused with a 400 and nothing is saved. Surrounding spaces are trimmed before it is judged, and the trimmed address is what is stored. A changed URL is a new version the same way a changed text is, and existing service orders keep the URL they were created with. Send an empty string to have no URL. Left out, it keeps its value."},"termsAcceptanceRequired":{"type":"boolean","description":"Whether the customer has to accept the terms before work starts. Send true to have every status change into IN_PROGRESS on a service order that has terms refused until a standing acceptance exists on it — re-entry included, and a service order already in work is never un-started by a void. It applies immediately, to the service orders that exist as well as to new ones. Moving a status itself into IN_PROGRESS is a configuration change and is never held: the service orders on it move whether or not their terms have been accepted. A service order without terms is never held.\nIt asks for an acceptance, not a signature: a tap in the service portal satisfies it exactly as a signature drawn at the counter or an acceptance recorded by staff in the store does. Left out, it keeps its value."}}}},"requestBodies":{"ServiceSettingsUpdateRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceSettingsUpdateRequestSchema"}}}}}},"paths":{"/tenants/{tenantUid}/serviceorders/settings":{"put":{"summary":"Update the tenant's service settings","operationId":"put-serviceorders-settings","description":"Change the tenant-wide service settings. Every field is optional and a field left out keeps its value, so a client sends only what it changes; the full settings are returned, exactly as the read returns them.\nA termsUrl that is neither empty nor an absolute http:// or https:// address naming a host is refused with a 400, and nothing is saved.\nA serviceAccentColor that is neither empty nor a # followed by six hex digits is refused with a 400, and nothing is saved.\nA serviceBannerExpiresAt that is not later than the server's clock when the update is handled is refused with a 400, and nothing is saved, unless serviceBannerText is or becomes empty.\nConfiguring the service module is separated from working on the service orders that run through it: this is a configuration write and asks for SERVICE_CONFIG, while reading asks for any service permission.\n\nRequired permissions: SERVICE_CONFIG","responses":{"200":{"$ref":"#/components/responses/ServiceSettingsResponse"}},"tags":["Service"],"requestBody":{"$ref":"#/components/requestBodies/ServiceSettingsUpdateRequest"}}}}}
```


---

# 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-the-tenants-service-settings.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.
