Usage-Based Billing Quick Start

Usage-based billing ties cost to consumption, charging customers only for what they actually use. Salable handles the Stripe webhook lifecycle for you, scopes usage to the right owner across multiple organisations, and prevents accidental duplicate subscriptions to the same meter. Salable also lets you combine metered and per-seat line items on a single subscription, meaning every member in the team contributes to the same meter.

Introduction

Usage-based billing means charging based on consumption. £0.01 per API call, £0.10 per GB of storage, and £0.05 per message sent are all examples of this billing model.

1. Create and configure your product

Before you can start implementing Salable into your codebase, you need to sign up for an account and create a product.

After creating a product, you'll need to create the plans you want users to be able to subscribe to. Make sure to associate any entitlements they should receive upon subscribing.

As an example, if your application was an AI image generation tool, you may offer a "Pro" plan, with the entitlements high_resolution_exports, image_generations, and priority_processing.

To charge for usage on this plan, configure a Line Item with a Pricing Type of "Metered", connect a Meter (e.g. image_generations) and configure your per-unit price.

2. Generate a checkout link

To accept payment from a user, you will need to generate a checkout link.

import { Salable } from '@salable/sdk';
const salable = new Salable('secret-api-key');
 
const { data } = await salable.api.checkout.post({
    planId: 'plan_01KJWF3VM5HNQ3YRS27K06J64T',
    owner: 'company_acme',
    grantee: 'user_alice',
    interval: 'month',
    intervalCount: 1,
    currency: 'USD'
});
 
// Redirect user to data.url

const response = await fetch('https://salable.app/api/checkout', {
    method: 'POST',
    headers: {
        Authorization: 'Bearer YOUR_SECRET_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        planId: 'plan_01KJWF3VM5HNQ3YRS27K06J64T',
        owner: 'company_acme',
        grantee: 'user_alice',
        interval: 'month',
        intervalCount: 1,
        currency: 'USD'
    })
});
 
const { data } = await response.json();
// Redirect user to data.url

Once the customer completes checkout and is subscribed, Salable automatically starts tracking their consumption of the associated meter.

3. Record usage in your application

As users consume your service, record their usage against the appropriate meter.

Note Usage recording is processed asynchronously so newly recorded usage may not reflect immediately.

import { Salable } from '@salable/sdk';
const salable = new Salable('your-secret-key');
 
await salable.api.usage.record.post({
    owner: 'company_acme',
    meterSlug: 'image_generations',
    increment: 1
});

await fetch('https://salable.app/api/usage/record', {
    method: 'POST',
    headers: {
        Authorization: 'Bearer YOUR_SECRET_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        owner: 'company_acme',
        meterSlug: 'image_generations',
        increment: 1
    })
});

Note Passing owner scopes consumption to a specific tenant. All users belonging to that owner contribute to the same meter, this is useful for plans that combine metered with per-seat line items. It also handles users who belong to multiple tenants: pass the right owner, and Salable applies the usage to the right meter.