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:
Schema field typeCoercion applied
numberNumber(value); empty string / nullnull
toggleBoolean(value)
anything elseString(value); null / undefined""
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

installationId
string
required
UUID of the app installation to write.
settings
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.
status
integer
HTTP status code (200 on success).
state
string
"success" or "error".
data.settings
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

CodeDescription
400A key in settings is not declared in the app’s settings schema (Unknown setting key: <key>).
401Missing or invalid merchant JWT.
404No installation with this installationId on the caller’s store.
404The app has no settings schema declared (This app has no settings schema).