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

installationId
string
required
UUID of the app installation whose settings bag you want to read.
No query parameters.

Response

Responses use the standard platform envelope (status / state / message / data). The settings bag is returned under data.settings.
status
integer
HTTP status code (200 on success).
state
string
"success" or "error".
data.settings
object
The settings bag. Empty object {} for fresh installs that have never written anything.

Example response

If the installation does not exist (or is not on the caller’s store), the endpoint returns the error envelope:

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 from data.settings — not returned as null. Set defaults in your own code when reading:
To prepopulate settings, write them via Update App Settings. Only keys declared in the app’s settings schema can be written.

Error codes

CodeDescription
401Missing or invalid merchant JWT.
404No installation with this installationId on the caller’s store.