Postpaid Billing

Postpaid billing is how Monigo works out of the box. The customer consumes usage during a billing period, and at period end Monigo aggregates that usage, generates an invoice, finalizes the amounts, and then collects payment through your connected payment provider. The customer pays after the usage has happened — in arrears. This is the right default for most products:

SaaS with a card on file that you charge at the end of each cycle
Usage-based products billed monthly in arrears
Customers you trust to pay after consumption rather than pre-funding an account

If instead you want the customer to pre-fund a balance and have it debited at billing time, see Prepaid Billing. To debit a wallet continuously as usage accrues, see Real-Time Billing.

Postpaid is the default billing_mode for every plan. You don’t have to set anything — it’s what you get when you omit billing_mode. Payout plans always use the postpaid flow.

How it works

Everything in this flow runs automatically once a subscription’s period ends — you don’t trigger any of it by hand.

Setting up a postpaid plan

Because postpaid is the default, you can simply omit billing_mode. It’s shown explicitly below for clarity:

curl -X POST https://api.monigo.co/v1/plans \
  -H "Authorization: Bearer mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Metered API",
    "currency": "NGN",
    "plan_type": "collection",
    "billing_period": "monthly",
    "billing_mode": "postpaid"
  }'

plan, err := client.Plans.Create(ctx, monigo.CreatePlanParams{
    Name:          "Metered API",
    Currency:      "NGN",
    PlanType:      "collection",
    BillingPeriod: "monthly",
    BillingMode:   "postpaid", // optional — this is the default
})

const plan = await client.plans.create({
  name: "Metered API",
  currency: "NGN",
  plan_type: "collection",
  billing_period: "monthly",
  billing_mode: "postpaid", // optional — this is the default
});

Postpaid works with every billing_period (daily, weekly, monthly, quarterly, annually) and every pricing model. See Pricing Models for the full set.

The billing cycle at period end

When a postpaid period closes, Monigo runs these steps automatically:

Aggregates usage — all events ingested during the period are rolled up per metric.
Calculates the invoice total — each price rule is applied to its metric’s aggregated value; VAT is added if configured.
Generates a draft invoice — one line item per metric/price pair.
Finalizes the invoice — amounts are locked, status moves to finalized, and invoice.finalized fires.
Attempts collection — Monigo charges the customer through your connected payment provider.
Advances the period — the subscription moves to its next billing period.

For the period-level view of this, see Billing Cycle.

The happy path: payment succeeds

When collection succeeds, the invoice moves to paid, paid_at is stamped, and an invoice.paid webhook fires. The resulting invoice will have:

Field	Value
`status`	`"paid"`
`paid_at`	Timestamp of the successful charge
`wallet_debit`	`false` (unless a wallet covered it — see below)

How Monigo collects, in order:

Wallet — if the customer has a wallet with enough balance, it’s debited first.
Saved card — otherwise the default card on file (captured from prior successful charges) is charged.
Payment link — if there’s no chargeable card, Monigo emails the customer a hosted payment link to settle the invoice.

A card is added to the customer’s file automatically the first time they pay through a provider — there’s no separate “save card” step. Subsequent invoices can then be charged without customer interaction.

Handling failed payments

If collection fails (insufficient funds, expired card, provider decline), the invoice stays finalized and a payment.failed webhook fires. Monigo then begins dunning — it automatically retries collection on a fixed schedule:

Attempt	When
Retry 1	1 day after the failure
Retry 2	4 days after the failure
Retry 3	7 days after the failure

payment.failed

{
  "event": "charge.failed",
  "data": {
    "reference": "pay_abc123",
    "amount": 500000,
    "currency": "NGN"
  }
}

If any retry succeeds, the invoice moves to paid and invoice.paid fires — the dunning sequence ends there.

Use the payment.failed webhook to nudge the customer early — an email or in-app banner asking them to update their card often recovers the payment before the dunning retries are exhausted.

When dunning is exhausted

If all three retries fail, Monigo suspends the subscription and fires subscription.suspended:

subscription.suspended

{
  "customer_id": "01924f1e-...",
  "customer_name": "Acme Corp",
  "subscription_id": "01924f1e-...",
  "invoice_id": "01924f1e-...",
  "amount": "5000.000000",
  "currency": "NGN"
}

A suspended subscription stops accruing billable usage. To recover it, have the customer settle the outstanding invoice (update their card and retry the charge, or pay the hosted link), then resume the subscription:

curl -X POST https://api.monigo.co/v1/subscriptions/<subscription_id>/resume \
  -H "Authorization: Bearer mk_live_..."

sub, err := client.Subscriptions.Resume(ctx, subscriptionID)

const sub = await client.subscriptions.resume(subscriptionId);

Don’t void a finalized invoice just to stop dunning — voiding cancels the charge entirely and the customer is never billed for that period. Use it only when the customer genuinely should not be charged. See Invoice Lifecycle.

Webhook events

Event	When fired
`invoice.finalized`	Period closed; amounts locked, collection starting
`payment.success`	A charge succeeded at the provider
`invoice.paid`	Invoice settled; `paid_at` set
`payment.failed`	A charge attempt failed (dunning begins/continues)
`subscription.suspended`	All dunning retries exhausted; subscription suspended

Customer portal

In the customer portal, postpaid subscriptions show the customer their invoices (draft, finalized, paid, void), the estimated total for the current open period, and their saved payment methods. When an invoice is unpaid, the portal surfaces a Pay now action backed by your payment provider — no code required on your side.

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
Payment collection	Provider (card/bank/link)	Debited from wallet	Debited from wallet
Failed payment	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

Billing Cycle — how periods work and when billing runs
Invoice Lifecycle — draft → finalized → paid → void
Subscription Lifecycle — pause, resume, suspend, and cancel
Prepaid Billing — wallet debited at period end
Real-Time Billing — wallet debited continuously as usage accrues
Webhooks — receiving billing events

Get Started

Concepts

Guides

SDKs

Integrations

API Reference

Postpaid Billing

How it works

Setting up a postpaid plan

The billing cycle at period end

The happy path: payment succeeds

Handling failed payments

When dunning is exhausted

Webhook events

Customer portal

Comparing the billing modes

​How it works

​Setting up a postpaid plan

​The billing cycle at period end

​The happy path: payment succeeds

​Handling failed payments

​When dunning is exhausted

​Webhook events

​Customer portal

​Comparing the billing modes

​Related

How it works

Setting up a postpaid plan

The billing cycle at period end

The happy path: payment succeeds

Handling failed payments

When dunning is exhausted

Webhook events

Customer portal

Comparing the billing modes

Related