> ## 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 Usage Cap

> Lower the usage cap of the installation at once, or ask the merchant to approve a higher one.

The cap is the most your app may charge the merchant for usage in one billing
period. It starts at `pricing.usage.cappedAmount` and changes like Shopify's
capped-amount update:

* **Lowering** it (or setting a first cap on an uncapped install) applies at
  once. It cannot go below the usage already accrued this period.
* **Raising** it needs the merchant's approval. The request is stored as
  pending and the response carries a `confirmationUrl` — a page in the
  merchant's admin that shows the current and requested limit. The cap only
  changes when the merchant approves there. A new raise request replaces a
  pending one.

**Scope:** `write_billing`.

## Request

**cappedAmount** `number` *required*

The new cap in **major units** of the pricing currency (e.g. `40.25` =
\$40.25), rounded to two decimals. `0` stops further usage charges until the
cap is raised again.

**returnUrl** `string`

Where to send the merchant after they approve or decline. Used only when it
is an `https` URL on your App URL's origin or on the origin of one of your
registered redirect URLs; otherwise the merchant stays in their admin.

```bash theme={null}
curl -X POST "https://api.launchmystore.io/api/v1/billing/usage/cap" \
  -H "Authorization: Bearer <APP_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "cappedAmount": 100, "returnUrl": "https://my-app.example.com/billing" }'
```

### Response — applied (lowering)

```json theme={null}
{
  "status": 200,
  "state": "success",
  "data": { "requiresApproval": false, "newCap": 8, "capAmountCents": 800 }
}
```

### Response — approval required (raising)

```json theme={null}
{
  "status": 200,
  "state": "success",
  "data": {
    "requiresApproval": true,
    "confirmationUrl": "https://app.launchmystore.io/appstore/usage-cap?installationId=…&returnUrl=…",
    "currentCap": 50,
    "requestedCap": 100
  }
}
```

Open `confirmationUrl` in the top-level window (from an embedded app, use the
App Bridge `Redirect` action to the remote URL). While the request waits,
[`GET /api/v1/billing/usage`](https://docs.launchmystore.io/api-reference/app-billing/get-usage) reports
it as `pendingCapAmountCents`.

## After the merchant decides

* They are returned to `returnUrl` (when it passed the check above).
* Your app receives an
  [`app_subscriptions/update`](https://docs.launchmystore.io/api-reference/webhooks/topics) webhook with
  `reason: "usage_cap_approved"` or `"usage_cap_declined"` and the resulting
  `capAmountCents`.
* An approved cap applies to the next `POST /api/v1/billing/usage` call.

## Errors

Errors use `{ "errors": { "base": ["…"] } }`.

| Status | When |
| - | - |
| `400` | The app's pricing has no usage component. |
| `401` | Missing or invalid access token. |
| `403` | Token lacks `write_billing`. |
| `404` | Installation or app not found. |
| `422` | `cappedAmount` is missing, negative or not a number, or lower than the usage already accrued this period. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.