> ## 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.

# Get Usage

> Read the metered configuration and the current billing period usage of the installation that owns the token.

Returns the usage pricing, the merchant-approved cap and what has accrued in
the current billing period — typically used to render a "used X of Y this
month" bar in your app.

**Scope:** `read_billing`. The installation is resolved from the access
token. `*Cents` fields are minor units of the pricing currency (see
[Usage Records](https://docs.launchmystore.io/api-reference/app-billing/usage-records.md)).

```bash theme={null}
curl "https://api.launchmystore.io/api/v1/billing/usage" \
  -H "Authorization: Bearer <APP_ACCESS_TOKEN>"
```

## Response

**data.unitName** `string | null`

Label of the metered unit, e.g. `SMS`.

**data.unitAmount** `number | null`

Unit price in major units.

**data.currency** `string`

Pricing currency (ISO 4217).

**data.capAmountCents** `integer | null`

Merchant-approved cap (`null` when no cap is declared).

**data.accruedAmountCents** `number`

Usage recorded and not yet invoiced.

**data.remainingCents** `number | null`

Headroom under the cap.

**data.pendingCapAmountCents** `integer | null`

A cap raise waiting for the merchant's approval, else `null`.

**data.billingStatus** `string`

`active`, `trial`, `past_due`, `cancelled`, …

**data.currentPeriodEnd** `string | null`

End of the current subscription period.

**data.cancelAtPeriodEnd** `boolean`

`true` when the subscription is scheduled to end at `currentPeriodEnd`.

**data.meteredItemId** `string | null`

Metered subscription item the usage is reported on.

```json theme={null}
{
  "status": 200,
  "state": "success",
  "data": {
    "unitName": "SMS",
    "unitAmount": 0.05,
    "currency": "USD",
    "capAmountCents": 5000,
    "accruedAmountCents": 605,
    "remainingCents": 4395,
    "pendingCapAmountCents": null,
    "billingStatus": "active",
    "currentPeriodEnd": "2026-06-01T00:00:00.000Z",
    "cancelAtPeriodEnd": false,
    "meteredItemId": "si_OqW2NABCxyz"
  }
}
```

`accruedAmountCents` goes down by the invoiced usage when the period's
invoice is paid, so usage recorded after the period closed but before the
invoice was paid is not lost.

## Errors

| Status | When |
| - | - |
| `401` | Missing or invalid access token. |
| `403` | Token lacks `read_billing`. |
| `404` | Installation or app not found. |


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