Override a branded string

Replaces the wording of one customer-facing string for a branding and a language, so that the hosted checkout, the receipt, the merchant's own screens and the messages the API returns say what the merchant wants rather than the wording Shuttle ships. Each string has an id of the form <mapping>.<key>: the part before the first dot names the set of strings a provider integration publishes (web for the hosted checkout, core for the API's own messages, country_gb for the UK address labels, and so on), and the rest is the key within it. The override is stored against the branding, so it applies to every channel that uses that branding and to every branding that inherits from it; saving the wording the string already inherits removes the override instead of storing it, which is how a string is put back to its original.

Where you can do this

Merchant View: Localisation editor (Save)

Before you start

The branding exists on the client, or default is used, which means the client's own branding.
A provider integration whose string set declares the id's prefix is installed on the client. The ids that can be overridden are whatever the installed provider integrations declare; nothing can be invented.
The language does not have to exist first. A branding's list of languages is derived from the languages it has wording saved for, so saving the first string in a language adds that language to the branding.

Inputs

Merchant View also sends its own display fields on the same object; only id, text, branding and language are read.

Rules

Checked by the API means Shuttle refuses the request however it is sent; a screen name means only that screen refuses it, and a direct API call would be accepted.

Rule	Checked by	What you see
The fields go inside a `string` object: `{"string": {... }}`. The record itself is identified by the id in the URL, not in the body	The API	VALIDATION_ERROR: "API body error: missing string object"
`branding` and `language` in the query string do not select what is written: the values on the body's `string` object do. A query `language` only chooses which language's string sets are looked up, and the sets are published in the default language	The API	(silent; the wording lands on the body's branding and language)
The part of the id before the first dot must match an installed provider integration's string set	The API	VALIDATION_ERROR: "strings mapping not found"
Wording equal to what the string already inherits is not stored: the override is removed and the string inherits again. What it is compared against is the parent branding's own wording for the same language, or, where the branding has no parent, the wording the provider integration itself ships	The API	200, and the response no longer reports the string as overriding
The wording is stored for every installed provider integration whose string set declares that prefix (a client running two versions of the same one gets both), using the internal key taken from the first of them	The API	(silent)
Merchant View offers Save only when the wording has changed, and Reset only when the string differs from what it inherits	Merchant View screen	control disabled or absent
Without that permission Merchant View also fixes the branding selector on the default branding, so a deep-linked operator can only edit the default branding's wording	Merchant View screen	selector disabled

What happens

The string reads as the new wording for that branding and language, and for every branding that inherits from it that has not overridden the same string itself. The response is 200 with the string as it now reads, including the wording it would inherit when the new value differs from it.
Sending the wording the string already inherits takes the override away rather than storing it, so the string goes back to reading as Shuttle (or the parent branding) ships it.
The change reaches the customer the next time the payment form is opened, and appears in receipts, in the merchant's own screens and in the messages the API returns from then on. A checkout session that was already created keeps the wording it was created with until it expires, a day by default, so a customer sent to a session created before the change still sees the old wording.
Saving the first string in a language adds that language to the branding; there is no separate add-language operation, and taking every override away again does not remove the language.
No webhook, email or SMS is raised by the change, and nothing notifies the merchant's other operators that the wording moved.

Who can do this

Roles: Admin only. Support has no permission recorded against a branding.
Permission keys (for clients managing permissions directly): Shuttle requires a permission recorded against the branding being changed: branding on that branding, or on the division's branding wildcard, which is what the Admin team holds; any access level satisfies it. Support, Support (read-only) and Payment Links Only hold permissions recorded against the division only, so they are refused with NO_PERMISSION ("No permissions on branding...", HTTP 403), which is what principle 1 intends: screen terminology is not a Support action. A request with no session key is refused before it reaches Shuttle (FORBIDDEN: "Invalid or missing API Key"). Merchant View gates the screen on a narrower test than the server's and can refuse an operator the server would accept.
Admin app options: none. The localisation screen and its menu entry are gated on the same branding permission, or on arriving through a deep link, in which case only the default branding can be edited.