Usage-based billing

From events to invoice

Usage-based (metered) billing rates real consumption at period close. The moving parts:

A billable metric — a named aggregation (count, sum, max, unique) over raw usage events. Its code doubles as the event dimension.
A usage charge on a plan that prices that metric (per-unit or tiered).
Usage events you record as consumption happens, each optionally carrying a transaction_id for idempotency.
A rating read — windowed usage buckets, or the live current-period amount.

Rate units differ from flat prices. A per-unit or tier unit_amount is a decimal string in major currency units (e.g. "0.0035" = $0.0035 per unit). Flat plan prices and package amounts stay as integer minor units.

Construct a client

import { Recurso } from 'recurso';

const recurso = new Recurso('sk_live_your_api_key', {
  baseUrl: 'https://api.recurso.dev',
});

ctx := context.Background()
client := recurso.NewClient("sk_live_your_api_key")

from recurso import AuthenticatedClient

client = AuthenticatedClient(
    base_url="https://api.recurso.dev",
    token="sk_live_your_api_key",
)

Create a billable metric

The code is the dimension your events will report against and is immutable after creation. field_name is required only for the unique aggregation (the event property whose distinct values are counted) and forbidden otherwise.

const metric = await recurso.billableMetrics.create({
  name: 'API Calls',
  code: 'api_calls',
  aggregation_type: 'sum', // count | sum | max | unique
});

metric, err := client.BillableMetrics.Create(ctx, &recurso.BillableMetricParams{
	Name:            "API Calls",
	Code:            "api_calls",
	AggregationType: "sum", // count | sum | max | unique
})
if err != nil {
	log.Fatal(err)
}

from recurso.api.metering import create_billable_metric
from recurso.models import BillableMetricInput, BillableMetricInputAggregationType

metric = create_billable_metric.sync(
    client=client,
    body=BillableMetricInput(
        name="API Calls",
        code="api_calls",
        aggregation_type=BillableMetricInputAggregationType.SUM,
    ),
)

Set usage charges on a plan

Charges use PUT replace semantics: the list you send becomes the plan’s complete usage-charge set (charges absent from it are removed). Flat plan prices are untouched — a plan with both is hybrid (flat fee in advance, usage in arrears on the same renewal invoice). Reference the metric by its id.A per-unit charge prices every unit at one rate:

await recurso.plans.setCharges(plan.id, [
  {
    metric_id: metric.id,
    charge_model: 'per_unit',
    amounts: {
      USD: { unit_amount: '0.0035' }, // $0.0035 per unit (major units)
    },
  },
]);

_, err = client.Plans.SetCharges(ctx, plan.ID, []recurso.ChargeParams{
	{
		MetricID:    metric.ID,
		ChargeModel: "per_unit",
		Amounts: map[string]recurso.ChargeAmounts{
			"USD": {UnitAmount: "0.0035"}, // $0.0035 per unit (major units)
		},
	},
})
if err != nil {
	log.Fatal(err)
}

from recurso.api.metering import set_plan_charges
from recurso.models import (
    ChargeAmounts,
    ChargeInput,
    ChargeInputAmounts,
    ChargeInputChargeModel,
)

amounts = ChargeInputAmounts()
amounts["USD"] = ChargeAmounts(unit_amount="0.0035")  # $0.0035 per unit

set_plan_charges.sync(
    plan.id,
    client=client,
    body=[
        ChargeInput(
            metric_id=metric.id,
            charge_model=ChargeInputChargeModel.PER_UNIT,
            amounts=amounts,
        )
    ],
)

A tiered (graduated) charge prices bands separately; the final tier is unbounded (up_to: null):

await recurso.plans.setCharges(plan.id, [
  {
    metric_id: metric.id,
    charge_model: 'graduated',
    amounts: {
      USD: {
        tiers: [
          { up_to: 100000, unit_amount: '0.0035' }, // first 100k units
          { up_to: null, unit_amount: '0.0020' }, // everything above
        ],
      },
    },
  },
]);

first := int64(100000)
_, err = client.Plans.SetCharges(ctx, plan.ID, []recurso.ChargeParams{
	{
		MetricID:    metric.ID,
		ChargeModel: "graduated",
		Amounts: map[string]recurso.ChargeAmounts{
			"USD": {Tiers: []recurso.ChargeTier{
				{UpTo: &first, UnitAmount: "0.0035"}, // first 100k units
				{UpTo: nil, UnitAmount: "0.0020"},    // everything above
			}},
		},
	},
})
if err != nil {
	log.Fatal(err)
}

from recurso.models import ChargeAmounts, ChargeInput, ChargeInputAmounts, ChargeInputChargeModel, ChargeTier

amounts = ChargeInputAmounts()
amounts["USD"] = ChargeAmounts(
    tiers=[
        ChargeTier(up_to=100000, unit_amount="0.0035"),  # first 100k units
        ChargeTier(up_to=None, unit_amount="0.0020"),    # everything above
    ]
)

set_plan_charges.sync(
    plan.id,
    client=client,
    body=[
        ChargeInput(
            metric_id=metric.id,
            charge_model=ChargeInputChargeModel.GRADUATED,
            amounts=amounts,
        )
    ],
)

The ChargeAmounts model was missing from an earlier generated build of the Python client; it’s now present, so set_plan_charges works in all three SDKs. Install a Python build that includes it (from a current checkout of the repo).

Record usage events

Record consumption as it happens against the subscription and its dimension. Pass a transaction_id to make ingestion idempotent: a retried event with the same (subscription, transaction_id) collapses to the original instead of double-counting.

await recurso.usage.record({
  subscription_id: subscription.id,
  customer_id: customer.id,
  dimension: 'api_calls', // the metric's code
  quantity: 1500,
  transaction_id: 'req-2026-07-20-0001', // idempotency key
});

_, err = client.Usage.Record(ctx, &recurso.UsageRecordParams{
	SubscriptionID: subscription.ID,
	CustomerID:     customer.ID,
	Dimension:      "api_calls", // the metric's code
	Quantity:       1500,
	TransactionID:  "req-2026-07-20-0001", // idempotency key
})
if err != nil {
	log.Fatal(err)
}

from recurso.api.usage import record_usage_event
from recurso.models import RecordUsageEventBody

record_usage_event.sync(
    client=client,
    body=RecordUsageEventBody(
        subscription_id=subscription.id,
        customer_id=customer.id,
        dimension="api_calls",  # the metric's code
        quantity=1500,
        transaction_id="req-2026-07-20-0001",  # idempotency key
    ),
)

Query windowed usage

Aggregate events into time buckets over a window. At least one of subscription_id or customer_id is required; the window defaults to the last 30 days at day granularity.

const { data: buckets } = await recurso.usage.query({
  subscription_id: subscription.id,
  from: '2026-07-01T00:00:00Z',
  to: '2026-07-31T23:59:59Z',
  granularity: 'day', // day | month
});

usage, err := client.Usage.Query(ctx, &recurso.UsageQueryParams{
	SubscriptionID: subscription.ID,
	From:           "2026-07-01T00:00:00Z",
	To:             "2026-07-31T23:59:59Z",
	Granularity:    "day", // day | month
})
if err != nil {
	log.Fatal(err)
}
for _, b := range usage.Data {
	log.Printf("%s %s=%d", b.Period, b.Dimension, b.Quantity)
}

import datetime

from recurso.api.usage import query_usage
from recurso.models import QueryUsageGranularity

usage = query_usage.sync(
    client=client,
    subscription_id=subscription.id,
    from_=datetime.datetime(2026, 7, 1, tzinfo=datetime.timezone.utc),
    to=datetime.datetime(2026, 7, 31, 23, 59, 59, tzinfo=datetime.timezone.utc),
    granularity=QueryUsageGranularity.DAY,
)

Get the current usage amount

Rating preview: what the current period’s metered usage would bill to if invoiced now, per charge, with a total_amount in minor units.

const amount = await recurso.subscriptions.usageAmount(subscription.id);
console.log(amount.total_amount, amount.currency); // total in minor units
for (const charge of amount.charges) {
  console.log(charge.metric_code, charge.quantity, charge.amount);
}

amount, err := client.Subscriptions.UsageAmount(ctx, subscription.ID)
if err != nil {
	log.Fatal(err)
}
log.Printf("total=%d %s", amount.TotalAmount, amount.Currency) // minor units
for _, c := range amount.Charges {
	log.Printf("%s qty=%d amount=%d", c.MetricCode, c.Quantity, c.Amount)
}

from recurso.api.metering import get_subscription_usage_amount

amount = get_subscription_usage_amount.sync(
    id=subscription.id,
    client=client,
)

recurso.subscriptions.usage(id) (Node) / client.Subscriptions.Usage(ctx, id) (Go) / get_subscription_usage.sync(...) (Python recurso.api.usage) is the sibling read: raw current-period quantities per dimension plus lifetime totals and entitlement limits, without rating them to money.

Get Started

By Language

Workflows

From events to invoice

​From events to invoice

​Related

From events to invoice

Related