Skip to main content
The Object Storage Blueprint sends a usage event to Dodo Payments each time a customer uploads a file, with the number of bytes uploaded. A Sum meter over bytes adds up each customer’s upload volume, so you can bill for it. The blueprint ships in the @dodopayments/ingestion-blueprints npm package as trackObjectStorage(), and it works with S3, Google Cloud Storage, Azure Blob Storage, and other object storage services.

Use Cases

The Object Storage Blueprint fits these scenarios:

File Hosting

Bill customers for the total volume of files they upload.

Backup Services

Track backup data uploads and charge for the amount of data uploaded.

Media CDN

Monitor media uploads and bill for upload volume. To bill for delivery bandwidth, use the Stream Blueprint.

Document Management

Track document uploads per customer for usage-based pricing.
Use it to bill by upload volume for file hosting, media CDN, and backup services. The blueprint counts bytes uploaded, not bytes stored over time.

Quick Start

To track uploads, install the package, create a meter, and send an event after each successful upload.
1

Install the SDK

Install the Dodo Payments Ingestion Blueprints package:
2

Get Your API Keys

You need two sets of credentials:
  • Dodo Payments API key: Create one under Developer → API Keys in the Dodo Payments dashboard, and store it in DODO_PAYMENTS_API_KEY. Use a test mode key while you build. A test mode key works only with test_mode.
  • Storage provider credentials: The credentials your storage SDK uses, for AWS S3, Google Cloud Storage, Azure Blob Storage, or another provider.
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 Storage Uploads.
  • Event Name: object_storage_upload, or a name you choose. It must match eventName in your code exactly (case-sensitive).
  • Aggregation Type: Sum, to add up the bytes uploaded.
  • Over Property: bytes, to bill by upload size.
  • Measurement Unit: the unit shown on invoices, such as bytes.
4

Track Storage Usage

Send the event after the storage call succeeds. In these examples, a failed upload throws before trackObjectStorage() runs, so it isn’t billed.

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 Object Storage Options

Pass these options to trackObjectStorage():
string
required
The Dodo Payments customer ID to bill for the upload, for example cus_123.
number
Number of bytes uploaded. Required for byte-based billing. If you omit it, the event has no bytes value, but it still counts toward a Count meter.
object
Optional metadata about the upload, such as bucket name or content type. Each value must be a string, number, or boolean.

Best Practices

Track Before or After Upload: You can track the event before or after the actual upload, depending on your error handling strategy.
The API has no endpoint to delete an ingested event. An event sent before an upload that then fails stays in the customer’s usage.
Handle Upload Failures: Only track successful uploads, so you don’t bill for failed operations.
Last modified on September 26, 2026