Data Model

Monigo is built around seven entities. Understanding how they fit together makes every other part of the API easier to reason about.

Entity map

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, 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, Idempotency guide

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

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

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

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, 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

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

Wallet

A wallet holds a pre-funded balance for a customer in a specific currency. Wallets are used by 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

Get Started

Concepts

Guides

SDKs

Integrations

API Reference

Entity map

Customer

Event

Metric

Plan

Price

Subscription

Invoice

Payout Account

Wallet

​Entity map

​Customer

​Event

​Metric

​Plan

​Price

​Subscription

​Invoice

​Payout Account

​Wallet

Entity map

Customer

Event

Metric

Plan

Price

Subscription

Invoice

Payout Account

Wallet