@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 matcheventNamein 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.
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 tonew 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 totrackAPICall() 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
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 withconsole.error. A call to flush() or cleanup() throws it.