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.
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.
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 |
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) |
"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 |
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 |
