Per-Seat Billing Quick Start

Per-seat billing charges customers based on how many users have access to your product, but Stripe alone has no concept of who those users are. Salable handles the entire Stripe webhook lifecycle for you, team onboarding, seat management and keeping entitlements in sync as users join or leave.

Introduction

Per-seat billing means charging based on the number of grantees. £10 per user per month, £99 per seat per year, and £5 per seat per week 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 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 a project management tool, you may offer "Team" and "Enterprise" plans, with advanced_reporting, custom_fields, and api_access as your entitlements.

To charge for seats on your "Team" plan, set up a Line Item with a Pricing Type of "Per Seat".

To onboard an entire team through a checkout, pass a Group ID as the grantee value. If quantity is not provided, the quantity is set from the number of users in the group. Every user gets the plan's entitlements as soon as the subscription is active. If you don't pass a group, Salable creates one automatically when the subscription is created. Useful when a single user is buying for themselves who may add teammates later.

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: 'test-user-123',
    interval: 'month',
    intervalCount: 1,
    currency: 'USD',
    successUrl: 'https://your-app.com/success',
    cancelUrl: 'https://your-app.com/cancel'
});
 
// Redirect user to data.url

Creating a group upfront (optional)

If you need to create a group with specific team members before checkout, you can do so:

import { Salable } from '@salable/sdk';
const salable = new Salable('secret-api-key');
 
const { data: group } = await salable.api.groups.post({
    owner: 'company_acme',
    name: 'Development Team',
    grantees: [
        { granteeId: 'user_alice', name: 'Alice Smith' },
        { granteeId: 'user_bob', name: 'Bob Johnson' }
    ]
});
 
const { data } = await salable.api.checkout.post({
    planId: 'plan_01KJWF3VM5HNQ3YRS27K06J64T',
    owner: 'company_acme',
    grantee: group.id,
    interval: 'month',
    intervalCount: 1,
    currency: 'USD',
    successUrl: 'https://your-app.com/success',
    cancelUrl: 'https://your-app.com/cancel'
});

3. Add entitlement checks to your application

In your application, you'll want to check if each grantee has access through their group membership.

import { Salable } from '@salable/sdk';
const salable = new Salable('secret-api-key');
 
const { data } = await salable.api.entitlements.check.get({
    queryParameters: {
        granteeId: 'user_alice'
    }
});
 
const granteeHasEntitlement = data.entitlements.find(e => e.value === 'ai_assistant');
 
if (granteeHasEntitlement) {
    // Allow the user to perform the action in your system.
}

Setting up Entitlements allows you to easily create tailored plans for your customers requirements. Copy any existing Plan, adjust its Entitlements and cost based on the agreed terms with the customer, and they immediately get the exact feature set you agreed without any code change. Now everything flows through Entitlements, sales can be instant.

4. Managing team members

As your customers' teams grow, you can add or remove grantees from the group.

import { Salable } from '@salable/sdk';
const salable = new Salable('secret-api-key');
 
// Update seat quantity
await salable.api.subscriptionPlanLineItems.byId(subscriptionPlanLineItemId).put({
    quantity: 3,
    proration: 'always_invoice' // only required for Stripe subscriptions
});
 
// Add a new team member
await salable.api.groups.byId(group.id).grantees.post([
    {
        type: 'add',
        granteeId: 'user_charlie',
        name: 'Charlie Brown'
    }
]);

5. Next steps

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