Monigo is built around seven entities. Understanding how they fit together makes every other part of the API easier to reason about.
Entity map
Organisation
│
├── Customers ──────────────── PayoutAccounts
│ │
│ ├── Subscriptions ──── Plans ──── Prices ──── Metrics
│ │ │
│ │ └── Invoices
│ │ │
│ │ └── LineItems
│ │
│ └── Events ──────────────────────────────────► UsageRollups
│
└── Metrics
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.
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.) |
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 |
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
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 |
prices | One or more pricing rules attached to metrics |
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) |
"2.500000") to avoid floating-point precision errors.
Related: Pricing Models guide
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) |
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 |
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 |
