Skip to main content
The Time Range Blueprint sends a usage event to Dodo Payments with how long a resource ran for a customer, in milliseconds, seconds, or minutes. A Sum meter over that duration adds up each customer’s runtime, so you can bill for compute time. The blueprint ships in the @dodopayments/ingestion-blueprints npm package as trackTimeRange().

​
Use Cases

The Time Range Blueprint fits these scenarios:

Serverless Functions

Bill based on function execution time and memory usage.

Container Runtime

Track container running time for usage-based billing.

Compute Instances

Monitor VM runtime and charge by the minute or hour.

Background Jobs

Track processing time for data exports, reports, and batch jobs.
Use it to bill for compute time, function execution duration, container runtime, or any other time-based usage.

​
Quick Start

To track runtime, install the package, create a meter, and send the duration each time a resource finishes running.
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 Compute Time.
  • Event Name: time_range_usage, or a name you choose. It must match eventName in your code exactly (case-sensitive). The examples in the next step use a separate event name for each resource type, such as function_execution, so each one needs its own meter.
  • Aggregation Type: Sum, to add up the total duration.
  • Over Property: the duration key you send: durationSeconds, durationMinutes, or durationMs.
  • Measurement Unit: the unit shown on invoices, such as seconds.
4

Track Time Usage

Measure how long the work ran, then call trackTimeRange() with the duration in the unit your meter uses:

​
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).

​
Track Time Range Options

Pass these options to trackTimeRange(). Each duration you pass is sent as a metadata key with the same name.
​
string
required
The Dodo Payments customer ID to bill for the runtime, for example cus_123.
​
number
Duration in milliseconds. Use for sub-second precision.
​
number
Duration in seconds. Most common for function execution and short tasks.
​
number
Duration in minutes. Useful for longer-running resources like VMs.
​
object
Optional metadata about the resource, such as CPU, memory, or region. Each value must be a string, number, or boolean.

​
Best Practices

Choose the Right Unit: Use milliseconds for short operations, seconds for functions, and minutes for longer-running resources.
A meter sums only the key that its Over Property names, so send the duration in the same unit every time.
Accurate Timing: Use Date.now() or performance.now() for accurate time tracking, especially for serverless functions.
Last modified on September 26, 2026