@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
Rate Limiting
Performance Monitoring
Multi-Tenant SaaS
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.