Get the tenant's service settings
Get the tenant-wide settings of the service module: whether the service part of the web app locks between users, how long a portal link outlives a finished service order, the status a new service order starts on when the create request names none, whether outbound service messages are paused, the banner shown to service staff and when it stops being shown, the tenant's accent color, and the terms and conditions customers accept. Reading them asks for any service permission — SERVICE_ORDER or SERVICE_STORE_CONFIG at the tenant, at an organization or at any one store, or SERVICE_CONFIG, which is held at the tenant only — because every screen of the service web app, the configuration screens included, needs the lock-screen regime, the banner and the accent color. A tenant-wide ADMIN grant counts as every permission. A caller holding none of them, a user with no role assignments included, is refused with a 403. Writing them is configuration and asks for SERVICE_CONFIG.
Required permissions: SERVICE_ORDER, SERVICE_STORE_CONFIG, SERVICE_CONFIG
Access token recevied after user login with a deviceToken
Reference to a tenant.
^[A-Za-z0-9-_]+Example response
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.
^[A-Za-z0-9-_]+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. The 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. Revealing a secret on a service order verifies the PIN again every time, whatever the lock screen has already established.
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.
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. The 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. It 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.
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.
^[A-Za-z0-9-_]+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). It 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.
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. The 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.
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. Only 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.
#f97316The 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. Every 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. It 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:
**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.- 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. - 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\nis one line break, and so is a lone\r, as\nis; nothing else is a line break. - 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.
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.
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. It 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.
GET /v2/tenants/{tenantUid}/serviceorders/settings HTTP/1.1
Host: api.flowretail.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Example response
{
"tenantUid": "text",
"requirePinCodeForService": true,
"servicePortalTokenExpiryDays": 1,
"serviceMessagesPaused": true,
"serviceDefaultStartStatusUid": "text",
"serviceBannerText": "text",
"serviceBannerExpiresAt": "2026-01-01T00:00:00.000Z",
"serviceAccentColor": "#f97316",
"termsText": "text",
"termsUrl": "text",
"termsAcceptanceRequired": true
}Last updated
Was this helpful?

