usage-based-billing

Dodo Payments Usage-Based Billing

Reference: docs.dodopayments.com/features/usage-based-billing

Charge customers for what they actually use—API calls, storage, AI tokens, or any metric you define.

---

When to use this skill

• You need to bill customers based on consumption (API calls, tokens, storage, bandwidth).
• You want to combine usage charges with subscriptions or one-time purchases.
• You need to track and aggregate events into billable quantities.
• You're building an AI service, SaaS platform, or infrastructure product with metered features.

---

Core Concepts

Events

Usage records sent from your application to Dodo. Each event is attributed to a customer and matched to a meter by its event_name.

{
  "event_id": "evt_unique_123",
  "customer_id": "cus_abc123",
  "event_name": "api.call",
  "timestamp": "2025-01-21T10:30:00Z",
  "metadata": { "endpoint": "/v1/users", "tokens": 150 }
}

Meters

Filters and aggregates events into billable quantities. A meter specifies:

• Event name: which events to match (case-sensitive)
• Aggregation type: how to combine events (count, sum, max, last)
• Measurement unit: the billing unit (calls, tokens, GB, etc.)
• Optional filters: conditions events must meet to be counted

Aggregation Types

Type	Use Case	Example
Count	Total events	API calls, image generations
Sum	Add values from a property	Tokens used, bytes transferred
Max	Highest value in a period	Peak concurrent users
Last	Most recent value	Current storage used

For sum, max, and last, you specify which metadata property to aggregate.

Pricing

Attach a meter to a product price to charge per unit:

• Price per unit: e.g., $0.001 per API call
• Free threshold: e.g., 1,000 free calls per month
• Charge formula: (usage − threshold) × price_per_unit