Usage-Based Pricing

Last updated: February 5, 2026

Overview

Usage-based pricing (metered billing) lets you charge customers based on actual consumption rather than a fixed fee. This is ideal for APIs, cloud services, AI models, and any product where usage varies per customer.

Monk handles the full lifecycle: you configure a usage-based product, create a contract, send usage events via API or dashboard, and Monk automatically matches events to the correct invoice.

Prerequisites

  • A product with usage-based pricing configured in Product Plans
  • A contract with the customer that includes the usage-based product
  • For API usage: an API key with the usage:write scope (Settings → API Keys)

How It Works

  1. You create a product with usage-based pricing in Monk, including a unique pricing code
  2. You create a contract with the customer, which pre-creates invoices for each billing period
  3. Your application sends usage events to Monk via the API as customers consume resources
  4. Monk automatically matches usage events to the correct invoice based on the service period

Step 1: Create a Usage-Based Product

Navigate to Product Plans in the left sidebar and click + Create product.

Select Usage-based as the pricing model.

Create product form showing pricing model options: Flat rate, Volume-based, Usage-based

Configure the usage-based product:

  • Name — A descriptive name (e.g., "SMS Notifications")
  • Charge type — Per unit (flat rate per unit) or Per tier (volume-based tiers)
  • Aggregation — How usage events are combined: Sum, Count, Max, or Min
  • Price — The per-unit rate (e.g., $0.045 per SMS)
  • Pricing Code — A unique identifier used to match API usage events (auto-generated from name, e.g., sms-notifications)
Usage-based product form with charge type, aggregation, price, and pricing code

Scroll down to see the Pricing Code field — this is what you'll reference when sending usage events via the API.

Pricing code field showing sms-notifications

Click Save product to create it.

Charge Types

Charge Type Description Example
Per unit (flat rate) Single price per unit of usage $0.045 per SMS sent
Per tier (volume-based) Different rates for different usage levels. Each tier can have its own unit price and an optional flat fee. 0–10k calls at $0.01/call, 10k–100k at $0.008/call

Aggregation Methods

Method Description Use Case
Sum Total of all usage values API calls, tokens, data transfer
Count Number of usage events Active users, sessions
Max Highest value in period Peak concurrent users, max storage
Min Lowest value in period Minimum commitment tracking

Step 2: Add Usage Products to a Contract

Upload a contract and proceed to Step 2: Commercial Terms. Usage-based products can be added alongside fixed-price products.

What's Different for Usage Products

Scroll down to the SMS Notifications product to see the key differences:

  • Units show "Metered" instead of a quantity input — the quantity is determined by actual usage events, not set upfront
  • Billing is forced to arrears — "Billed first of next period" is selected and the dropdown is disabled. This is because the final amount depends on actual consumption during the period.
  • Pricing summary shows the per-unit rate and minimum price (e.g., "$0.05/unit, min $15.00 – Every 1 month")

Why Arrears?

With fixed pricing, you know the amount upfront and can bill at the start of the period. With usage-based pricing, the total depends on actual consumption during the period. Monk enforces arrears billing so the invoice is only finalized after the usage period ends and all events have been aggregated.

Step 3: Review and Complete the Contract

Click Next to proceed to the review step. The invoice schedule shows how fixed and usage-based charges are combined:

The invoicing schedule clearly shows which invoices include usage-based charges:

  • INV-1 (January): $350.00 — flat fee only (no usage in arrears yet)
  • INV-2 through INV-4 (February–April): "$350.00 + based on usage" — flat fee plus usage from the prior month
  • INV-5 (May): "Based on usage" — only the final month's usage in arrears

Click Complete to create the contract and generate all invoices.

Step 4: View Customer Invoices

Click View Customer to see the generated invoices:

All invoices start as DRAFTED. Notice the totals — invoices with usage charges show $365.00 ($350 flat + $15 minimum usage fee).

Step 5: Invoice Detail — Metered Line Items

Click into an invoice with usage to see the line item detail:

Key things to notice:

  • SMS Notifications has a metered icon (⟳) next to the quantity — hovering shows the tooltip: "Usage-based: Metered quantity that updates as new usage is recorded"
  • The quantity starts at the minimum (here, $15.00) until actual usage events are matched
  • The quantity is read-only — you cannot manually edit metered line items

Step 6: Sending Usage Events

There are two ways to send usage data to Monk:

Via Dashboard (Manual)

Navigate to Usage-Based in the left sidebar under AR.

Click + Add usage to manually record a usage event:

Fill in:

  1. Customer — Search and select the customer
  2. Pricing — Select from usage-based pricings (shown by code and name)
  3. Quantity — Number of units to record (e.g., 400 SMS)
  4. Timestamp (optional) — When the usage occurred. Defaults to now.

Click Create usage to submit.

Via API (Recommended for Production)

Send usage events as they happen using the Create Usage Event API.

const response = await fetch('https://app.monk.com/api/v1/usages', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer mk_live_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    customerId: 'customer-uuid-here',
    pricingCode: 'sms-notifications',
    quantity: 400,
    idempotencyKey: 'sms_oatmeal_2026-02-05T14:52:00Z',
  }),
});

API Fields

Field Required Description
customerId Yes UUID of the customer in Monk
pricingCode Yes Matches the code on the product pricing
quantity Yes The usage amount (must be positive)
idempotencyKey Yes Unique key to prevent duplicates on retries
timestamp No ISO 8601 timestamp of when usage occurred. Defaults to now.
properties No Key-value metadata (e.g., model, region, feature)

API Responses

Status Meaning
201 Usage event created successfully
401 Invalid API key
403 API key missing usage:write scope
409 Duplicate idempotency key (event already exists)
422 Customer or pricing code not found

Via CSV (Coming Soon)

Bulk CSV upload for importing historical usage data or batch events from external systems.

For full API documentation, see Usage-Based Pricing Guide and Create Usage Event API Reference.

Step 7: Automatic Usage Matching

After submitting usage events, they appear in the Unmatched section. Matching runs automatically a few minutes after new events arrive.

Once matched, the event moves to the Matched section:

How Matching Works

  1. Contract created → Monk pre-generates invoices for each billing period
  2. Usage events sent → Events are stored as "unmatched" initially
  3. Matching runs → A background job finds the correct invoice by matching the customer, pricing code, and service period dates
  4. Invoice updated → The line item quantity is recalculated using the configured aggregation method, and the invoice total is updated

Step 8: Invoice Updated with Usage

After matching, the invoice automatically reflects the actual usage:

Before matching: SMS Notifications showed quantity 1 at $15.00 (minimum price)

After matching: SMS Notifications now shows quantity 400 at $0.05/unit = $20.00 — exceeding the $15 minimum, so the actual usage amount applies.

The invoice total updated from $365.00 to $368.00 ($350 platform fee + $18.00 usage).

No manual intervention needed — Monk automatically recalculates the invoice when usage events are matched.

Best Practices

  • Send events in real-time. Send usage events as they happen rather than batching at end of period. This ensures accurate billing even if your system has issues.
  • Use meaningful pricing codes. Choose descriptive, lowercase codes with hyphens (e.g., sms-notifications, api-calls). These appear in invoices and reports.
  • Always use idempotency keys. Generate unique keys for every event. Structure them meaningfully: {metric}_{customer}_{timestamp} (e.g., sms_oatmeal_2026-02-05T14:52:00Z).
  • Handle API errors gracefully. If the usage API returns an error, queue the event for retry. The idempotency key prevents duplicates on retries.
  • Include timestamps for accuracy. Pass the timestamp field when usage occurred, especially if sending events with a delay. This ensures usage is attributed to the correct billing period.

Troubleshooting

Pricing code not found (422)

Cause: The pricingCode in the API request doesn't match any active usage-based pricing in your organization.

Fix: Verify the code matches exactly (case-sensitive) with the code configured on the product pricing in Product Plans.

Customer not found (422)

Cause: The customerId UUID doesn't match any customer in your organization.

Fix: Use the List Customers API or check the Customers page to find the correct UUID.

Duplicate event (409)

Cause: An event with this idempotencyKey was already created. This is expected behavior when retrying a previously successful request.

Fix: No action needed — the original event was already recorded. Use a new idempotency key for genuinely new events.

Usage not appearing on invoice

Cause: The usage event's timestamp falls outside the invoice's service period, or the matching job hasn't run yet.

Fix:

  1. Check that the event timestamp is within the invoice's service period dates
  2. Wait a few minutes for the matching job to run
  3. Verify the event appears in the Unmatched section on the Usage-Based page

Related Articles