Skip to main content
The API Gateway Blueprint sends a usage event to Dodo Payments for each API call your service handles, and a Count meter turns those events into a per-call charge for each customer. Use it to track API endpoint usage, to inform rate limits, and to bill for API usage. It ships in the @dodopayments/ingestion-blueprints npm package as trackAPICall(), which sends one event per call, and createBatch(), which queues events for high request volumes.

Use Cases

The API Gateway Blueprint fits these scenarios:

API-as-a-Service

Track calls per customer on an API platform and charge by the number of calls.

Rate Limiting

Record each customer’s call volume to inform usage-based rate limits. The blueprint records usage but doesn’t enforce limits.

Performance Monitoring

Record response times and status codes with each event, so error rates sit next to billing data.

Multi-Tenant SaaS

Bill customers for their API consumption across different endpoints.
Every event needs the Dodo Payments customer ID of the customer you bill, which starts with cus_. Store it with your user record when you create the customer, and pass it as customerId.

Quick Start

To track API calls, install the package, create a meter, and send an event for each call.
1

Install the SDK

Install the Dodo Payments Ingestion Blueprints package:
2

Get Your API Keys

Create a Dodo Payments API key under Developer → API Keys in the Dodo Payments dashboard, and store it in the DODO_PAYMENTS_API_KEY environment variable. Use a test mode key while you build. A test mode key works only with test_mode.
3

Create a Meter

In the Dodo Payments dashboard, go to Products → Meters and click Create Meter. Set these fields:
  • Meter Name: a descriptive name, such as API Calls.
  • Event Name: api_call, or a name you choose. It must match eventName in your code exactly (case-sensitive).
  • Aggregation Type: Count, to bill by the number of calls.
  • Measurement Unit: the unit shown on invoices, such as calls.
To count only some calls, turn on Enable Event Filtering and add conditions on metadata keys such as endpoint, method, or status_code.
4

Track API Calls

Create one Ingestion instance with your API key and event name, then choose a pattern: one event per call, a batch for high volume, or Express.js middleware that tracks every request. In the middleware, req.user comes from your authentication middleware, and its id must be a Dodo Payments customer ID. Requests without a signed-in user are sent with the customer ID anonymous, which doesn’t match any customer.

Configuration

Ingestion Configuration

Pass these options to new Ingestion():
string
required
Your Dodo Payments API key from the dashboard.
string
Environment mode: test_mode or live_mode. Defaults to test_mode. The Dodo Payments SDKs default to live_mode instead, so set live_mode explicitly in production.
string
required
Event name that matches your meter’s Event Name (case-sensitive). Every event this instance sends uses it.

Track API Call Options

Pass these options to trackAPICall() and batch.add():
string
required
The Dodo Payments customer ID to bill for the call, for example cus_123.
object
Optional metadata about the API call, such as endpoint, method, status code, and response time. Each value must be a string, number, or boolean. The API rejects nested objects, arrays, and null values.

Batch Configuration

createBatch(ingestion, options) queues events in memory and returns an object with three methods: add() queues an event, flush() sends the queued events, and cleanup() sends them and stops the timer. A flush sends one ingest request per event, in parallel.
number
Number of queued events that triggers an immediate flush. Default: 100.
number
Milliseconds to wait after the most recent add() before the batch flushes. Each add() restarts the timer. Default: 5000 (5 seconds).

Best Practices

Use Batching for High Volume: For high-traffic applications, use createBatch(). batch.add() returns immediately, so tracking doesn’t add latency to your request handler.
A batch holds events in memory until it flushes, and it doesn’t retry events that fail to send. An automatic flush logs the error with console.error. A call to flush() or cleanup() throws it.
Clean Up Batches on Shutdown: Call batch.cleanup() when your application shuts down, so pending events are flushed instead of lost.
Last modified on September 26, 2026