> ## Documentation Index
> Fetch the complete documentation index at: https://docs.launchmystore.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Update App Settings

> Replace a single app installation's per-merchant settings bag.

Writes the app's per-installation settings bag (see
[Get App Settings](/api-reference/app-settings/get) 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 type | Coercion applied                                |
| ----------------- | ----------------------------------------------- |
| `number`          | `Number(value)`; empty string / `null` → `null` |
| `toggle`          | `Boolean(value)`                                |
| anything else     | `String(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

<ParamField path="installationId" type="string" required>
  UUID of the app installation to write.
</ParamField>

<ParamField body="settings" type="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.
</ParamField>

```bash theme={null}
curl -X PUT "https://api.launchmystore.io/apps/installations/<INSTALLATION_ID>/settings" \
  -H "Authorization: Bearer <MERCHANT_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "enabled": true,
      "free_shipping_min": 7500
    }
  }'
```

## Response

The response returns the bag exactly as stored (after type coercion), under
`data.settings`, in the standard platform envelope.

<ResponseField name="status" type="integer">HTTP status code (`200` on success).</ResponseField>
<ResponseField name="state" type="string">`"success"` or `"error"`.</ResponseField>
<ResponseField name="data.settings" type="object">The stored bag, post-coercion.</ResponseField>

```json theme={null}
{
  "status": 200,
  "state": "success",
  "message": null,
  "data": {
    "settings": {
      "enabled": true,
      "free_shipping_min": 7500
    }
  },
  "count": null,
  "pagination": null
}
```

***

## Replace semantics

Because the write is a full replace, any key you omit is dropped:

```json theme={null}
// Before
{ "enabled": true, "free_shipping_min": 5000 }

// PUT body
{ "settings": { "free_shipping_min": 7500 } }

// After  ← "enabled" is GONE
{ "free_shipping_min": 7500 }
```

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

| 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`).                     |