> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Stream Blueprint

> Track the bytes each customer streams for video, audio, live streams, and real-time data transfer, and bill them for bandwidth in Dodo Payments.

The Stream Blueprint sends a usage event to Dodo Payments with the number of bytes a customer consumed from a stream. A **Sum** meter over `bytes` adds up each customer's bandwidth, so you can bill for it. The blueprint ships in the `@dodopayments/ingestion-blueprints` npm package as `trackStreamBytes()`.

## Use Cases

The Stream Blueprint fits these scenarios:

<CardGroup cols={2}>
  <Card title="Video Platforms" icon="video">
    Bill customers for video bandwidth consumption and streaming quality.
  </Card>

  <Card title="Music Streaming" icon="music">
    Track audio streaming usage per user for subscription tiers.
  </Card>

  <Card title="Live Events" icon="signal-stream">
    Monitor live stream consumption and charge for bandwidth usage.
  </Card>

  <Card title="Real-Time Data" icon="wave-pulse">
    Track real-time data transfer for IoT and telemetry applications.
  </Card>
</CardGroup>

<Info>
  Use it for video and audio streaming platforms, live streaming services, and real-time data applications.
</Info>

## Quick Start

To track streaming usage, install the package, create a meter, and send the bytes each customer consumes.

<Steps>
  <Step title="Install the SDK">
    Install the Dodo Payments Ingestion Blueprints package:

    ```bash theme={null}
    npm install @dodopayments/ingestion-blueprints
    ```
  </Step>

  <Step title="Get Your API Keys">
    Create a Dodo Payments API key under **Developer → API Keys** in the [Dodo Payments dashboard](https://app.dodopayments.com/developer/api-keys), 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`.
  </Step>

  <Step title="Create a Meter">
    In the [Dodo Payments dashboard](https://app.dodopayments.com/), go to **Products → Meters** and click **Create Meter**. Set these fields:

    * **Meter Name**: a descriptive name, such as `Stream Bandwidth`.
    * **Event Name**: `stream_consumption`, or a name you choose. It must match `eventName` in your code exactly (case-sensitive).
    * **Aggregation Type**: **Sum**, to add up the bytes streamed.
    * **Over Property**: `bytes`, to bill by bandwidth usage.
    * **Measurement Unit**: the unit shown on invoices, such as `bytes`.
  </Step>

  <Step title="Track Stream Usage">
    Call `trackStreamBytes()` with the customer and the number of bytes consumed:

    <CodeGroup>
      ```javascript Video Streaming theme={null}
      import { Ingestion, trackStreamBytes } from '@dodopayments/ingestion-blueprints';

      const ingestion = new Ingestion({
        apiKey: process.env.DODO_PAYMENTS_API_KEY,
        environment: 'test_mode',
        eventName: 'stream_consumption'
      });

      // Track video stream consumption
      await trackStreamBytes(ingestion, {
        customerId: 'cus_123',
        bytes: 10485760, // 10MB
        metadata: {
          stream_type: 'video',
        }
      });
      ```
    </CodeGroup>
  </Step>
</Steps>

## Configuration

### Ingestion Configuration

Pass these options to `new Ingestion()`:

<ParamField path="apiKey" type="string" required>
  Your Dodo Payments API key from the dashboard.
</ParamField>

<ParamField path="environment" type="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.
</ParamField>

<ParamField path="eventName" type="string" required>
  Event name that matches your meter's **Event Name** (case-sensitive).
</ParamField>

### Track Stream Bytes Options

Pass these options to `trackStreamBytes()`:

<ParamField path="customerId" type="string" required>
  The Dodo Payments customer ID to bill for the stream, for example `cus_123`.
</ParamField>

<ParamField path="bytes" type="number">
  Number of bytes consumed in the stream. Required for bandwidth-based billing. If you omit it, the event has no `bytes` value, but it still counts toward a **Count** meter.
</ParamField>

<ParamField path="metadata" type="object">
  Optional metadata about the stream, such as stream type, quality, or session ID. Each value must be a string, number, or boolean.
</ParamField>

## Best Practices

<Tip>
  **Track by Chunk**: For long streams, track consumption in chunks rather than waiting for the entire stream to complete.
</Tip>

Each call to `trackStreamBytes()` sends a separate event, and a **Sum** meter adds the chunks together.

<Warning>
  **Accurate Byte Counting**: If you bill for total bandwidth, include all overhead, such as headers and protocol overhead, in your byte counts.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.