Update App Settings
App Settings
Update App Settings
Replace a single app installation’s per-merchant settings bag.
PUT
Update App Settings
Writes the app’s per-installation settings bag (see
Get App Settings for the model).
Write mode is full-replace. Every call overwrites the entire bag with the
keys you send — there is no shallow-merge default, no
Auth: merchant dashboard JWT (
To change one key while keeping the rest, read the current bag, merge in your
change, and send the full object.
replace flag, and no
null-key-delete behaviour. To preserve existing keys, read the bag first,
apply your change, and send the complete object back.
Keys are not an arbitrary JSON bag. Every key you send must be declared in
the app’s settings schema (the settings array in the app’s extensions
manifest). Unknown keys are rejected. Values are type-coerced by the
schema field’s declared type before being stored:
| Schema field type | Coercion applied |
|---|---|
number | Number(value); empty string / null → null |
toggle | Boolean(value) |
| anything else | String(value); null / undefined → "" |
MERCHANT or STAFF_ADMIN role). The
storeId is resolved from the token; the installation is identified by the
:installationId path param. There is no write_settings_own OAuth scope and
no /api/v1 per-installation settings route.
Request
UUID of the app installation to write.
The settings to write. Each top-level key must be declared in the app’s
settings schema; unknown keys are rejected. The whole bag is replaced with
this object.
Response
The response returns the bag exactly as stored (after type coercion), underdata.settings, in the standard platform envelope.
HTTP status code (
200 on success)."success" or "error".The stored bag, post-coercion.
Replace semantics
Because the write is a full replace, any key you omit is dropped:Concurrency
Writes are last-writer-wins; there is no optimistic-locking token. The bag is normally written from a single admin UI session, so races are rare.Error codes
| Code | Description |
|---|---|
400 | A key in settings is not declared in the app’s settings schema (Unknown setting key: <key>). |
401 | Missing or invalid merchant JWT. |
404 | No installation with this installationId on the caller’s store. |
404 | The app has no settings schema declared (This app has no settings schema). |