Usage Billing

Usage billing enables you to bill your customers based on the volume of use in the billing period. For example, if you want to implement a credits-based pricing system, you can do so with usage billing.

Usage is tracked in the usage table and is reported to Stripe daily (customisable).

Usage tracking is supported on free accounts but won't be reported to Stripe or billed.

Enabling Usage Billing in Stripe

Usage billing uses the volume pricing in Stripe.

You must create a new price and set the pricing model to volume pricing. Then, set the price per unit to whatever you want to charge per unit.

Stripe doesn't support switching from a non-volume pricing model to a volume pricing model on the same subscription. Ensure all of your prices are volume pricing to support changing plans.

Incrementing Usage

To track usage, use the usage.increment method. You can increment by a specific amount passing quantity or omit it to increment by one.

const usage = require('./model/usage');

// increment by 10 
usage.increment({ account: 'account_id', quantity: 10 });

// increment by 1
usage.increment({ account: 'account_id' });

You should call this function in any relevant API endpoint where you want to log use.

Reporting Usage to Stripe

Usage is reported to Stripe once per day using the usage background job. You can customise how often this job runs in config.worker_schedule.usage

Shorter billing times are recommended to ensure Stripe always has the latest usage data for the current billing period and can charge your customers the correct amount.

When usage is reported, the report column of the usage table for the corresponding report will be marked as true. The end_period will also be populated, and the report is closed.

The worker will then open a new report, and any incrementation will be applied to the new open report.

Getting Usage

You can use the usage.get method to fetch usage. The client application will fetch and display usage for the current billing period.

const usageData = await usage.get({ 

  account: 'account_id', 
  period_start: '2023-10-10', 
  period_end: '2023-11-11'

});

Prorations

On usage (and seat) tiered plans, invoice_now and prorate are enabled. Users will be charged at the end of the billing cycle for uncharged tiered usage.