Skip to main content
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

Ingest events → Monigo meters usage → Invoice generated → Customer charged

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

​
3. Subscribe a customer to a plan

curl -X POST https://api.monigo.com/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.com/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: 
{
  "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"
}