Skip to main content
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 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)
When signed up and landed on Hyperline, you can use the test mode to experiment before going live.

​
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:

CSV import

Upload historical data from a CSV file

API integration

Send events programmatically via API

Data loaders

Connect directly to your database
For testing purposes, you can skip this step initially and use simulated events directly in test mode.
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.
1

Navigate to data loaders

Go to the data loaders page in Hyperline.
2

Create a new connection

Click New connection and select your database provider from the list.
3

Enter connection details

Fill in your database connection information:
  • Host and port
  • Database name
  • Authentication credentials
  • SSL settings (if required)
4

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)
5

Test and activate

Test your query to ensure data is flowing correctly, then activate the data loader.
Learn more about configuring data loaders in our detailed guides:

​
2. Create a usage-based product

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

Navigate to the product catalog

Go to Products and click New product.
2

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
3

Link an aggregator

Connect your product to the usage data you want to bill by selecting an aggregator. 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
4

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.10perunitfor0−1,000units,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.
5

Save the product

Click Save to add the product to your catalog.

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.
For detailed information on metering configuration options, see our usage-based products guide.

​
3. Create a customer

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

Go to the Customers section

Navigate to Customers and click New Customer.
2

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.
3

Save the customer

Click Save customer to create the customer record.
Learn more about customer management in our customer creation guide.

​
4. Configure a subscription with the usage product

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

Start creating a subscription

From your customer’s page, click Actions → Assign new subscription.Alternatively, go to Subscriptions and select your customer.
2

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
3

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)
4

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
5

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.

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.
For more details on subscription configuration options, see our subscription setup guide.

​
5. Simulate usage (optional, for testing)

If you’re in test mode, you can simulate usage events to see how billing works without real data.
1

Go to the customer's Events tab

From your customer’s page, click the Events tab.
2

Click Simulate new events

Look for the Simulate new events button at the top of the events list.
3

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
4

Create the events

Click Create new events. The events will appear in the customer’s event list after a few seconds.
You can delete simulated events at any time if you need to reset your test data. This is only available in test mode.
Learn more about simulating usage in our simulate usage data guide.

​
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
For detailed usage analysis and exports, see our explore usage consumption guide.

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

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.

​
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
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.
You can configure the grace period duration in Settings → Invoicing. Learn more about invoice terms and grace periods.

​
Next steps

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

Explore consumption data

View detailed usage reports and export data

Configure metering options

Learn about advanced metering configurations

Manage subscriptions

Update, pause, or cancel subscriptions

Set up invoicing

Customize invoice templates and settings
Is something still unclear? Don’t hesitate to reach out to our team via the in-app chat if you need additional support.