Skip to main content
This guide walks through the full Monigo billing loop from scratch using the REST API. By the end you will have a customer subscribed to a metered plan, usage events flowing in, and a draft invoice ready to inspect.
Prefer to follow along in code? The Go and JavaScript SDKs each ship with a quickstart example that does exactly this. See the Go SDK or JavaScript SDK.

​
Prerequisites

  • A Monigo account — sign up free
  • Your test API key from Dashboard → API Keys
Use your mk_test_... key throughout this guide. Test mode events and invoices are fully isolated — no real charges are triggered.

​
Step 1 — Create a customer

A customer represents one of your end-users or accounts. Every event, subscription, and invoice is attached to a customer. 
curl -X POST https://api.monigo.co/v1/customers \
  -H "Authorization: Bearer mk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "user_abc123",
    "name": "Acme Corp",
    "email": "billing@acme.com"
  }'
Save the id from the response — you’ll need it in later steps.

​
Step 2 — Define a metric

A metric tells Monigo what to count and how to count it. It maps an event_name to an aggregation function. 
curl -X POST https://api.monigo.co/v1/metrics \
  -H "Authorization: Bearer mk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Calls",
    "event_name": "api_call",
    "aggregation": "count",
    "description": "Counts every API call made by a customer"
  }'
Supported aggregations: count, sum, max, minimum, average, unique. For sum, max, minimum, and average, also set aggregation_property to the event property that holds the numeric value.

​
Step 3 — Create a pricing plan

A plan defines how your metric maps to a price. Attach one or more prices when creating the plan. This example uses flat-rate pricing — ₦2 per API call, billed monthly. 
curl -X POST https://api.monigo.co/v1/plans \
  -H "Authorization: Bearer mk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Pro",
    "description": "₦2 per API call, billed monthly",
    "currency": "NGN",
    "plan_type": "collection",
    "billing_period": "monthly",
    "prices": [
      {
        "metric_id": "<metric_id>",
        "model": "flat_unit",
        "unit_price": "2.000000"
      }
    ]
  }'
Monigo supports six pricing models: flat, tiered, volume, package, overage, and weighted tiered. See Pricing Models for the full reference.

​
Step 4 — Subscribe the customer

Linking a customer to a plan starts their billing relationship. The subscription tracks the current period start and end dates. 
curl -X POST https://api.monigo.co/v1/subscriptions \
  -H "Authorization: Bearer mk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "<customer_id>",
    "plan_id": "<plan_id>"
  }'
The subscription starts immediately and the first billing period begins now.

​
Step 5 — Ingest usage events

Send an event every time your customer uses a billable feature. Events are aggregated into usage rollups that drive the invoice calculation. 
curl -X POST https://api.monigo.co/v1/ingest \
  -H "Authorization: Bearer mk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "event_name": "api_call",
        "customer_id": "<customer_id>",
        "idempotency_key": "req_unique_id_001",
        "timestamp": "2026-02-25T10:00:00Z",
        "properties": { "endpoint": "/v1/predict", "method": "POST" }
      },
      {
        "event_name": "api_call",
        "customer_id": "<customer_id>",
        "idempotency_key": "req_unique_id_002",
        "timestamp": "2026-02-25T10:00:05Z",
        "properties": { "endpoint": "/v1/embed", "method": "POST" }
      }
    ]
  }'
The idempotency_key ensures each event is counted exactly once even if the request is retried. You can send up to 1 000 events per batch call.

​
Step 6 — Generate an invoice

Invoices are generated automatically at the end of each billing period, but you can also generate a draft manually at any time to preview the charge. 
curl -X POST https://api.monigo.co/v1/invoices/generate \
  -H "Authorization: Bearer mk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "subscription_id": "<subscription_id>" }'
The invoice will have status: "draft". You can inspect the line items, finalize it to lock the amounts, and void it if needed.

​
What happens next

You now have the complete billing loop running in test mode: 
Customer ─→ Metric ─→ Plan ─→ Subscription
                                    │
                              Events flow in
                                    │
                           Usage rollups accumulate
                                    │
                         Invoice generated at period end
                                    │
                      Paystack / Flutterwave charges customer
Continue building: