Get App Settings
App Settings
Get App Settings
Read a single app installation’s per-merchant settings bag.
GET
Get App Settings
Every installed app has a private settings bag scoped to one merchant
installation. It persists per-store configuration — feature toggles, default
templates, values the merchant entered into the app’s settings UI, etc. —
without the app standing up its own database.
The settings bag is a single JSON object stored on the installation:
No query parameters.
If the installation does not exist (or is not on the caller’s store), the
endpoint returns the error envelope:
To prepopulate settings, write them via
Update App Settings. Only keys declared
in the app’s settings schema can be written.
- Values can be any JSON type. The shape is the app’s own concern.
- Stored per installation — each (app, store) pair has its own bag.
- A fresh install that has never been written returns an empty object
{}.
MERCHANT or STAFF_ADMIN role). The
storeId is resolved from the token and the installation is looked up by the
:installationId path param scoped to that store — a merchant can only read
the settings of installations on their own store.
This is a merchant/admin endpoint, not an app-facing OAuth endpoint.
There is no
read_settings_own scope and no per-installation settings route
under /api/v1. The only /api/v1 settings endpoints are store-level
(storefront config — name, country, payment providers); see
Get settings.Request
UUID of the app installation whose settings bag you want to read.
Response
Responses use the standard platform envelope (status / state / message
/ data). The settings bag is returned under data.settings.
HTTP status code (
200 on success)."success" or "error".The settings bag. Empty object
{} for fresh installs that have never
written anything.Example response
Reading specific keys
There is no per-key endpoint — fetch the bag and read the keys you need client-side.Defaults
If a key has never been written, it is absent fromdata.settings — not
returned as null. Set defaults in your own code when reading:
Error codes
| Code | Description |
|---|---|
401 | Missing or invalid merchant JWT. |
404 | No installation with this installationId on the caller’s store. |