Skip to main content
Every subscription runs on a billing cycle — a repeating period over which usage is accumulated and a single invoice is generated. Understanding the cycle helps you predict when invoices will appear and how usage is attributed to each period.

​
Billing periods

When you create a plan, you set a billing_period:
PeriodDescription
dailyResets every calendar day at midnight UTC
weeklyResets every 7 days from the subscription start date
monthlyResets on the same day of month as the subscription start
quarterlyResets every 3 months
annuallyResets every 12 months
The period start date is anchored to the subscription creation date. A subscription created on February 10 on a monthly plan will have period boundaries on the 10th of each month.

​
The billing cycle timeline

Subscription created
        │
        ▼
  Period 1 starts
        │
        │  Events flow in
        │  Usage accumulates in rollups
        │
        ▼
  Period 1 ends
        │
        ├─ Draft invoice generated
        ├─ Invoice finalized (amounts locked)
        ├─ Charge triggered via payment provider
        ├─ invoice.paid webhook fired
        │
        ▼
  Period 2 starts
        │
       ...

​
What Monigo does at period end

When a billing period closes, Monigo executes the following steps automatically:
  1. Aggregates usage — All events ingested during the period are rolled up per metric.
  2. Applies pricing — Each price rule is evaluated against its metric’s aggregated value.
  3. Generates a draft invoice — Line items are created for each metric/price pair.
  4. Finalizes the invoice — The amounts are locked and the invoice moves to finalized status.
  5. Triggers a charge — Monigo calls your connected payment provider (Paystack, Flutterwave, or Monnify) to collect payment.
  6. Delivers webhooks — invoice.finalized, invoice.paid (or invoice.payment_failed) events are sent to your webhook endpoint.
In test mode, invoices are generated and finalized but no real charge is submitted to your payment provider. This lets you inspect the full billing cycle without affecting real customers.

​
Trial periods

Plans can include a trial period. During a trial:
  • The subscription is active and events are ingested normally
  • No invoice is generated until the trial ends
  • When the trial period expires, the first regular billing period begins
Trial periods are set on the plan level (trial_period_days) and apply to all new subscriptions created on that plan.

​
Manually generating invoices

You can generate a draft invoice at any time without waiting for the period to end — useful for previewing what a customer would be charged based on their current usage. 
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>" }'
A manually generated invoice starts as draft and does not automatically trigger a charge. You must call POST /v1/invoices/{id}/finalize explicitly to lock amounts and initiate collection.

​
Event attribution

Events are attributed to the billing period in which their timestamp falls — not when they were ingested. This means you can ingest events late (up to 90 days backdated) and they will be attributed to the correct period.
If an invoice for a period has already been finalized, backdated events for that period will not be included automatically. You would need to void and regenerate the invoice to incorporate them. See Idempotency & Replayability.