Skip to main content
This page covers the full credit product lifecycle: catalog setup, customer balances, plan and subscription integration, expiration, and auto-topup. For an introduction to credits as a product type and where they sit in the catalog, see Products and prices.
PrerequisiteTo configure credits, you need to connect events first so Hyperline can detect usage data.

​
Create a credit product

To get started with credits, first create a credit product in your catalog, where you specify the events that rule the consumption. Hyperline then deducts credit usage automatically.
1

Select create new, product, and then the credit product

2

Product configuration

Add one or more aggregators to define which events consume credits on the customer’s balance. Each aggregator has a weight that determines how many credits are consumed per unit of usage.You can add aggregators directly from this form. If you need a new one, click Create aggregator to set it up without leaving the page.You can also configure display settings (public description) and set a low balance threshold to trigger warnings on the customer portal. The unit name shown to customers is inherited from the linked aggregator.Credit grant mode controls how many credits are granted on a partial period (e.g. mid-cycle start, upgrade, or automated top-up at the end of a period):
This setting only affects the credits granted, not the invoiced amount. The invoice is always prorated for partial periods. With Full allowance, the customer pays a fractional price but receives the full credit allowance.
Create credit balance as soon as the product is added to a subscription controls when the customer’s balance starts existing. Keep it enabled for the usual case. Disable it when the balance must not consume events before the subscription is active. See When the credit balance is created.
3

Pricing configuration

Select how the granted credit quantity determines the price:
  • Volume pricing applies progressive prices across quantity tiers.
  • Bulk pricing uses the tier reached by the total quantity to price all credits.
  • Bundle pricing offers predefined quantities at fixed prices. You can also select which bundles customers can purchase from the customer portal.
When you assign the credit product to a plan or subscription, enter the quantity of credits to grant and select a catalog price. Hyperline calculates the resulting amount and stores it as a fixed fee on the subscription while retaining the selected pricing configuration as context.

​
Multiple aggregators with weights

A credit product can be linked to multiple aggregators, each with its own weight. All aggregators consume from a single shared balance, but at different rates. The weight defines how many credits are deducted per unit of usage for that aggregator. For example, a weight of 3 means each unit of usage consumes 3 credits.

Example 💡

An AI platform sells credits that can be used across different models:A customer with 1,000 credits could use them for 200 GPT-4 requests, 1,000 GPT-3 requests, 100 image generations, or any combination.
If you only need a single aggregator, simply add one row with a weight of 1. This works exactly like a standard credit product.

​
Set up credits on a customer

Once your credit product is set up, you can enable a credit balance on your customer and link their credit usage immediately. You can also do this via the API.
1

On the customer's details page, go to the Credits tab and click Add credit balance

2

Credit balance form

Here, you can also change the name and starting balance, and set the credit warning limit. This won’t override the values previously set in your product catalog, but will be specific to the customer.
3

Monitor balance and consumption

Once the balance is created, a credits chart shows balance evolution over time. You can adjust the date range and granularity (daily, weekly, monthly) to analyze consumption patterns.Below the chart, the transactions table lists all credit movements (top-ups, usage, expirations). For products with multiple aggregators, an Aggregator column indicates which aggregator triggered each usage transaction. You can click a usage transaction to inspect and export the underlying consumption events.You can also manually top up or remove credits via the Actions menu.

​
Add credit products in plan and subscription

You can add credit products created in the product catalog to predefined billing plans and subscriptions like any other product. You can also change options for this product at the customer/subscription level, allowing full customization without altering your catalog configuration.

​
When the credit balance is created

By default, Hyperline creates the customer’s credit balance as soon as you add the credit product to a subscription. This includes draft subscriptions and quotes that have not been signed yet. From that moment the balance consumes reported events, and its starting balance accounts for the consumption your aggregators have already recorded. Disable Create credit balance as soon as the product is added to a subscription to delay this. The setting lives on the credit product in your catalog, and each subscription or quote can override it on its own credit product line. When it is disabled:
  • No balance exists while the subscription is a draft or the quote is unsigned, so nothing is consumed in the meantime.
  • On activation, the balance is created empty and the subscription’s credit allowance is granted immediately, so the customer starts with exactly the quantity purchased. Consumption recorded before that point is ignored. Only events reported afterwards are deducted.
  • You can also create the balance yourself beforehand, for example to carry over the credits left on a previous batch. The allowance granted on activation is then added to that balance.

Example 💡

A renewal is sold as a new credit product carrying 10,000 credits, and the quote is sent three weeks before the customer signs. With the setting disabled, no balance exists for that product while the quote is pending, so the usage reported during those three weeks is not charged against it. On signature, the subscription activates and the balance is credited with exactly 10,000 credits.
On a partial first period, the quantity granted also depends on the credit grant mode of the product. Select Full allowance when the customer must receive the whole quantity purchased regardless of when the period starts.

​
Consumption order

A customer’s credit balance is a single shared pool. When usage is reported (via events or via POST /v1/customers/{id}/credits/{productId}/usage), it is deducted from that pool. For accounting and expiration purposes, Hyperline attributes the deducted amount to individual top-ups in FIFO order by top-up creation date. The oldest top-up is drained first and the most recent one last. This applies regardless of whether a top-up has an expiration date or is permanent.
Consumption order is based on when each top-up was created, not on its expiration date. A permanent top-up created before a time-limited top-up will be drained first.If you want a “free” allowance (e.g. a plan-included monthly allowance) to be consumed before paid top-ups, make sure the allowance top-up is credited to the balance before any paid top-up on the same credit product. For recurring allowances tied to a subscription, the allowance is credited at the start of each billing period. As long as paid top-ups happen after that point, the allowance is consumed first.

​
Real-time consumption and limits

Credit balances are updated asynchronously when usage is reported through events. In production, balances can take about 60 seconds to reflect new consumption, because Hyperline intentionally buffers and processes usage in the background. Use the credit usage API endpoint (POST /v1/customers/{id}/credits/{productId}/usage) when you need to debit credits immediately from your own system. This synchronous debit flow is the right choice when you must enforce real-time limits, stop overconsumption, or block an action before confirming that the customer still has credits.
Test and production environments can feel different for credit timing. Always validate real-time enforcement against the same environment your application will use.

​
Credit expiration

You can configure credits to expire automatically, ensuring that unused credits don’t remain on customer balances indefinitely. There are two ways to set up credit expiration:

​
Expiration after a fixed number of days

Set a specific number of days after which credits will expire. This is useful for promotional credits or time-limited offers. When configuring a credit product on a subscription, you can specify how many days after the top-up the credits will expire.

​
Expiration at the end of the billing period

You can configure credits to expire at the end of each billing period. This is useful for monthly or annual credit allowances that should not roll over. When configuring a credit product on a subscription, you can enable this option. Credits will automatically expire when the billing period ends, and new credits will be added at the start of the next period.
When credits expire, an expiration transaction is automatically created in the credit ledger, and the customer’s balance is reduced accordingly. The oldest credits expire first.

​
Auto-topup

Auto-topup allows you to automatically replenish a customer’s credit balance when it falls below a specified threshold. This ensures uninterrupted service for your customers and reduces manual intervention.

​
How auto-topup works

When a customer’s credit balance drops below the configured low balance threshold, Hyperline can automatically:
  1. Create an invoice for the top-up amount
  2. Charge the customer’s payment method
  3. Add the credits to their balance

​
Configuration options

You can configure auto-topup in two ways: Custom amount: Specify a fixed amount to charge and the number of credits to add when the threshold is reached. Bundle pricing: Use an existing bundle price from your product catalog. Hyperline automatically calculates the correct amount based on the bundle pricing.

Example 💡

If you want to add 200 credits and your bundle is 50 credits for €400, Hyperline charges €1,600 for 4 bundles.

​
Setting up auto-topup

When creating or updating a credit balance for a customer, you can configure:
  • The balance threshold that triggers auto-topup
  • The number of credits to add when triggered
  • Either a custom amount to charge, or select a bundle price from your catalog
Auto-topup requires the customer to have a valid payment method on file. If the payment fails, Hyperline does not process the top-up and the balance remains unchanged.

​
Credit balances report

The Credit balances report gives you a month-by-month roll-forward of every prepaid credit balance, so finance teams can audit how credits were granted, consumed, and expired over time. You can view it on the Reports page or export it through the exports API with name set to credit_balances. Each row covers one customer’s balance for a single credit type and month. A customer can hold several balances in different units, and amounts are never combined across units. The report is dense: quiet months still appear, carrying the previous closing balance forward. A balance appears once it has had activity on or before the end of the selected period. Values are expressed in raw credit units (always positive), not in currency. Every row balances out: Opening + Granted + Purchased + Subscription − Consumed − Expired + Adjustments = Closing
Months are bucketed in the customer’s timezone, while the date-range filter bounds are interpreted in UTC.