> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monigo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing Cycle

> How billing periods work, what happens at period end, and how invoices are triggered.

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`:

| Period      | Description                                               |
| ----------- | --------------------------------------------------------- |
| `daily`     | Resets every calendar day at midnight UTC                 |
| `weekly`    | Resets every 7 days from the subscription start date      |
| `monthly`   | Resets on the same day of month as the subscription start |
| `quarterly` | Resets every 3 months                                     |
| `annually`  | Resets 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

```mermaid placement="top-right" theme={null}
flowchart TD
    A([Subscription Created]) --> B[Period 1 Starts]

    B --> C[/"Events flow in\nUsage accumulates in rollups"/]

    C --> D[Period 1 Ends]

    D --> E[Draft Invoice Generated]
    E --> F[Invoice Finalized\namounts locked]
    F --> G[Charge Triggered\nvia Payment Provider]
    G --> H[/invoice.paid webhook fired/]

    H --> I[Period 2 Starts]
    I --> J[/"Events flow in\nUsage accumulates in rollups"/]
    J --> K[...]

    style A fill:#16A34A,color:#fff,stroke:#14532D
    style H fill:#DCFCE7,color:#14532D,stroke:#16A34A
    style E fill:#F3F4F6,color:#1F2937,stroke:#D1D5DB
    style F fill:#F3F4F6,color:#1F2937,stroke:#D1D5DB
    style G fill:#F3F4F6,color:#1F2937,stroke:#D1D5DB
    style K fill:#F3F4F6,color:#6B7280,stroke:#D1D5DB
```

## 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.

<Info>
  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.
</Info>

## 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.

```bash theme={null}
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.

<Warning>
  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](/guides/idempotency).
</Warning>

## Prepaid billing mode

Plans can be set to `billing_mode: "prepaid"` (collection plans only). In prepaid mode, the billing cycle changes at step 5:

**Postpaid (default):**

```mermaid placement="top-right" theme={null}
flowchart LR
    A[Period Ends] --> B[Draft Invoice]
    B --> C[Finalized]
    C --> D[Payment Provider Charged]
    D --> E[/invoice.paid/]

    style A fill:#1F2937,color:#fff,stroke:#374151
    style B fill:#F3F4F6,color:#1F2937,stroke:#D1D5DB
    style C fill:#F3F4F6,color:#1F2937,stroke:#D1D5DB
    style D fill:#F3F4F6,color:#1F2937,stroke:#D1D5DB
    style E fill:#DCFCE7,color:#14532D,stroke:#16A34A
```

**Prepaid:**

```mermaid placement="top-right" theme={null}
flowchart TD
    A[Period Ends] --> B{Check Wallet Balance}

    B -->|Sufficient| C[Wallet Debited]
    C --> D[Invoice Created as 'paid']
    D --> E[Period Advances]

    B -->|Insufficient| F[Draft Invoice\naudit trail]
    F --> G[Subscription Paused]
    G --> H[/Webhook Fired/]

    I([Customer Tops Up Wallet]) --> J[Auto-Resume +\nBilling Retry]
    J --> C

    style A fill:#1F2937,color:#fff,stroke:#374151
    style B fill:#F3F4F6,color:#1F2937,stroke:#D1D5DB
    style C fill:#DCFCE7,color:#14532D,stroke:#16A34A
    style D fill:#DCFCE7,color:#14532D,stroke:#16A34A
    style E fill:#16A34A,color:#fff,stroke:#14532D
    style F fill:#FEF3C7,color:#92400E,stroke:#F59E0B
    style G fill:#FEE2E2,color:#991B1B,stroke:#EF4444
    style H fill:#FEE2E2,color:#991B1B,stroke:#EF4444
    style I fill:#EFF6FF,color:#1E40AF,stroke:#3B82F6
    style J fill:#EFF6FF,color:#1E40AF,stroke:#3B82F6
```

The invoice in the prepaid path is created directly with `status: "paid"` — there is no draft-to-finalized transition. If the wallet balance is insufficient, the subscription is paused and does not advance to the next period until the customer funds their wallet.

See the [Prepaid Billing guide](/guides/prepaid-billing) for the full setup and auto-resume flow.

## Related

* [Subscription Lifecycle](/guides/subscription-lifecycle) — how subscriptions start, pause, and end
* [Invoice Lifecycle](/guides/invoice-lifecycle) — the full invoice state machine
* [Pricing Models](/guides/pricing-models) — how usage is priced within a period
* [Prepaid Billing](/guides/prepaid-billing) — wallet-based billing mode