Usage-Based Billing

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

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

{ "model": "flat", "unit_amount": 100 }

Graduated tiers — different rates at different volumes

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

{ "model": "package", "package_size": 1000, "unit_amount": 500 }

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:

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:

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

Hard caps and overages

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

{
  "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:

{
  "cap_action": "allow_overage"
}

Get Started

Concepts

Guides

SDKs

Integrations

API Reference

Usage-Based Billing

Overview

1. Define a metric

2. Create a pricing plan

4. Ingest usage events

5. Billing cycle end

Hard caps and overages

​Overview

​1. Define a metric

​2. Create a pricing plan

​3. Subscribe a customer to a plan

​4. Ingest usage events

​5. Billing cycle end

​Hard caps and overages

Overview

1. Define a metric

2. Create a pricing plan

3. Subscribe a customer to a plan

4. Ingest usage events

5. Billing cycle end

Hard caps and overages