Skip to main content

​
How Usage-Based Billing Works

This page explains how Monk’s core concepts — meters, pricing, plans, contracts, and credits — connect to power usage-based billing.
Self-serve or enterprise? How you use these concepts depends on your go-to-market motion. See Self-Serve vs Enterprise Workflows to understand what’s API-driven vs ops-driven for your setup.

​
The Big Picture

LayerWhat It DoesCreated Once or Per-Customer?
MetersDefine what you measure (API calls, tokens, storage)Once — reused across all customers
Rate CardsGlobal rate tables for dimensional pricing (attached to meters)Once — can be overridden per contract
PricingAttach rates to meters (per-unit, tiered, flat)Once — reused across plans
PlansBundle pricing into a subscription templateOnce — reused across customers
ContractsSubscribe a customer to a plan (can override rate cards)Per-customer
Prepaid Credit WalletPrepaid balance that offsets usage (different rates per customer)Per-customer (optional)
EventsUsage data sent as customers consume resourcesPer-customer, continuous
InvoicesGenerated automatically from usage + creditsPer-customer, per billing cycle

​
How the Pieces Connect

​
1. Meters: Define What You Measure

Meters are the foundation. They define what you’re billing for, not how much. 
Meter: API_CALLS
- Aggregation: Count
- Event name: api_call
Create meters once. They’re reusable across all pricing configurations and customers. See the Create Your First Meter guide.

​
2. Rate Cards: Global Dimensional Pricing (Optional)

Rate Cards define variable rates based on dimensions (like model, region, or tier). They’re attached to Meters — not Pricing or Plans — so you can manage rates globally. 
Meter: LLM_TOKENS
Rate Card:
- model=gpt-4: $0.03 per 1K tokens
- model=gpt-3.5: $0.002 per 1K tokens
- model=claude-3: $0.015 per 1K tokens
Why are Rate Cards on Meters? This gives you a single place to update rates globally. When OpenAI changes pricing, update the rate card once — every plan and contract using that meter gets the new rates automatically.
Override per contract: Contracts can override specific rate card values for custom enterprise deals without changing the global rates.

​
3. Pricing: Attach Rates to Meters

Pricing defines how much to charge for meter usage. For simple cases, rates are defined directly on Pricing. For variable rates, Pricing references the Meter’s rate card. 
Pricing: API Usage (Standard)
- Meter: API_CALLS
- Rate: $0.001 per call

Pricing: LLM Usage
- Meter: LLM_TOKENS
- Rate: Use rate card (varies by model dimension)

​
4. Plans: Bundle Pricing Together

Plans bundle pricing configurations into a subscription template. This is what you “sell” to customers. See Create Your First Plan. 
Plan: Pro Plan
- Pricing: API Usage (Standard)
- Pricing: Storage (Standard)
- Billing cycle: Monthly
Do I need a new Plan for every enterprise customer? No! Use Dimensional Pricing for customer-specific rates, or override pricing at contract creation.

​
5. Contracts: Subscribe Customers

A Contract assigns a Plan to a Customer. This is where billing begins — and where customization happens. See Create Your First Contract and Enterprise Billing Patterns. 
Contract:
- Customer: Acme Corp
- Plan: Pro Plan
- Start date: March 1, 2026
- Rate overrides: gpt-4 @ $0.02 (vs $0.03 default)
- Credit wallet: $10,000 prepaid (optional)
Same Plan, Different Rates: Multiple customers can be on the same Plan but pay different rates. Rate card overrides are set at the Contract level, so each customer can have custom pricing without creating new plans.
This means:
  • One Plan to maintain (Pro Plan)
  • Global rate cards on Meters (default pricing)
  • Per-customer overrides on Contracts (enterprise deals, volume discounts)

​
6. Prepaid Credit Wallet (Optional)

The Prepaid Credit Wallet is a prepaid balance attached to a contract. Customers pay upfront, and credits are deducted as usage accrues. See Grant Your First Credit and Prepaid Credits Guide. Why is the wallet separate from Plans?
  • Credits can be added/removed independently of the plan
  • Credits can expire on their own schedule
  • Different customers on the same plan can have different credit amounts
  • Promotional credits (free) are tracked separately from paid credits
Different customers can have different credit rates:
CustomerPlanCredit Rate$10,000 Purchase Gets
Acme CorpPro Plan$0.32/credit31,250 credits
Beta IncPro Plan$0.35/credit28,571 credits
Startup LLCPro Plan$0.40/credit25,000 credits
Each credit grant stores its own rate (creditRateCents), so enterprise customers can get better rates on their prepaid commitments — independent of the plan they’re on.
Credits are a payment method, not a pricing model. A customer on the “Pro Plan” might have 0credits,0 credits, 10,000 credits, or $100,000 credits at various rates — that’s all independent of what the plan charges per unit.

​
7. Events: Send Usage Data

As customers use your product, send events to Monk. Events are matched to meters and aggregated for billing. See Send Your First Event. Simple event (no dimensions): 
{
  "customerId": "cust_acme",
  "eventName": "api_call",
  "properties": { "endpoint": "/users" },
  "timestamp": "2026-03-15T10:30:00Z"
}
Event with dimensions (for rate card pricing): When using dimensional pricing, include the dimension in the event properties. Monk uses this to look up the correct rate. 
{
  "customerId": "cust_acme",
  "eventName": "llm_tokens",
  "properties": {
    "model": "gpt-4",
    "tokens": 1500
  },
  "timestamp": "2026-03-15T10:30:00Z"
}
This event is priced using the model=gpt-4 rate from the rate card (e.g., $0.03/1K tokens), or the contract’s override rate if one exists. 
{
  "customerId": "cust_acme",
  "eventName": "llm_tokens",
  "properties": {
    "model": "gpt-3.5-turbo",
    "tokens": 5000
  },
  "timestamp": "2026-03-15T10:31:00Z"
}
This event uses the model=gpt-3.5-turbo rate (e.g., $0.002/1K tokens).
The dimension value in the event determines the rate. If your rate card has model=gpt-4 and model=gpt-3.5-turbo, the event’s model property is used to look up the correct price.

​
8. Invoices: Automatic Billing

At the end of each billing cycle, Monk:
  1. Aggregates events by meter
  2. Applies pricing to calculate charges
  3. Deducts available credits
  4. Generates the invoice
Overage handling (when credits deplete): When a prepaid credit wallet runs out mid-cycle, usage continues to accrue at the plan’s rates. What happens at billing cycle end depends on the contract’s overage setting:
SettingOn Depletion (mid-cycle)At Billing Cycle End
Auto InvoiceWebhook alert sentInvoice sent automatically for overage amount
Alert OnlyWebhook alert sentDraft invoice created, held for manual review
Both modes deduct all available credits first. The setting only controls whether the overage invoice is sent automatically or held for review.

​
Common Patterns

​
Standard SaaS: Plan + Usage

Most customers use a plan with usage-based pricing, no credits needed. 
Customer → Contract → Plan → Usage → Invoice

​
Enterprise with Prepaid Commitment

Large customers prepay for usage at a discounted rate. See Enterprise Billing Patterns. 
Customer → Contract → Plan + $100K Credits → Usage → Credits Deducted → Invoice ($0 or overage)

​
Promotional Credits

New customers get free credits to try your product. See Promotional Credits Guide. 
Customer → Contract → Plan + $500 Promo Credits → Usage → Promo Credits Deducted First

​
Per-Customer Pricing (Same Plan, Different Rates)

Three customers on the same Pro Plan, each with different rates:
CustomerPlanRate OverrideEffective Rate
Startup IncPro PlanNone$0.03/1K tokens (default)
Acme CorpPro Plangpt-4: $0.02$0.02/1K tokens
Mega EnterprisePro Plangpt-4: $0.015$0.015/1K tokens
No new plans needed. Rate overrides live on each Contract.

​
FAQ

No. Use rate card overrides at the Contract level. Every customer can be on the same Plan but pay different rates:
  • Global rate card (on Meter): Default rates for all customers
  • Contract override: Custom rates for specific customers
This way you maintain one Plan, but Acme pays 0.02/tokenwhileBetapays0.02/token while Beta pays 0.025/token.
You need one Meter per metric you want to track separately (e.g., input_tokens and output_tokens are separate meters). But you don’t need separate Products — a single Plan can include pricing for multiple meters.
Credits are a payment method, not a pricing model. They’re attached to the Contract (customer-level) because: - Different customers on the same plan may have different credit amounts - Credits can be added/removed anytime without changing the plan - Credits can expire independently of the contract - Promotional credits need separate tracking from paid credits
  • Prepaid Credits: Prepaid balance for future usage. Deducted in real-time as usage accrues. Only applies to usage-based charges. - Credit Memos: Post-billing adjustments to invoices. Can apply to any line item. Used for refunds, corrections, goodwill.
Rate cards are on Meters for two reasons:
  1. Global updates: When a vendor changes pricing (e.g., OpenAI raises rates), update the rate card once — all plans and contracts inherit the change automatically.
  2. Flexibility: The same meter can be used in multiple plans. Rate cards stay consistent across plans while contracts can override for custom deals.
If rate cards were on Plans, you’d need to update every plan when rates change. If they were on Pricing, you’d lose the ability to have a single source of truth.
  • Rate Cards: When rates vary by dimension (model, region, tier) but the plan structure stays the same
  • Contract overrides: When one customer needs custom rates
  • New Plans: When the plan structure itself differs (different features, billing cycles, or included meters)

​
Next Steps

Self-Serve vs Enterprise

Choose your go-to-market setup

Create your first Meter

Start tracking usage

Set up a Plan

Bundle pricing for customers

Grant Credits

Add prepaid credits to a contract

Dimensional Pricing

Per-customer rates without new plans

Enterprise Billing

Contract-level customizations