Usage-Based Billing Quick Start

This guide is intended to take you from no payment processing to a simple, but functional, usage-based billing system.

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.

Following this short guide will take you from zero to being up-and-running with a usage-based billing model in your application.

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 in the Salable dashboard.

You will need to create a product, the plans that you want the users to be able to subscribe to, and any entitlements your users should be able to access depending on their subscription.

As an example, if your application was an AI image generation tool, you may offer "Starter" and "Pro" plans, with "High-Resolution Exports", "Commercial Rights", and "Priority Processing" as your entitlements.

To charge for usage on your "Pro" plan, set up a Line Item with a Pricing Type of "Metered". Create a Meter (like image_generations) and set your per-unit price.

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

const response = await fetch('https://beta.salable.app/api/checkout', {
    method: 'POST',
    headers: {
        Authorization: 'Bearer YOUR_SECRET_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        planId: 'YOUR_PLAN_ID',
        owner: 'user_123',
        grantee: 'user_123',
        interval: 'YOUR_INTERVAL', // 'month' or 'year'
        intervalCount: 1,
        currency: 'YOUR_PLANS_CURRENCY', // USD, GBP, EUR, etc
        successUrl: 'https://your-app.com/success',
        cancelUrl: 'https://your-app.com/cancel'
    })
});
 
const { data } = await response.json();
// Redirect user to data.url

Once the customer completes checkout, Salable automatically creates a Usage Record to track their consumption.

3. Record usage in your application

As users consume your service, record their usage to the appropriate meter. Usage recording returns immediately and processes in the background.

async function recordUsage(owner, meterSlug, increment) {
    const response = await fetch('https://beta.salable.app/api/usage/record', {
        method: 'POST',
        headers: {
            Authorization: 'Bearer YOUR_SECRET_KEY',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({ owner, meterSlug, increment })
    });
 
    if (!response.ok) throw new Error(`Failed to record usage: ${response.status}`);
}
 
// Record usage after processing a request
await recordUsage('user_123', 'image_generations', 1);

4. Add entitlement checks to your application

In your application, you will only want to allow the grantee to perform certain actions if they have an active subscription.

We can check for a grantee's active entitlements as follows:

const { data } = await fetch('https://beta.salable.app/api/entitlements/check?granteeId=YOUR_GRANTEE_ID', {
    headers: {
        Authorization: 'Bearer YOUR_SECRET_KEY'
    }
});
 
const granteeHasEntitlement = data.entitlements.find(e => e.value === 'YOUR_ENTITLEMENT_NAME');
 
if (granteeHasEntitlement) {
    // Allow the user to perform the action in your system.
}

5. Display usage to customers

You can retrieve current usage data to display in your application's dashboard.

const response = await fetch('https://beta.salable.app/api/usage-records?owner=user_123&meterSlug=image_generations&status=current', {
    headers: {
        Authorization: 'Bearer YOUR_SECRET_KEY'
    }
});
 
const { data } = await response.json();
const currentUsage = data[0]?.count || 0;

6. Next steps

Now that you have usage-based payment processing and entitlement checking set up in your application, there are some further things you should set up to enable full subscription handling: