Skip to main content
By default, a usage-based product is invoiced in arrears — at the end of the billing period, once all usage for that period has been consumed. Hyperline also supports the opposite pattern: upfront metered products, where usage is invoiced at the start of each period and reconciled against real consumption on the next invoice. This is useful when:
  • Your customer has a minimum committed volume and you want to charge for it upfront each period.
  • You want cash to come in at the start of the period rather than the end.
  • Your customer’s usage is fairly predictable period-over-period.
Upfront billing is a property of a usage-based (dynamic) product on a subscription. You configure it by setting the product’s payment schedule to start of period when adding it to the subscription or plan.

​
How it’s billed

At the start of each period, real usage for that period hasn’t happened yet, so Hyperline has to bill on a projection. The projection is: 
billed units = max(committed units, usage billed for the previous period)
  • Committed units is the minimum volume you configure on the product (min_committed_count on the API). It acts as a floor, not a cap.
  • Previous period’s billed usage is what actually got consumed in the period that just closed.
Two consequences follow from this rule:
  • On the very first period there is no prior usage, so the customer is billed on the committed amount. If you didn’t set a commitment, the upfront charge for the first period is zero and the whole charge lands on the correction line the following period.
  • On subsequent periods the upfront charge floats up if the last period ran hot. If a customer consumed 500 units when they committed to 250, the next period’s upfront charge is priced on 500 — the commitment is only a floor.

​
The correction line item

Because you charged the customer upfront on a projection, real usage will drift from what was billed. To reconcile, every renewal invoice includes a correction line item for the period that just closed: 
correction = actual usage for that period (priced) − amount already invoiced upfront
  • If the customer used more than what was billed upfront, the correction is a debit (extra charge).
  • If the customer used less, the correction is a credit (refund).
A typical renewal invoice for an upfront metered product therefore contains two lines for that product:
  1. Upfront charge for the new period, sized on max(committed, last period's usage).
  2. Correction for the previous period, settling the difference between actual and projected usage.
Corrections are pre-populated on the next period’s draft invoice as soon as the current invoice is finalized, and are kept in sync as new usage events arrive — so both you and your customer can see the running true-up before the invoice is issued.

​
Worked example

Setup:
  • Metered product priced at €50 per unit, billed monthly, upfront.
  • Committed units: 250 per month.
January (first period)
  • No prior usage yet → billed on the committed 250 units.
  • Upfront charge: 250 × €50 = €12,500.
  • Actual January usage turns out to be 500 units.
February renewal invoice
  • Upfront charge for February: max(250, 500) × €50 = 500 × €50 = €25,000.
  • Correction for January: 500 × €50 − 250 × €50 = €12,500 debit (customer used more than was billed upfront).
  • Total on the February invoice for this product: €25,000 + €12,500 = €37,500.
March renewal invoice — assume February usage came in at 300 units
  • Upfront charge for March: max(250, 300) × €50 = 300 × €50 = €15,000.
  • Correction for February: 300 × €50 − 500 × €50 = −€10,000, applied as a €10,000 credit (customer used less than was billed upfront in February).
  • Net on the March invoice for this product: €15,000 − €10,000 = €5,000.
April renewal invoice — assume March usage came in at 200 units (below commitment)
  • Upfront charge for April: max(250, 200) × €50 = 250 × €50 = €12,500 — the commitment kicks in as the floor.
  • Correction for March: 200 × €50 − 300 × €50 = −€5,000 credit.
  • Net on the April invoice for this product: €12,500 − €5,000 = €7,500.

​
Interaction with other settings

​
Metering period

The projection and the correction always look at usage within the product’s own billing period (the period being billed upfront and the one being trued up). If you configure a different metering period (Committed period, Whole database, Custom), the same upfront + correction mechanic applies, but the “actual usage” figure used in the correction reflects that broader window rather than a single billing period.

​
Only bill the usage difference

The Only bill the difference with the last invoice option combines with upfront billing: the customer is charged upfront for the projected units, and the correction on the next invoice reflects only the incremental usage vs. what was previously billed, rather than the full period’s usage. Use this when the priced quantity is a running total (e.g. cumulative revenue against an annual threshold) rather than a per-period consumption count.

​
Min and max amounts

Minimum and maximum amounts on the product are applied to each invoiced amount independently — both the upfront line and the correction line are subject to the caps in force at the time they are computed.

​
When not to use upfront metering

Upfront metering is a poor fit if:
  • Usage is highly volatile and you don’t want large corrections swinging invoice totals up and down.
  • The customer has no meaningful commitment — you’ll end up billing zero upfront and everything on the correction, which is just arrears with extra steps.
  • You need revenue tied precisely to consumption events with no timing gap. In that case, use standard (in-arrears) metering.