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

# Configure usage-based billing

> Step-by-step guide to set up your first usage-based subscription

This guide walks you through setting up a complete usage-based billing workflow in Hyperline, from connecting your data to monitoring customer consumption. By the end, you'll have a working usage-based subscription with real-time usage tracking.

## Context

You want to bill customers based on their actual consumption of your product or service—such as API calls, compute hours, storage, or any other measurable metric. This guide shows you how to configure this end-to-end using Hyperline's interface.

## Prerequisites

Before you begin, make sure you have:

* Access to your Hyperline account (we recommend using [test mode](../docs/getting-started/sandbox) for this setup)
* Usage data ready to import, or the ability to generate simulated data for testing
* A clear understanding of what metric you want to bill (e.g., API calls, GB stored, hours used)

<Info>
  When signed up and landed on Hyperline, you can use the [test mode](../docs/getting-started/sandbox) to experiment before going live.
</Info>

## Steps

### 1. Connect your usage data

Hyperline needs usage data to calculate charges for usage-based products. You have three options to connect your data:

<CardGroup cols={3}>
  <Card title="CSV import" icon="file-csv" href="../docs/usage/import-events-csv">
    Upload historical data from a CSV file
  </Card>

  <Card title="API integration" icon="code" href="../docs/usage/send-usage-data">
    Send events programmatically via API
  </Card>

  <Card title="Data loaders" icon="database" href="../docs/usage/usage-data-with-connectors">
    Connect directly to your database
  </Card>
</CardGroup>

<Tip>
  For testing purposes, you can skip this step initially and use [simulated events](../docs/usage/simulate-usage-data) directly in test mode.
</Tip>

#### Using data loaders (recommended)

Data loaders allow you to pull usage data directly from your database without writing code. This is ideal for connecting to existing data sources like PostgreSQL, BigQuery, MongoDB, or Snowflake.

<Steps>
  <Step title="Navigate to data loaders">
    Go to the [data loaders page](https://app.hyperline.co/app/events/loaders) in Hyperline.
  </Step>

  <Step title="Create a new connection">
    Click **New connection** and select your database provider from the list.
  </Step>

  <Step title="Enter connection details">
    Fill in your database connection information:

    * Host and port
    * Database name
    * Authentication credentials
    * SSL settings (if required)
  </Step>

  <Step title="Create a data loader">
    After connecting, create a new data loader with a SQL query that returns:

    * `timestamp` - The date and time of the event
    * `customerId` - Your customer's unique identifier
    * `id` - The event's unique identifier
    * Any additional fields you want to track (e.g., `quantity`, `region`, `product_type`)
  </Step>

  <Step title="Test and activate">
    Test your query to ensure data is flowing correctly, then activate the data loader.
  </Step>
</Steps>

<Note>
  Learn more about configuring data loaders in our detailed guides:

  * [BigQuery](../docs/usage/bigquery)
  * [MongoDB](../docs/usage/mongodb)
  * [Snowflake](../docs/usage/snowflake)
  * [General data loaders](../docs/usage/usage-data-with-connectors)
</Note>

### 2. Create a usage-based product

Once your events are flowing into Hyperline, you can create a product that bills based on this usage.

<Steps>
  <Step title="Navigate to the product catalog">
    Go to [**Products**](https://app.hyperline.co/app/products) and click **New product**.
  </Step>

  <Step title="Select usage-based product type">
    Choose **Usage** as the product type.

    Fill in the basic product information:

    * **Name**: A descriptive name for your product (e.g., "API Calls", "Storage GB")
    * **Description**: Optional details about what this product represents
  </Step>

  <Step title="Link an aggregator">
    Connect your product to the usage data you want to bill by selecting an [aggregator](../docs/usage/aggregators). If you haven't created one yet, head to **Usage > Aggregators** first.

    The aggregator defines:

    * **Event type**: Which events to aggregate
    * **Operation**: How to calculate usage:
      * **Count**: Count the number of events
      * **Sum**: Add up a specific numeric property
    * **Filters**: Optional conditions to narrow eligible events
  </Step>

  <Step title="Define pricing tiers">
    Set up your pricing model:

    * **Pricing model**: Choose between:
      * **Volume pricing**: Price per unit changes based on total usage
      * **Bulk pricing**: All units charged at the rate of the tier reached
      * **Basis points**: Percentage-based pricing
    * **Price tiers**: Define your pricing tiers and amounts
      * Example: $0.10 per unit for 0-1,000 units, $0.08 per unit for 1,001-10,000 units
    * **Billing interval**: Set when this product should be billed (monthly, quarterly, yearly)

    Make sure to configure at least one recurring price before moving to the next step.
  </Step>

  <Step title="Save the product">
    Click **Save** to add the product to your catalog.
  </Step>
</Steps>

<Card title="Example 💡">
  You want to charge for API calls with volume pricing:

  * 0-10,000 calls: \$0.01 per call
  * 10,001-100,000 calls: \$0.008 per call
  * 100,001+ calls: \$0.005 per call

  Create a "Count" aggregator on your API event type, link it to your usage product, then set up three pricing tiers with these rates.
</Card>

<Info>
  For detailed information on metering configuration options, see our [usage-based products guide](../docs/products/metering).
</Info>

### 3. Create a customer

Before assigning a subscription, you need a customer in Hyperline.

<Steps>
  <Step title="Go to the Customers section">
    Navigate to [**Customers**](https://app.hyperline.co/app/customers) and click **New Customer**.
  </Step>

  <Step title="Fill in customer details">
    Enter the required information:

    * **Name**: Customer or company name
    * **Currency**: The currency for billing this customer
    * **Country**: Customer's country (used for tax calculations)

    You can add additional details like email, address, and tax information, or update them later.
  </Step>

  <Step title="Save the customer">
    Click **Save customer** to create the customer record.
  </Step>
</Steps>

<Note>
  Learn more about customer management in our [customer creation guide](../docs/customers/overview).
</Note>

### 4. Configure a subscription with the usage product

Now you'll create a subscription that includes your usage-based product.

<Steps>
  <Step title="Start creating a subscription">
    From your customer's page, click **Actions** → **Assign new subscription**.

    Alternatively, go to [**Subscriptions**](https://app.hyperline.co/app/subscriptions/create) and select your customer.
  </Step>

  <Step title="Set subscription duration">
    Configure when the subscription starts:

    * **Immediately**: Start billing right away
    * **In the future**: Schedule for a specific date
    * **On checkout completion**: Wait for customer to complete checkout
  </Step>

  <Step title="Add your usage-based product">
    Click **Add product** and select the usage-based product you created earlier.

    Configure the product settings:

    * **Pricing**: Select or customize the pricing tier
    * **Metering period**: Choose when usage is measured:
      * **Same as payment interval**: Usage resets each billing cycle
      * **Committed period**: Usage measured over the entire contract
      * **Custom**: Define a specific metering window
    * **Min/max amounts**: Optionally set spending limits per billing period
    * **Committed units**: Set minimum usage commitments if needed (customer pays for at least X units)
  </Step>

  <Step title="Configure payment settings">
    Click **Next** to access payment settings.

    For testing purposes, select **Manually later** to create the subscription without immediate payment.

    For production, choose:

    * **Checkout page**: Customer completes payment via Hyperline checkout
    * **Immediately**: Charge the customer's default payment method
  </Step>

  <Step title="Assign the subscription">
    Click **Assign subscription** to activate it.

    You'll be redirected to the customer page where you can see the subscription and current usage.
  </Step>
</Steps>

<Card title="Example 💡">
  A customer subscribes to your API product with monthly billing. They have a committed minimum of 5,000 API calls per month (they'll be charged for at least 5,000 calls even if they use fewer), and a maximum spending cap of \$500 per month to prevent unexpected bills.
</Card>

<Info>
  For more details on subscription configuration options, see our [subscription setup guide](../docs/subscriptions/create).
</Info>

### 5. Simulate usage (optional, for testing)

If you're in [test mode](../docs/getting-started/sandbox), you can simulate usage events to see how billing works without real data.

<Steps>
  <Step title="Go to the customer's Events tab">
    From your customer's page, click the **Events** tab.
  </Step>

  <Step title="Click Simulate new events">
    Look for the **Simulate new events** button at the top of the events list.
  </Step>

  <Step title="Configure the simulated events">
    Fill in the details:

    * **Event type**: Use the same event type configured in your product
    * **Date**: Choose when the events occurred (must be within the current billing period)
    * **Number of events**: How many events to create
    * **Payload** (optional): Add custom event properties in JSON format
      ```json theme={null}
      {
        "quantity": 100,
        "region": "us-east-1"
      }
      ```
  </Step>

  <Step title="Create the events">
    Click **Create new events**. The events will appear in the customer's event list after a few seconds.
  </Step>
</Steps>

<Tip>
  You can delete simulated events at any time if you need to reset your test data. This is only available in test mode.
</Tip>

<Note>
  Learn more about simulating usage in our [simulate usage data guide](../docs/usage/simulate-usage-data).
</Note>

### 6. Monitor usage and understand open invoices

After creating usage events, you can track consumption and preview upcoming charges.

#### View current usage

From the customer's **Subscriptions** tab, you'll see the current usage displayed next to each usage-based product.

Click the eye icon next to the unit count to open the consumption details modal, which shows:

* Total usage for the current billing period
* Individual events contributing to the usage
* Calculated amount based on your pricing tiers
* Breakdown by time period or event properties

<Info>
  For detailed usage analysis and exports, see our [explore usage consumption guide](../docs/usage/explore-usage-consumption).
</Info>

#### Understanding open invoices

An **open invoice** is a live preview of the invoice that will be charged at the end of the billing period. For usage-based subscriptions, this invoice updates automatically in real-time as new usage events are recorded.

**Key characteristics of open invoices:**

* **No invoice number yet**: Open invoices don't have a final invoice number because they're still being calculated
* **Cannot be paid**: Customers cannot pay an open invoice—it's for preview purposes only
* **Updates in real-time**: As usage accumulates, the invoice amount increases automatically
* **Visible to customers**: Customers can see their open invoice in the [customer portal](../docs/customers/portal) to track their current charges

**To view an open invoice:**

1. Go to the customer's **Invoices** tab
2. Look for the invoice with status `open`
3. Click on the invoice to see the current charges and line items

<Card title="Example 💡">
  A customer subscribes on January 1st with monthly billing. An open invoice is immediately created for the January 1-31 period. As they make API calls throughout the month, the invoice updates:

  * January 5: 2,500 calls → Invoice shows \$25
  * January 15: 8,000 calls → Invoice shows \$80
  * January 31: 15,000 calls → Invoice shows \$138 (with tiered pricing)

  On February 1st, the invoice enters the grace period for final review.
</Card>

#### Invoice lifecycle for usage-based billing

Usage-based invoices follow this lifecycle:

1. **Open**: Invoice is created at the start of the billing period and updates as usage accumulates
2. **Grace period**: At the end of the billing period, the invoice enters a grace period (default: 3 days) where you can review and make manual adjustments if needed
3. **To pay**: After the grace period, the invoice is finalized with an invoice number and sent for payment
4. **Paid**: Payment is collected and the invoice is settled

<Warning>
  During the grace period, you can still make adjustments to the invoice (add credits, apply discounts, etc.). Once the grace period ends, the invoice is locked and cannot be modified.
</Warning>

<Info>
  You can configure the grace period duration in **Settings** → **Invoicing**. Learn more about [invoice terms and grace periods](../docs/invoices/term).
</Info>

## Next steps

You've successfully set up a usage-based subscription! Here are some ways to expand your implementation:

<CardGroup cols={2}>
  <Card title="Explore consumption data" icon="chart-line" href="../docs/usage/explore-usage-consumption">
    View detailed usage reports and export data
  </Card>

  <Card title="Configure metering options" icon="sliders" href="../docs/products/metering">
    Learn about advanced metering configurations
  </Card>

  <Card title="Manage subscriptions" icon="arrows-rotate" href="../docs/subscriptions/manage">
    Update, pause, or cancel subscriptions
  </Card>

  <Card title="Set up invoicing" icon="file-invoice" href="../docs/invoices/configuration">
    Customize invoice templates and settings
  </Card>
</CardGroup>

<Info>
  Is something still unclear? Don't hesitate to reach out to our team via the in-app chat if you need additional support.
</Info>