For the complete documentation index, see llms.txt. This page is also available as Markdown.

Regenerate service-order portal link

Give the service order a fresh service portal link, replacing the one the customer has. This is what is done when the link has gone somewhere it should not have — forwarded on, left on a screen, sent to the wrong number. The old link stops working the moment the new one is made, and so does every document link its portal page carried: anyone still holding one gets nothing, apart from a document already opened in the last five minutes, and the customer needs the new one to follow their case again. Nothing else about the service order changes and the case keeps its history. The updated service order is returned. Name channels in notifications to send the new link to the customer straight away; send none and the link is regenerated quietly, for when the point was to cut off the old one rather than to reach the customer. Naming them is refused while the tenant setting serviceMessagesPaused is on: the old link would die with no way of delivering the new one. Naming a channel the tenant has written no text for is refused with a 400 for the same reason, and the link is not regenerated. Three further 400s are refused before the rotation, each for that same reason — the old link must never die for a message that was never going to leave. A channel the customer has no address or mobile number for is refused. An e-mail channel is refused when the store itself has no e-mail address of its own, because a recorded e-mail is sent FROM the store, so a store without one can send no e-mail at all — the rule the quote send and the message sent by hand state too. An SMS channel is refused when the store does not send SMS, which is asked of the tenant first, so a tenant whose SMS goes out under its own provider is never held to the store's extension. And regenerating at all is refused once the case has been finished for longer than the tenant keeps links alive: there is no live link left to give, and a new one would be dead before it was sent. Regenerating without them stays possible. The new link is not in the response: publicPageHash is served as an empty string here as on every other service order response, and is deprecated and on its way out. Getting the link to the customer is what this endpoint and the send endpoint are for. Which customer the new link is for is settled at the moment it is made, and a case can change hands while a request is being prepared — a customer merge repoints it, or an update moves it to someone else. When the service order has gone to a different customer by then, the request is refused with a conflict: the link is not replaced and nothing is sent, so a fresh way into the case never reaches the customer the case has just left. Retry it, and the retry is judged against the customer the service order belongs to now. 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

post
/tenants/{tenantUid}/stores/{storeUid}/serviceorders/{serviceOrderUid}/portaltoken
Authorizations
AuthorizationstringRequired

Access token recevied after user login with a deviceToken

Path parameters
tenantUidstringRequired

Reference to a tenant.

Pattern: ^[A-Za-z0-9-_]+
storeUidstringRequired

Reference to a Store.

Pattern: ^[A-Za-z0-9-_]+
serviceOrderUidstringRequired

Reference to a service order

Pattern: ^[A-Za-z0-9-_]+
Body

A request for a fresh service portal link on a service order, replacing the one the customer has. Regenerating is what is done when the link has gone somewhere it should not have — forwarded on, left on a screen, sent to the wrong number. The old link stops working the moment the new one is made, and so does every document link its portal page carried: anyone still holding one gets nothing, apart from a document already opened in the last five minutes. Nothing else about the service order changes, and the case keeps its history. Name the channels to send the new link on straight away, or send nothing and the link is regenerated quietly — for the case where the point was to cut off the old link rather than to reach the customer.

Responses
200

Example response

application/json

A service order as staff read it, with everything on the case: what came in, who is on it, what it will cost, the intake form values, the secrets by label, the job types the work consists of and the answers given on their checklists. How much of that is returned depends on where the service order is read from. This full representation is what the single service order endpoint returns, secret labels and sensitive form values included, at the store that owns the service order and at the store it was taken in at. Read at any other store of the tenant, two things are held back: secrets is an empty array, and formValues leaves out the values captured for sensitive fields. In the results of a service order search or of the store's service order list, three things are held back: secrets and checklistAnswers are always empty arrays, and formValues leaves out the values captured for sensitive fields. Read the one service order to see them: the checklist answers at any store of the tenant, the secrets and the sensitive values at the store that owns it or the store it was taken in at. It is a staff representation throughout, and the two customer-facing surfaces do not use it at all: the service portal has PortalServiceOrderResponseSchema and the customer data export has CustomerExportServiceOrderSchema, each assembled from customer-visible data of its own.

serviceOrderUidstringRequiredPattern: ^[A-Za-z0-9-_]+
tenantUidstringRequiredPattern: ^[A-Za-z0-9-_]+
storeUidstringRequired

The store that owns the service order — the store the work sits with and where the customer collects it. It changes only through the move mechanism — the move endpoint, or the receipt of a shipment item at another store — which writes a MOVED event when it does.

Pattern: ^[A-Za-z0-9-_]+
orderProductLineUidstringRequiredPattern: ^[A-Za-z0-9-_]*
orderUidstringRequiredPattern: ^[A-Za-z0-9-_]*
customerUidstringRequiredPattern: ^[A-Za-z0-9-_]*
customerNamestringRequired
createdFromStoreUidstringRequired

The store the service order was taken in at. It is set when the service order is registered and never changes afterwards, so it keeps recording where the unit was handed in however far the case travels. storeUid is the store that owns the service order now — where the work sits and where the customer collects it — so the two differ for the rest of the case once a service order has been moved between stores.

Pattern: ^[A-Za-z0-9-_]+
assignedUserUidstringRequired

The user who is to do the work on this service order. An empty string means no personal assignee: the service order is held by the store that owns it, and its notifications go to that store's service staff rather than to one person, so nothing is left waiting on somebody who is not looking at it. Assigning and unassigning happen on the service order's assign endpoint, which writes an ASSIGNED event either way. A move to another store also ends the assignment: the service order arrives at the receiving store unassigned, recorded on the MOVED event.

Pattern: ^[A-Za-z0-9-_]*
assignedUserDisplayNamestringRequired
serviceTypeUidstringRequiredPattern: ^[A-Za-z0-9-_]+
serviceTypeNamestringRequired
serviceStatusUidstringRequiredPattern: ^[A-Za-z0-9-_]+
serviceStatusNamestringRequired
serviceStatestring · enumRequired

Where a service order stands, as the platform understands it. Every status a tenant defines maps to exactly one state, and it is the state Flow reasons about: the workspace filters, the wording the portal shows the customer and the turnaround figures all follow the state rather than the name the status was given. AWAITING_PRODUCT: the service order is registered, but the device has not arrived yet. NOT_STARTED: the device is here and the work is queued. IN_TRANSIT: the service order is in a box on its way between locations. IN_PROGRESS: the work is being done. WAITING_CUSTOMER: waiting for an answer from the customer — never for the device, which is what AWAITING_PRODUCT is for. WAITING_SUPPLIER: waiting for parts or for an answer from a supplier. READY_FOR_PICKUP: the outcome is ready to be handed over. COMPLETE: the customer has the device back. This is the handover, never the payment. CANCELLED: the service order ended without a completed repair. COMPLETE and CANCELLED are the terminal states. The states are owned by the platform: tenants never define or rename them, and only decide which state each of their own statuses maps to. A status that exists today keeps the state it has until the tenant remaps it — nothing is remapped for them. Extensible — new states may be added, so clients must not fail on a value they do not know.

Possible values:
titlestringRequired
serviceNumberstringRequired
externalServiceNumberstringRequired

The number an outside workshop or supplier handling the work gives the case in its own system, such as the supplier's case number. It is never serviceNumber, and never the number of a sale: the sales order the unit was bought on is externalSalesOrderNumber.

externalSalesOrderNumberstringRequired

The order number of the sales order the unit in for service was bought on, in the tenant's external order system such as Omnium. It is the sale's number, never serviceNumber and never externalServiceNumber, and it is text alone: the sale itself is looked up in the external system. An empty string when the service order names no external sale.

descriptionstringRequired
locationLabelstringOptionalDeprecated

Deprecated. Superseded by the intake form field of system kind LOCATION_LABEL: where the device is stored while it is in the workshop is captured as a form value, and is read from formValues. Until removal it is served as a derived read-only alias of the value captured for that field, and it is an empty string when no value is captured for it. It will be removed after the announced deprecation window; see the deprecation log for the date.

prioritystring · enumRequired

HIGHEST, HIGH and LOW rank the work; NONE is no priority, which a service order carries when none was given.

Possible values:
requiresPriceEstimatebooleanOptionalDeprecated

Deprecated. Asking the customer what the work will cost before it is started is the quote: quotedPrice is the offer that was made and quoteState is how the customer answered it, both written through the quote endpoints, which record the offer and the answer rather than a flag saying one is owed. During the deprecation window it is served from the stored value on service orders registered before the change, and is false on every service order registered after it; it is no longer in the required set. It will be removed after the announced deprecation window; see the deprecation log for the date.

estimatedPriceintegerRequired

What the work is estimated to cost. It is entered at intake beside the coverage and is not an intake form field. It is 0 when no estimate has been captured.

maxPriceintegerRequired

The ceiling the customer allows the work to be done up to without being asked again. It is entered at intake beside the coverage and is not an intake form field. It is 0 when no ceiling has been captured.

readyAtEstimatestring · date-time · nullableRequired

When the work on the service order is estimated to be ready. null when no date has been given. A service order whose work is ready, on a status of the state READY_FOR_PICKUP, is not late however long it waits to be collected; the overdue filter of the service order search states the rule. The value is read on the clock in the tenant's timezone. A value that reads 23:59:59 there, whatever its milliseconds, means ready by the end of that day with no time picked, and is shown as the day and "end of day". Any other value is a picked time and is shown as the day and that time. Clients send a picked time in whole minutes, so its seconds read :00, and a picked 00:00 or 23:59 is never mistaken for the end of the day. A writer with no picked time sends 23:59:59 on the chosen day in the tenant's timezone, which is the value the service type's per-store turnaround response prefills. The tenant's timezone is the tenant's zone name — timezone on the tenant, in tz/zoneinfo format such as Europe/Oslo, which the service portal page carries as timeZone — and never a fixed offset, so a day the clocks change on reads right. The zone is Europe/Oslo when the tenant has none set. No store carries a zone of its own. The texts core writes follow the same rule: the .readyDate variable in SMS and e-mail texts, the service papers that print the expected ready time, the intake slip and the note of a FIELD_CHANGE entry for readyAtEstimate give the day and the time, or the day and "end of day", in the language the text is written in.

readyAtNeededstring · date-time · nullableOptionalDeprecated

Deprecated. The service module follows one date, readyAtEstimate; a deadline the workshop cannot control is not tracked. During the deprecation window it is served from the stored value on service orders registered before the change, and is null on every service order registered after it; it is no longer in the required set. It will be removed after the announced deprecation window; see the deprecation log for the date.

publicPageHashstringOptionalDeprecated

Deprecated. Staff surfaces never need the customer's link: sending it, sending it again and replacing it all happen server-side, through the send endpoint and the portal token endpoint, and signing at the counter has its own signing session that reaches the terms of that one service order and nothing else. Handing the customer's portal credential to every staff client is what made it leak, and there is no longer a reason to. It is served as an empty string for the whole deprecation window, and is no longer in the required set: the field stays in the response so a client that requires a string still parses, and it carries nothing. There is no value to read here — a service order's portal link reaches the customer by being sent, and by nothing else. It will be removed after the announced deprecation window; see the deprecation log for the date.

warrantybooleanOptionalDeprecated

Deprecated. Superseded by coverage, which classifies who pays for the work and under what right: warranty true is the coverage WARRANTY_CLAIM. Until removal it is served as a derived read-only alias — computed from the coverage on every read, true when the coverage is WARRANTY_CLAIM and false otherwise. It is read-only in the strict sense: the service order's write side carries no warranty at all, and the coverage is set through coverage alone. A warranty property sent on a create or an update is not a value the request carries — it changes nothing and is not refused — so a client that reads a service order and writes the body back unaltered sets no coverage by doing it. It will be removed after the announced deprecation window; see the deprecation log for the date.

createdAtstring · date-timeRequired
createdBystringRequired
lastModifiedAtstring · date-timeRequired
lastModifiedBystringRequired
rmaOrderItemUidstringRequiredPattern: ^[A-Za-z0-9-_]*
rmaOrderUidstringRequiredPattern: ^[A-Za-z0-9-_]*
intakeFormUidstringRequired

The intake form the service order was created from. It names the form rather than copying it: archiving the form afterwards leaves this uid as it is, and an edit of the form applies to the service orders created from it as well. Form values are checked against this form as it reads at the moment of the write, and an update is checked only for what it changes (formValues on the update), so a question an edit adds or makes required is asked of an existing service order only when an update clears it or sends an answer that turns it from hidden to shown. An empty string when the service order was created without an intake form.

Pattern: ^[A-Za-z0-9-_]*
quotedPriceinteger · nullableRequired

The amount of the latest quote on the service order, in the same unit as estimatedPrice and maxPrice. Where that offer stands is quoteState's job rather than this field's: null here means nothing has ever been offered. It is set only through the service order's quote endpoint, never through an ordinary update, so that offering a price always leaves a QUOTE_SENT event with the amount snapshotted. The customer's answer does not clear it: the amount stays as it is after a decision, approved or declined, until a new quote replaces it. estimatedPrice and maxPrice are separate figures and are not touched by quoting.

quoteStatestring · enumRequired

Where the latest quote on a service order stands. NONE: nothing has been offered. SENT: an offer is outstanding, waiting for the customer's answer. APPROVED: the customer accepted the latest offer. DECLINED: the customer turned it down. It is maintained solely by the quote endpoints: sending a quote sets SENT, recording a decision sets the answer that was given, and a new quote puts it back to SENT and asks again.

Possible values:
termsTextstringRequired

The terms and conditions that apply to this service order, in the terms format that termsText in the service settings describes: the tenant's terms followed by the additional terms of the service order's service type, the two separated by a blank line, each as it read when the service order was created. Editing the tenant's terms or the type's additional terms afterwards never changes it — a service order keeps the wording that was in force when it was taken in, so the printed confirmation says the same thing years later. Changing serviceTypeUid while no standing acceptance exists on the service order replaces the type's part with the new type's additional terms as in force at the change; once an acceptance exists, the text is frozen. An empty string when neither the tenant nor the type had any terms when the service order was created — service orders migrated from the old service system and orders created before any terms were saved among them — then, unless termsUrl is set, nothing is shown to the customer, no acceptance can be recorded, and termsAccepted is true.

termsUrlstringRequired

Where the tenant publishes their terms, as the URL that was in force when the service order was created — for tenants who keep the wording on their own website. Shown to the customer alongside termsText and printed on the service confirmation and the intake slip. An empty string when the tenant had no URL then. It counts as terms: a service order with a URL and no text has terms to accept.

termsAcceptedbooleanRequired

Whether the terms that apply to this service order have been accepted. It is derived, never written: true when a standing acceptance exists on the service order, whichever way it was given — in the service portal, signed on a counter device, or given in the store and recorded by staff — and true when the service order has no terms at all, termsText and termsUrl both empty, because then nothing is asked. An acceptance that has been voided satisfies nothing, so voiding the one that stood puts this back to false. It says whether the terms have been accepted, not whether acceptance is required: the tenant setting termsAcceptanceRequired decides whether a status change may move an unaccepted service order into IN_PROGRESS. Read the acceptance itself, with the terms as they read when accepted and the drawn signature where there is one, through the service order's terms acceptances endpoint.

coveragestring · enumRequired

Who pays for the work on a service order, and under what right. Every service order carries a coverage: it is chosen at intake, and it can be changed while the case runs — a diagnosis may reclassify it, as when water damage voids a warranty and the case becomes payable. PAYABLE: the customer pays. CONSUMER_CLAIM: a claim under statutory consumer rights — the seller's cost. WARRANTY_CLAIM: a claim under a warranty — the seller's or the manufacturer's cost. INSURANCE_CLAIM: a claim to an insurer — the service order names the insurer and may carry the insurer's claim number and the deductible, recorded for information. Pricing, quoting and invoicing work the same way whatever the coverage is: the sale is billed to the service order's customer on every coverage (see post-serviceorders-orders). A covered repair can still carry billable work. Extensible — new coverages may be added, so clients must not fail on a value they do not know.

Possible values:
productUidstringRequired

The product the unit in for service is — the model of the machine on the bench, so the case can be found by what came in and the serial can be read against the right product. It is captured at intake when the intake form places a field of system kind PRODUCT, which writes here rather than into the form values. This is not one of the products on the service order's items: those are the parts and the work that go on the bill. An empty string when the unit was not identified as a catalogue product.

Pattern: ^[A-Za-z0-9-_]*
insuranceCompanyCustomerUidstringRequired

The insurance company the claim is made to, as a customer record of its own. It is recorded for information: the sale is billed to the service order's customer whatever the coverage (see post-serviceorders-orders). Set it when the coverage is INSURANCE_CLAIM; an empty string otherwise. The number the insurer gave the claim is claimNumber.

Pattern: ^[A-Za-z0-9-_]*
deductibleintegerRequired

The deductible on an insurance claim, VAT included, in the same unit as estimatedPrice and maxPrice, recorded for information and printed on the service papers; it does not change how the case is billed. It is 0 when there is none, and it is above 0 only on the coverage INSURANCE_CLAIM.

claimNumberstringRequired

The number the insurer gave the claim, which the insurer matches the bill and the damage report to. It is entered beside the insurer and the deductible and is not an intake form field. An empty string when none was entered, and it is non-empty only on the coverage INSURANCE_CLAIM.

post/tenants/{tenantUid}/stores/{storeUid}/serviceorders/{serviceOrderUid}/portaltoken
POST /v2/tenants/{tenantUid}/stores/{storeUid}/serviceorders/{serviceOrderUid}/portaltoken HTTP/1.1
Host: api.flowretail.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 27

{
  "notifications": [
    "EMAIL"
  ]
}
{
  "serviceOrderUid": "text",
  "tenantUid": "text",
  "storeUid": "text",
  "orderProductLineUid": "text",
  "orderUid": "text",
  "customerUid": "text",
  "customerName": "text",
  "createdFromStoreUid": "text",
  "assignedUserUid": "text",
  "assignedUserDisplayName": "text",
  "serviceTypeUid": "text",
  "serviceTypeName": "text",
  "serviceStatusUid": "text",
  "serviceStatusName": "text",
  "serviceState": "AWAITING_PRODUCT",
  "title": "text",
  "serviceNumber": "text",
  "externalServiceNumber": "text",
  "externalSalesOrderNumber": "text",
  "description": "text",
  "priority": "HIGHEST",
  "estimatedPrice": 1,
  "maxPrice": 1,
  "readyAtEstimate": "2026-01-01T00:00:00.000Z",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "createdBy": "text",
  "lastModifiedAt": "2026-01-01T00:00:00.000Z",
  "lastModifiedBy": "text",
  "totals": {
    "goodsTotal": 1,
    "grandTotal": 1,
    "otherTotal": 1
  },
  "items": [
    {
      "serviceOrderItemUid": "text",
      "serviceOrderUid": "text",
      "warehouseUid": "text",
      "warehouseName": "text",
      "tenantUserUid": "text",
      "productUid": "text",
      "salesOrderUid": "text",
      "quantity": 1,
      "name": "text",
      "sku": "text",
      "coverImage": {
        "productMediaUid": "text",
        "mainUrl": "text",
        "thumbnailUrl": "text"
      },
      "priceOverride": true,
      "price": 1,
      "costPrice": 1,
      "originalPrice": 1,
      "discountReasonCode": "text",
      "discountReference": "text",
      "totalPrice": 1,
      "totalCostPrice": 1,
      "serialNumber": "text",
      "removedSerialNumber": "text",
      "note": "text",
      "orderItemReferenceValue": "text",
      "tenantUserDisplayName": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "createdBy": "text",
      "lastModifiedAt": "2026-01-01T00:00:00.000Z",
      "lastModifiedBy": "text"
    }
  ],
  "assets": [
    {
      "assetUid": "text",
      "name": "text",
      "description": "text",
      "isPublic": true,
      "customerVisible": true,
      "publicUrl": "text",
      "mimeType": "text",
      "size": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "createdBy": "text",
      "tenantUserUid": "text",
      "tenantUserDisplayName": "text"
    }
  ],
  "rmaOrderItemUid": "text",
  "rmaOrderUid": "text",
  "formValues": [
    {
      "serviceFormFieldUid": "text",
      "fieldKey": "text",
      "label": "text",
      "fieldType": "TEXT",
      "systemKind": "SERIAL_NUMBER",
      "sensitive": true,
      "value": "text",
      "values": [
        "text"
      ],
      "redacted": true
    }
  ],
  "intakeFormUid": "text",
  "secrets": [
    {
      "secretUid": "text",
      "serviceOrderUid": "text",
      "label": "text",
      "serviceFormFieldUid": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "createdBy": "text"
    }
  ],
  "serviceJobTypes": [
    {
      "serviceJobTypeUid": "text",
      "name": "text"
    }
  ],
  "checklistAnswers": [
    {
      "serviceJobTypeUid": "text",
      "item": "text",
      "checked": true,
      "tenantUserUid": "text",
      "tenantUserDisplayName": "text",
      "screenAccountTenantUserUid": "text",
      "answeredAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "quotedPrice": 1,
  "quoteState": "NONE",
  "termsText": "text",
  "termsUrl": "text",
  "termsAccepted": true,
  "coverage": "PAYABLE",
  "productUid": "text",
  "insuranceCompanyCustomerUid": "text",
  "deductible": 1,
  "claimNumber": "text"
}

Last updated

Was this helpful?