Skip to main content
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 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: Auth: merchant dashboard JWT (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

string
required
UUID of the app installation to write.
object
required
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), under data.settings, in the standard platform envelope.
integer
HTTP status code (200 on success).
string
"success" or "error".
object
The stored bag, post-coercion.

Replace semantics

Because the write is a full replace, any key you omit is dropped:
To change one key while keeping the rest, read the current bag, merge in your change, and send the full object.

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