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):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.
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.
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.
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 of3 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.
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 you report usage (via events or viaPOST /v1/customers/{id}/credits/{productId}/usage), Hyperline deducts it 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.You may want a “free” allowance (e.g. a plan-included monthly allowance) to be consumed before paid top-ups. In that case, 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, Hyperline credits the allowance 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
Hyperline updates credit balances asynchronously when you report usage 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 trial usage allowances 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 automatically expire when the billing period ends, and Hyperline adds new credits at the start of the next period.When credits expire, Hyperline automatically creates an expiration transaction in the credit ledger and reduces the customer’s balance 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:- Create an invoice for the top-up amount
- Charge the customer’s card immediately
- Add the credits to their balance when the payment succeeds
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.
Set 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
Portal top-ups
Portal top-ups let a customer buy credits by themselves from the customer portal. You enable portal top-ups for each customer and each credit product, and you set the price that this customer pays.Prerequisites
- In Settings > Hosted pages > Portal, enable Allow customers to buy credits. When this option is off, no customer can buy credits from the portal.
- The customer has a currency. Every portal price uses the customer’s currency.
- The customer has a credit balance for the credit product. The balance can start at 0. Without a balance, the portal has nothing to show or top up.
Enable portal top-ups for a customer
1
Open the credit balance form
On the customer’s details page, go to the Credits tab. Click Add credit balance, or edit an existing credit balance.
2
Turn on Portal self-serve
In the Portal self-serve section, turn on Allow credit purchases from the customer portal.
3
Select the portal price
In Portal price, select the price that the customer pays. The list shows the catalog prices of the credit product that apply to this customer: the prices of the customer’s price book, in the customer’s currency.Hyperline suggests the catalog price billed once and shows it first. You can select any other price in the list.
4
Save
Click Save. When you add a new credit balance, Hyperline creates the balance first, then saves the portal settings.
Give a customer a custom price
If no catalog price fits, select Custom price in Portal price and set a price for this customer only. This works like a custom price on a product of a subscription: the price applies to this customer, and your catalog does not change. A custom price uses the customer’s currency. If the customer has no currency, set one before you add a custom price. When you save a new custom price, it replaces the previous custom price of this customer.If no catalog price matches the customer, the list is empty. Add a custom price to sell credits on the portal.
Supported prices
A portal price must meet these conditions:- Its type is bundle, volume or bulk. A credit product can only have these price types.
- It is live: it is not archived or deleted.
- It uses the customer’s currency.
Buy credits from the portal
On the portal, the customer clicks Buy credits on the credit balance. The Top up credit balance window opens:- With a bundle price, the customer selects a credit pack.
- With a volume or bulk price, the customer enters the Number of credits. The portal shows the price for this quantity.
- The customer selects the card to charge in Payment method. The portal lists the active cards of the customer and preselects the default card.
- Before confirmation, the portal shows the amount to charge, taxes included.
The customer needs an active card to buy credits. Without one, the portal blocks the purchase.
Buy credits with the API
The purchase credits endpoint follows the same rules as the portal:- The customer’s payment method must be a card. With another payment method, the request fails with the reason
payment_method_not_supportedand Hyperline creates no invoice. - Hyperline charges the card immediately, even if the customer has a payment initiation delay.
- Hyperline adds the credits only when the payment succeeds. If the card is declined, the request fails and the balance does not change.
Example 💡
Your credit product has two catalog prices in EUR: a bundle price of 1,000 credits for €100, billed once, and a volume price billed monthly. For your customer Acme, Hyperline suggests the bundle price. You keep it and save. On the portal, Acme selects the 1,000 credits pack, selects a card, sees the amount with taxes included, and confirms. Hyperline adds the 1,000 credits to the balance at once.
Manage portal top-ups with the API, MCP and CLI
Use these endpoints to read and change the portal top-up settings:
The
PUT request body has these fields:
Send
price_configuration_id or custom_price_configuration, not both. If portal top-ups are already enabled and you send neither, the current price stays. To disable portal top-ups, send enabled: false without a price.
The response contains customer_id, product_id, enabled, currency, price_configuration (the price the customer pays, or null) and is_custom_price.
If the customer has no credit balance for the product, the request to enable portal top-ups fails with the reason credit_balance_required. Create the credit balance first, even with a balance of 0.
The bulk endpoint takes an items array. Each item contains a customer_id, a product_id and the settings of the PUT request body. Hyperline applies all items in one transaction:
- If the customer of an item has no credit balance for the product, Hyperline skips the item and lists it in the
failedarray. - If any other error occurs, Hyperline applies no item.
data, the settings of the applied items, and failed. Each entry of failed has these fields:
To apply a failed item, create the customer’s credit balance, then send the item again.
The same operations are available in the Hyperline MCP server and the Hyperline CLI:
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 withname 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.