> ## 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.
# Data Model
> The seven core entities in Monigo and how they relate to each other.
Monigo is built around seven entities. Understanding how they fit together makes every other part of the API easier to reason about.
## Entity map
```mermaid placement="top-right" theme={null}
flowchart TD
Org[Organisation] --> Customer
Org --> Metric
Customer --> Wallet
Customer --> Subscription
Customer --> Event
Customer --> PayoutAccount
Subscription --> Plan
Subscription --> Invoice
Plan --> Price
Price --> Metric
Invoice --> LineItem
Event -.->|aggregates into| UsageRollup
Plan:::detail
Price:::detail
Metric:::detail
Org:::entity
Customer:::entity
Wallet:::entity
Subscription:::entity
Invoice:::entity
LineItem:::entity
Event:::entity
UsageRollup:::entity
PayoutAccount:::entity
Plan:::entity
Price:::entity
subgraph legend[" "]
direction LR
Plan["Plan
billing_mode: postpaid | prepaid"]
Price["Price
model: flat | per_unit | tiered | revenue_share"]
Metric["Metric
event_name"]
end
classDef entity fill:#F3F4F6,stroke:#D1D5DB,color:#1F2937
classDef org fill:#1F2937,stroke:#374151,color:#fff
classDef highlight fill:#DCFCE7,stroke:#16A34A,color:#14532D
class Org org
class Subscription,Invoice highlight
```
***
## Customer
A customer is an end-user, company, or account that you bill or pay out to.
| Field | Description |
| ------------- | ---------------------------------------------------------- |
| `id` | Monigo-assigned UUID |
| `external_id` | Your own ID for this customer (e.g. your database user ID) |
| `name` | Display name |
| `email` | Contact email |
| `phone` | E.164 phone number (required for mobile money payouts) |
Always set `external_id` to your own system's identifier. This lets you look up customers by your ID without storing Monigo UUIDs in your database.
**Related:** [Customers API](/api-reference/customers), [Payout Accounts](/api-reference/payout-accounts)
***
## Event
An event is a single record of something your customer did — one API call, one transaction processed, one gigabyte written. Events are the raw input to the metering pipeline.
| Field | Description |
| ----------------- | --------------------------------------------------------------------- |
| `event_name` | What happened (`"api_call"`, `"storage_write"`) |
| `customer_id` | Who did it |
| `idempotency_key` | Unique key that prevents double-counting on retries |
| `timestamp` | When it happened (can be backdated up to 90 days) |
| `properties` | Arbitrary key-value pairs for dimensions (`region`, `endpoint`, etc.) |
Events are immutable once ingested. You can replay a window of events through updated rules, but you cannot edit individual events.
**Related:** [Metering guide](/guides/metering), [Idempotency guide](/guides/idempotency)
***
## Metric
A metric defines how events are aggregated into a single number for billing.
| Field | Description |
| ---------------------- | ------------------------------------------------------------------------------- |
| `event_name` | Which events this metric tracks |
| `aggregation` | How to aggregate: `count`, `sum`, `max`, `minimum`, `average`, `unique` |
| `aggregation_property` | For `sum`/`max`/`min`/`average`: the `properties` key holding the numeric value |
**Example:** A metric named "API Calls" tracks events with `event_name: "api_call"` using `count` aggregation. At billing time, Monigo counts all events in the period and charges based on that number.
**Related:** [Metering guide](/guides/metering)
***
## Plan
A plan is a billing template that defines what to charge and when. Multiple customers can share the same plan.
| Field | Description |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Human-readable label shown on invoices |
| `currency` | ISO 4217 currency code (e.g. `NGN`, `USD`, `KES`) |
| `plan_type` | `collection` (billing customers) or `payout` (paying vendors/partners) |
| `billing_period` | `daily`, `weekly`, `monthly`, `quarterly`, or `annually` |
| `billing_mode` | `postpaid` (default) or `prepaid` — controls whether payment is collected via a payment provider or debited from a customer wallet |
| `prices` | One or more pricing rules attached to metrics |
`billing_mode` only applies to `collection` plans. A prepaid plan debits the customer's wallet atomically at period-end, creating the invoice directly as `paid` without a separate finalize-and-charge step.
**Related:** [Prepaid Billing guide](/guides/prepaid-billing)
***
## Price
A price is one pricing rule attached to a plan. A plan can have multiple prices — one per metric.
| Field | Description |
| ------------ | ---------------------------------------------------------------------------------- |
| `metric_id` | Which metric this price applies to |
| `model` | Pricing model: `flat`, `tiered`, `volume`, `package`, `overage`, `weighted_tiered` |
| `unit_price` | Price per unit (for flat, package, overage models) |
| `tiers` | Tier definitions (for tiered, volume, weighted\_tiered, overage models) |
All monetary values are decimal strings (`"2.500000"`) to avoid floating-point precision errors.
**Related:** [Pricing Models guide](/guides/pricing-models)
***
## Subscription
A subscription links one customer to one plan and tracks the active billing period.
| Field | Description |
| ---------------------- | ----------------------------------- |
| `customer_id` | The customer being billed |
| `plan_id` | The plan they're subscribed to |
| `status` | `active`, `paused`, or `canceled` |
| `current_period_start` | Start of the current billing period |
| `current_period_end` | End of the current billing period |
| `trial_ends_at` | When the trial period ends (if any) |
A subscription automatically advances to the next period when the current one ends. An invoice is generated at the end of each period.
**Related:** [Subscription Lifecycle guide](/guides/subscription-lifecycle), [Billing Cycle](/concepts/billing-cycle)
***
## Invoice
An invoice is the bill generated at the end of each billing period. It contains one line item per price on the plan.
| Field | Description |
| ----------------------------- | --------------------------------------- |
| `status` | `draft`, `finalized`, `paid`, or `void` |
| `subtotal` | Pre-tax total as a decimal string |
| `total` | Final total including VAT (if enabled) |
| `period_start` / `period_end` | The billing period this invoice covers |
| `line_items` | One entry per metric/price pair |
**Related:** [Invoice Lifecycle guide](/guides/invoice-lifecycle)
***
## Payout Account
A payout account is a bank account or mobile money number that a customer can be paid to. Used for event-driven payouts to vendors, drivers, or partners.
| Field | Description |
| --------------------- | ---------------------------------------------------------------- |
| `payout_method` | `bank_transfer` or `mobile_money` |
| `account_number` | Bank account number (for bank transfers) |
| `mobile_money_number` | Phone number in E.164 format (for mobile money) |
| `is_default` | Whether this is the default account for payouts to this customer |
**Related:** [Event-Driven Payouts guide](/guides/event-driven-payouts)
***
## Wallet
A wallet holds a pre-funded balance for a customer in a specific currency. Wallets are used by [prepaid billing](/guides/prepaid-billing) to debit usage charges directly at period-end.
| Field | Description |
| ---------------- | ------------------------------------------------------------------- |
| `customer_id` | The customer this wallet belongs to |
| `currency` | The currency the wallet holds (matches the prepaid plan's currency) |
| `balance` | Available balance as a decimal string (e.g. `"10000.000000"`) |
| `ledger_entries` | Double-entry record of every credit and debit |
Wallets are created automatically when a customer subscribes to a prepaid plan. You can credit a wallet at any time via the API or by generating a payment link.
**Related:** [Prepaid Billing guide](/guides/prepaid-billing)