Record Usage

Usage-based pricing charges your customers only for what they consume, whether that's API calls, image generations, or the AI credits an agent spends completing a task; that consumption must be accurately recorded. Recording usage is a single API call that increments consumption on the metered Line Item for the current cycle, so there are no counters to maintain and nothing to reconcile at invoice time.

Prerequisites

Your customer needs an active Subscription with a metered Line Item before you can record usage for them. Create one by sending them through a checkout link, or create a Salable Only Subscription if you are not billing that customer through Stripe.

Increment Consumption

The owner scopes usage to a single tenant: every user under that owner contributes to the same meter. Because you record against the owner rather than the individual user, usage is attributed correctly even when a user belongs to more than one tenant. If your application is single-user, use the user ID as the owner.

When recording usage, consider the volume that is processed. At low volume, record each unit as it's consumed. At high volume, accumulate consumption in your own process and send one larger increment per batch to avoid rate limits.

Parameter	Description
`owner`	The Owner is the tenant the usage belongs to, like a team or organisation ID. Cannot be an email address.
`meterSlug`	The Meter to increment, set on the Line Item when it was created. This must match a metered Line Item on the Subscription.
`increment`	A positive integer to add to the meter's usage for the current billing period. This call only adds usage; there is no decrement.

import { Salable } from '@salable/sdk';
const salable = new Salable(process.env.SALABLE_SECRET_KEY);
 
await salable.api.usage.record.post(
    {
        owner: 'team_acme',
        meterSlug: 'image_generations',
        increment: 5
    },
    {
        headers: {
            'Idempotency-Key': '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'
        }
    }
);

Important To prevent a customer from being overcharged from a retried request, send an Idempotency-Key header. Salable stores the key for 24 hours and replays the original response whenever you resend it with the same body and request parameters.

The endpoint returns 204 No Content. The increment is processed asynchronously, so reading the current usage immediately afterward may not yet reflect the change.

Metered Usage How meters are configured on a Line Item and billed at the end of a period.
Meter Slug The reference definition of a meter slug in the Salable model.

Prerequisites

Increment Consumption

Related