Usage-Based Billing

Usage-based billing lets you charge customers based on what they actually consume rather than a flat subscription price. This model is common for API products, compute services, messaging platforms, and any product where usage varies between customers.

mavi pay provides a complete metering and billing pipeline: you define meters, ingest usage events via API, and mavi pay calculates charges at the end of each billing cycle.

Core Concepts

Meters

A meter defines what you are measuring. Each meter has a name, a unit (e.g., "API calls", "messages", "GB"), and an aggregation method.

Create meters in your dashboard under Usage Billing > Meters or via the API.

Events

Events are the raw usage data points. Each event has a timestamp, a customer ID, a meter event name, and an optional numeric value.

Billing Cycles

At the end of each billing cycle (monthly by default), mavi pay aggregates all events for each customer, calculates the total usage per meter, applies your pricing tiers, and creates an invoice.

Ingesting Events

Send usage events to the mavi pay API as they occur in your application. Events are processed asynchronously and do not block your application.

API Endpoint

POST https://api.mavifinans.sh/api/v1/usage/events

Request Body

{
  "events": [
    {
      "customer_id": "cus_xxxxxxxx",
      "event_name": "api_request",
      "timestamp": "2026-03-30T12:00:00Z",
      "value": 1
    }
  ]
}

Authentication

Include your API key in the Authorization header:

curl -X POST https://api.mavifinans.sh/api/v1/usage/events \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "customer_id": "cus_xxxxxxxx",
        "event_name": "api_request",
        "timestamp": "2026-03-30T12:00:00Z",
        "value": 1
      }
    ]
  }'

You can send events individually or in batches of up to 1,000 events per request. Batching is recommended for high-volume applications.

Pricing Models

When you attach a meter to a product, you define how usage translates to charges:

Per-Unit Pricing

A flat rate per unit of usage. For example, EUR 0.001 per API request.

Tiered Pricing

Different rates for different usage brackets. For example:

Included Units

You can include a number of free units per billing cycle. Only usage above the included amount is charged. This is useful for freemium models where a base tier includes a usage allowance.

Monitoring Usage

From the dashboard, you can:

• View real-time usage per customer and per meter.
• Set alerts when a customer approaches a threshold (e.g., 80% of their typical usage).
• Export usage data as CSV for reconciliation or reporting.
• Preview invoices before the billing cycle closes to see estimated charges.

Billing Cycle Flow

1. Usage events are ingested throughout the billing period.
2. At the end of the cycle, mavi pay aggregates events per meter and customer.
3. Pricing rules are applied to calculate the total charge.
4. An invoice is generated and the customer is charged via Stripe.
5. If payment succeeds, the order is recorded and benefits remain active.
6. If payment fails, Stripe retries according to your retry settings.

Next Steps

• Create products and attach meters for usage-based pricing.
• Manage customers and monitor their usage.
• Review payouts to track revenue from usage billing.