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

# Billing

> Read your current plan, usage, and billing history from the public API.

## Public billing endpoints

| Method | Endpoint                       |
| ------ | ------------------------------ |
| `GET`  | `/api/v1/billing/plans`        |
| `GET`  | `/api/v1/billing/subscription` |
| `GET`  | `/api/v1/billing/usage`        |
| `GET`  | `/api/v1/billing/payments`     |
| `GET`  | `/api/v1/usage`                |

<Note>
  Public billing through an API key is read-only. Sensitive actions such as checkout, cancellation, or downgrade happen from the dashboard.
</Note>

<Warning>
  Billing reads (`/me`, `/usage`, `/billing/subscription`, `/billing/usage`, `/billing/payments`) require a **personal API key** (`msgf_live_…`). A **team API key** (`msgf_team_…`) is rejected with `403` `TEAM_KEY_NOT_ALLOWED`. For team-aware billing data, use the console API with `Authorization: Bearer <jwt>` and the optional `X-Team-Id` header — see [Team context](/api-reference/teams/team-context).
</Warning>

## Query parameters

All of these routes are `GET`.

| Endpoint                       | Query params    | Body |
| ------------------------------ | --------------- | ---- |
| `/api/v1/billing/plans`        | noe             | noe  |
| `/api/v1/billing/subscription` | noe             | noe  |
| `/api/v1/billing/usage`        | noe             | noe  |
| `/api/v1/usage`                | noe             | noe  |
| `/api/v1/billing/payments`     | `page`, `limit` | noe  |

***

## List plans

```bash theme={null}
curl https://srv.msgflash.com/api/v1/billing/plans \
  -H "x-api-key: msgf_live_your_api_key_here"
```

### Success response

```json theme={null}
{
  "data": [
    {
      "code": "pro",
      "name": "Pro",
      "priceEur": 19,
      "limits": {
        "maxInstances": 5,
        "maxApiKeys": 5,
        "maxWebhookEndpoints": 15,
        "monthlyOutboundQuota": 50000,
        "monthlyApiRequestQuota": 150000
      },
      "features": {
        "campaigns": true,
        "statuses": false,
        "voiceNotes": true,
        "webhooks": true,
        "numberLookups": true
      }
    }
  ]
}
```

See [Plans and quotas](/resources/plans-and-quotas) for the full **Free / Pro / MAX** comparison (EUR only).

***

## Current subscription

```bash theme={null}
curl https://srv.msgflash.com/api/v1/billing/subscription \
  -H "x-api-key: msgf_live_your_api_key_here"
```

Example:

```json theme={null}
{
  "data": {
    "subscription": {
      "plan": {
        "code": "pro",
        "name": "Pro",
        "limits": {
          "maxInstances": 5,
          "maxApiKeys": 5,
          "maxWebhookEndpoints": 15
        },
        "features": {
          "campaigns": true,
          "statuses": false,
          "webhooks": true
        }
      },
      "scheduledPlan": null,
      "scheduledPlanAt": null,
      "scheduledAction": null
    },
    "usage": {
      "messagesCount": 0,
      "statusesCount": 0,
      "effectiveOutboundUsage": 0,
      "apiRequestsCount": 0,
      "activeInstancesCount": 1,
      "activeApiKeysCount": 1
    },
    "period": {
      "start": "2026-04-01T00:00:00.000Z",
      "end": "2026-04-30T23:59:59.999Z"
    }
  }
}
```

<Note>
  Read limits from `subscription.plan.limits.*`, not from `subscription.plan.maxInstances`.
</Note>

<Note>
  Paid checkout accepts `pro` or `max` only. Legacy plan codes `starter` and `plus` may still appear on old payment records.
</Note>

***

## Enriched usage

```bash theme={null}
curl https://srv.msgflash.com/api/v1/billing/usage \
  -H "x-api-key: msgf_live_your_api_key_here"
```

This endpoint returns:

* current plan
* limits
* features
* monthly usage
* billing period

***

## Payment history

```bash theme={null}
curl "https://srv.msgflash.com/api/v1/billing/payments?page=1&limit=20" \
  -H "x-api-key: msgf_live_your_api_key_here"
```

Response:

```json theme={null}
{
  "data": {
    "payments": [
      {
        "id": "pay_uuid",
        "provider": "dodo",
        "planCode": "pro",
        "planName": "Pro",
        "amount": 1900,
        "currency": "EUR",
        "status": "succeeded",
        "periodStart": "2026-04-01T09:43:13.737Z",
        "periodEnd": "2026-05-01T09:43:13.737Z",
        "createdAt": "2026-04-01T09:43:13.745Z"
      }
    ],
    "total": 1,
    "page": 1,
    "totalPages": 1
  }
}
```

### Query params

| Parameter | Type    | Required | Description             |
| --------- | ------- | -------- | ----------------------- |
| `page`    | integer | no       | Default `1`             |
| `limit`   | integer | no       | Default `20`, max `100` |

## Common errors

| Code                      | HTTP | When                                               |
| ------------------------- | ---- | -------------------------------------------------- |
| `UNAUTHORIZED`            | 401  | Missing or invalid key                             |
| `TEAM_KEY_NOT_ALLOWED`    | 403  | Team API key used on a personal-only billing route |
| `API_RATE_LIMIT_EXCEEDED` | 429  | Too many requests per second                       |