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

> Consultez les plans, la souscription courante, la consommation et l'historique de paiements via l'API publique.

## Endpoints

| Méthode | 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>
  Le billing public via API key est en lecture seule. Les actions sensibles comme checkout, annulation ou downgrade se font depuis le dashboard.
</Note>

<Warning>
  Les lectures billing (`/me`, `/usage`, `/billing/subscription`, `/billing/usage`, `/billing/payments`) exigent une **clé API personnelle** (`msgf_live_…`). Une **clé d'équipe** (`msgf_team_…`) est rejetée en `403` `TEAM_KEY_NOT_ALLOWED`. Pour des données billing d'équipe, utilisez l'API console avec `Authorization: Bearer <jwt>` et l'en-tête optionnel `X-Team-Id` — voir [Team context](/fr/api-reference/teams/team-context).
</Warning>

## Paramètres

Ces routes sont toutes en `GET`.

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

***

## Lister les plans

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

### Réponse succès

```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
      }
    }
  ]
}
```

Voir [Plans et quotas](/fr/resources/plans-and-quotas) pour le comparatif **Free / Pro / MAX** (EUR uniquement).

***

## Souscription courante

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

Exemple :

```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>
  Les limites se lisent dans `subscription.plan.limits.*`, pas dans `subscription.plan.maxInstances`.
</Note>

<Note>
  Le plan Free autorise 1 clé API de test. Cette ouverture ne change pas le quota outbound Free: 20 messages + statuts par mois.
</Note>

***

## Usage enrichi

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

Cet endpoint renvoie :

* le plan courant
* les limites
* les features
* l'usage du mois
* la période de facturation

***

## Historique des paiements

```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"
```

Réponse :

```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
  }
}
```

### Paramètres query

| Paramètre | Type    | Requis | Description            |
| --------- | ------- | ------ | ---------------------- |
| `page`    | integer | non    | Défaut `1`             |
| `limit`   | integer | non    | Défaut `20`, max `100` |

## Erreurs courantes

| Code                      | HTTP | Quand                                                             |
| ------------------------- | ---- | ----------------------------------------------------------------- |
| `UNAUTHORIZED`            | 401  | Clé invalide ou absente                                           |
| `TEAM_KEY_NOT_ALLOWED`    | 403  | Clé d'équipe utilisée sur une route billing réservée au personnel |
| `API_RATE_LIMIT_EXCEEDED` | 429  | Trop de requêtes par seconde                                      |