Real-Time Billing

With postpaid and prepaid billing, the customer is charged at period end. Real-time billing charges them as they go: as usage events arrive, Monigo reconciles the running cost and debits the customer’s prepaid wallet — typically within ~5 seconds — so the balance always reflects exactly what has been consumed so far. There’s no invoice to chase and no end-of-period bill surprise; the customer only ever spends what they’ve already funded. Real-time billing works best for:

AI and agent products metered by tokens, calls, or seconds
Pay-as-you-go APIs where customers fund a balance and draw it down
Any product where you want the customer to watch their balance decrease live

Real-time billing is wallet-backed: it reuses the same prepaid wallet, pause-on-empty, and auto-resume-on-top-up machinery as Prepaid Billing. The difference is when the wallet is debited — continuously, rather than once at period end.

For a complete, copy-paste integration walkthrough using an AI agent as the example — customer creation, metric, plan, wallet widget, and event ingestion — see the AI Prepaid Wallet guide. This page focuses on the billing mode itself.

How it works

Charging is asynchronous and batched, so it never sits on your ingest hot path. The wallet’s double-entry ledger is the system of record throughout; the period-end invoice is just a record of what was already debited.

Setting up a real-time plan

Set "billing_mode": "realtime" and attach prices for your metrics:

curl -X POST https://api.monigo.co/v1/plans \
  -H "Authorization: Bearer mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AI Prepaid — token billing",
    "currency": "NGN",
    "plan_type": "collection",
    "billing_period": "monthly",
    "billing_mode": "realtime",
    "prices": [
      { "metric_id": "<metric_id>", "model": "per_unit", "unit_price": "0.100000" }
    ]
  }'

plan, err := client.Plans.Create(ctx, monigo.CreatePlanParams{
    Name:          "AI Prepaid — token billing",
    Currency:      "NGN",
    PlanType:      "collection",
    BillingPeriod: "monthly",
    BillingMode:   "realtime",
    Prices: []monigo.PriceParams{
        {MetricID: metricID, Model: "per_unit", UnitPrice: "0.100000"},
    },
})

const plan = await client.plans.create({
  name: "AI Prepaid — token billing",
  currency: "NGN",
  plan_type: "collection",
  billing_period: "monthly",
  billing_mode: "realtime",
  prices: [
    { metric_id: metricId, model: "per_unit", unit_price: "0.100000" },
  ],
});

billing_mode: "realtime" requires plan_type: "collection" and billing_period: "monthly" — usage is aggregated per calendar month, and other combinations are rejected at plan creation. All pricing models (per_unit, tiered, package, overage, cap) are supported.

Wallet auto-creation

Real-time billing debits a prepaid wallet, so the customer needs one funded in the plan’s currency. As with prepaid plans, Monigo creates the wallet automatically when the customer subscribes if one doesn’t already exist. Let the customer fund it inline with the <WalletWidget> component (React, Svelte, or Vue), which shows the live balance and opens the provider’s checkout on Top up. See Wallet Management and Embedding the Portal.

The payment provider’s webhook is the source of truth for crediting — never credit a wallet from the browser. Monigo credits it automatically when the provider confirms the top-up.

The reconcile engine

Each flush cycle does not price individual events. Instead it reconciles: it recomputes the cost of all usage so far this period and debits only the difference since the last charge.

target   = Σ price(cumulative usage) across all metrics
marginal = target − charged_so_far
debit the wallet for `marginal`, then persist charged_so_far = target

This reconcile approach is what makes every pricing model behave correctly in real time:

Tiered, package, and overage pricing stay exact across the whole period, because the cost is always recomputed from the cumulative quantity — never summed from per-event slices that would land in the wrong tier.
cap pricing charges its flat fee exactly once: the first reconcile debits the base price, and every subsequent reconcile computes a marginal of zero.

A few properties worth knowing:

~5 second latency. Charging trails ingestion by roughly the flush interval. It’s asynchronous, so it never blocks event ingestion.
Crash-safe and idempotent. Each debit carries a deterministic idempotency key derived from the charge sequence, so a retry after a crash can never double-charge.
Bounded free usage. Because charging trails ingestion by a few seconds, a small amount of usage can be metered in the window between the balance hitting zero and the pause taking effect. This is bounded to roughly one charge interval.

Handling insufficient balance

When the wallet can’t cover the next marginal charge, Monigo:

Pauses the subscription and blocks further usage events for that customer (so usage can’t run up unbilled while the balance is empty).
Fires a subscription.prepaid_balance_insufficient webhook.

subscription.prepaid_balance_insufficient

{
  "subscription_id": "01924f1e-...",
  "customer_id": "01924f1e-...",
  "amount_due": "120.000000",
  "currency": "NGN",
  "reason": "insufficient_balance"
}

Use this webhook to prompt the customer to top up — surface the wallet widget or a “fund wallet” call-to-action.

Auto-resume on top-up

When you credit a wallet belonging to a customer with a paused real-time subscription, Monigo automatically:

Reactivates the subscription
Charges any usage that accrued but went unbilled while the balance was empty (the residual)
Unblocks further events and resumes continuous debiting

This is fully automatic — exactly the same top-up flow as prepaid billing. The provider’s top-up webhook credits the wallet; Monigo handles the resume.

# Top up the wallet — Monigo auto-resumes the subscription once the credit lands
curl -X POST https://api.monigo.co/v1/wallets/{wallet_id}/credit \
  -H "Authorization: Bearer mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "5000.00",
    "description": "Manual top-up",
    "idempotency_key": "topup_abc123"
  }'

entry, err := client.Wallets.Credit(ctx, walletID, monigo.CreditWalletParams{
    Amount:         "5000.00",
    Description:    "Manual top-up",
    IdempotencyKey: "topup_abc123",
})
// Once the balance covers the residual, the subscription auto-resumes.

const entry = await client.wallets.credit(walletId, {
  amount: "5000.00",
  description: "Manual top-up",
  idempotency_key: "topup_abc123",
});
// Once the balance covers the residual, the subscription auto-resumes.

Always provide an idempotency_key when crediting wallets so a retried top-up never double-credits. See Idempotency.

What happens at period end

The money has already been debited continuously, so the period close is just bookkeeping. At month end Monigo emits one paid summary invoice — per-metric line items, total equal to what was actually debited — and no additional charge is made. The invoice exists for the customer’s records, then the period advances. This is the key difference from prepaid: prepaid does all its work at period end (one debit, one invoice), while real-time has done the debiting throughout and uses period end only to issue the summary.

Webhook events

Event	When fired
`subscription.prepaid_balance_insufficient`	Wallet can’t cover the next charge; subscription paused
`customer.wallet.topped_up`	Wallet was credited (auto-resume follows automatically)
`invoice.paid`	Monthly summary invoice issued (already paid from the wallet)

Customer portal

In the customer portal, a real-time subscription shows the customer their live wallet balance drawing down as usage accrues, alongside a Top up wallet → action. The monthly summary invoice appears under their invoices once the period closes. This gives customers continuous visibility into exactly what they’re spending.

Comparing the billing modes

	Postpaid (default)	Prepaid	Real-time
`billing_mode`	`"postpaid"`	`"prepaid"`	`"realtime"`
When charged	At period end, in arrears	At period end, from wallet	Continuously (~5s), from wallet
Invoice created	As `draft`, then finalized	Directly as `paid`	One `paid` summary at period end
Plan constraints	Any period	Collection plans	Collection + monthly only
Failed/empty	Dunning retries → suspend	Subscription paused	Subscription paused
Recovery	Settle invoice → resume	Top up → auto-resume	Top up → auto-resume
Best for	SaaS with card-on-file	APIs with credit/token packs	AI agents, pay-as-you-go usage

AI Prepaid Wallet — full end-to-end integration walkthrough
Prepaid Billing — wallet debited once at period end
Postpaid Billing — the default, collected via payment provider
Wallet Management — wallet operations and the <WalletWidget>
Pricing Models — tiered, package, overage, and cap pricing
Webhooks — receiving billing events

Get Started

Concepts

Guides

SDKs

Integrations

API Reference

Real-Time Billing

How it works

Setting up a real-time plan

Wallet auto-creation

The reconcile engine

Handling insufficient balance

Auto-resume on top-up

What happens at period end

Webhook events

Customer portal

Comparing the billing modes

​How it works

​Setting up a real-time plan

​Wallet auto-creation

​The reconcile engine

​Handling insufficient balance

​Auto-resume on top-up

​What happens at period end

​Webhook events

​Customer portal

​Comparing the billing modes

​Related

How it works

Setting up a real-time plan

Wallet auto-creation

The reconcile engine

Handling insufficient balance

Auto-resume on top-up

What happens at period end

Webhook events

Customer portal

Comparing the billing modes

Related