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

# Usage-Based Billing

> Move from flat-rate subscriptions to per-unit pricing with Monigo.

Usage-based billing charges customers based on how much they actually use your product. This guide walks through setting up metered billing end-to-end.

## Overview

```mermaid theme={null}
flowchart LR
    A[/Ingest Events/] --> B[Monigo<br>Meters Usage]
    B --> C[Invoice<br>Generated]
    C --> D[Customer<br>Charged]

    style A fill:#F3F4F6,color:#1F2937,stroke:#D1D5DB
    style B fill:#1F2937,color:#fff,stroke:#374151
    style C fill:#DCFCE7,color:#14532D,stroke:#16A34A
    style D fill:#16A34A,color:#fff,stroke:#14532D
```

## 1. Define a metric

A metric is a named unit of measurement. Create metrics in **Dashboard → Metrics** or via the API.

Common examples:

* `api_calls` — number of API requests
* `storage_gb` — gigabytes of data stored
* `transactions` — payment transactions processed
* `active_users` — monthly active users

## 2. Create a pricing plan

A Plan defines how metrics map to prices. Monigo supports:

**Flat rate** — fixed price per unit

```json theme={null}
{ "model": "flat", "unit_amount": 100 }
```

**Graduated tiers** — different rates at different volumes

```json theme={null}
{
  "model": "graduated",
  "tiers": [
    { "up_to": 10000, "unit_amount": 0 },
    { "up_to": 100000, "unit_amount": 0.50 },
    { "up_to": null, "unit_amount": 0.30 }
  ]
}
```

**Package / block pricing** — charge for bundles of units

```json theme={null}
{ "model": "package", "package_size": 1000, "unit_amount": 500 }
```

## 3. Subscribe a customer to a plan

```bash theme={null}
curl -X POST https://api.monigo.co/v1/subscriptions \
  -H "Authorization: Bearer mk_live_..." \
  -d '{
    "customer_id": "cus_xxxx",
    "plan_id": "plan_xxxx"
  }'
```

## 4. Ingest usage events

Send events in real time as your customers use your product:

```bash theme={null}
curl -X POST https://api.monigo.co/v1/events \
  -H "Authorization: Bearer mk_live_..." \
  -d '{
    "customer_id": "cus_xxxx",
    "event_name": "api_calls",
    "quantity": 1,
    "idempotency_key": "req_abc123"
  }'
```

## 5. Billing cycle end

At the end of each billing period, Monigo:

1. Aggregates all usage for each customer
2. Applies pricing tiers
3. Generates an invoice
4. Triggers payment via your connected provider
5. Delivers a `invoice.paid` or `invoice.failed` webhook

## Hard caps and overages

To prevent surprise bills, you can configure a hard cap:

```json theme={null}
{
  "hard_cap": 500000,
  "cap_action": "pause_service"
}
```

When a customer reaches the cap, Monigo sends an alert webhook and you can pause or throttle their access.

To allow overages instead:

```json theme={null}
{
  "cap_action": "allow_overage"
}
```