---
title: "6 steps to build a usage-based billing system"
url: https://getlago.com/blog/6-steps-to-build-a-usage-based-billing-system
description: "In this article, we explain how to build a usage-based billing system in just 6 steps using Lago."
authors: ["Anh-Tho Chuong"]
tags: ["Engineering"]
published: 2022-09-08
updated: 2026-09-26
reading_time_minutes: 5
---

# 6 steps to build a usage-based billing system

Lago is an **open-source billing API** that helps engineers implement their billing systems faster. We do think the future of pricing is hybrid, which includes subscription fees and usage-based charges. Over the past few years, engineers have struggled to implement exotic billing systems but this is over!

Lago also provides a cloud-hosted application for those who don’t want to run it on their own environment.

We are going to build an entire hybrid billing system, including plans and usage-based features. Let’s try to replicate [Segment](https://segment.com/)’s pricing for instance!‍

#### Prerequisites

You can find the main Lago repository [on GitHub](https://github.com/getlago/lago).

Before we get started, you need to:

1. Install [Docker](https://docs.docker.com/get-docker/) on your machine;
2. Make sure [Docker Compose](https://docs.docker.com/compose/install/) is installed and available (it should be the case if you’ve chosen to install Docker via Docker Desktop);
3. Make sure [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) is installed on your machine; and
4. A cup of tea (or coffee)! ☕️ 🫖

This demo is made through basic CURL API calls, but Lago also provides API clients in order to make the implementation process easier.

### 1. Setting up your Lago billing engine

Start running Lago on your own environment. You will have access to Lago API and Lago UI (frontend admin panel to perform no-code tasks).

![Command to run Lago](https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/6357e462bf52554d1688dd63_6319ca682c17b1f0591b93c2_get-code.png)

‍

You can now open your browser and go to [http://localhost](http://localhost/) to connect to the application. Lago's API is exposed at [http://localhost:3000](http://localhost:3000/).

If needed, you can override your environment variables ([learn more](https://getlago.com/docs/guide/lago-self-hosted/docker#environment-variables)).

‍

### 2. Defining your billable metrics

The usage-based feature billed by Segment is the number of **monthly tracked users (MTUs)**, which is related to the total number of unique users tracked monthly.

Lago’s billable metrics allow you to track and automatically aggregate usage to determine the number of **units to be charged** at the end of a billing period.

Here we’re going to define MTUs as a billable metric:

![Creation of a billable metric](https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/6357e462bf525548b288dd67_6319ca87c09cf51b540d1894_metric.png)

‍

For this billable metric, the aggregation type is **unique\_count\_agg**, which is used to count the number of unique **user\_id** values recorded during the billing period.

‍

### 3. Creating your first plan

Now that we have our billable metric, we can create our first plan. The plan defines the billing period and all fees (i.e. subscription and usage-based charges).

Let’s take the example of **Segment’s Team plan**. The base subscription costs $120 per month month, including 10,000 free MTUs. If you track more users, you will be charged for the overage, according to Segment’s graduated pricing model.

![Creation of a plan](https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/6357e462bf5255a4e688dd6d_6319caa22c17b1d9241b9857_plan.png)

‍

Let’s take a closer look at the request above.

##### Basic plan model

The request creates a basic plan at $120/month that is paid in advance (beginning of period), with no free trial. If can customise it using the following fields:

• **interval**: can also be set to **yearly** or **weekly**;
• **amount\_currency**: all currencies are available;
• **trial\_period**: set a number of trial days; and
• **pay\_in\_advance**: if set to **false**, the subscription fee will be paid in arrears (end of period).‍

##### Usage-based charges

In this example, we selected a **graduated charge model** for our usage-based feature (i.e. MTUs). Here’s what we can see in the user interface.

![Graduated charge model](https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/6357e462bf52558a0288dd6e_6319c60694898cea6a3c5b69_charge.png)

You can create as many charges as you want and there are many charge models available (e.g. volume pricing, standard pricing, percentage pricing, package pricing).

**See it in the docs:**Read how to create billable metrics to start building. [**create billable metrics**](https://getlago.com/docs/guide/billable-metrics/create-billable-metrics?utm_source=blog&utm_medium=cta&utm_campaign=6-steps-to-build-a-usage-based-billing-system).

### 4. Creating your first customer

Congratulations, your pricing is ready! You can now create a customer, assign them a plan and start monitoring usage.

![Creation of a customer](https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/6357e462bf525514bf88dd65_6319cac01847b7f3b2a2d66c_create-customer.png)

‍

This request allows you to create a customer and also to define the default payment provider (i.e. the payment service provider that will be used to collect payments for this customer). We also set a tax rate of 12.5% for this customer.

![Customer record](https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/6357e462bf525566bf88dd6b_6319c64b8e23fbfaa1a0950b_customer.png)

‍

### 5. Assigning a plan to a customer

To start billing a customer, you need to assign them a plan. This action will create a **subscription**.

![Creation of a subscription](https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/6357e462bf5255f1e788dd62_6319cad4c83e80bbd6b95207_assign-plan.png)

![Subscription associated with a customer](https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/6357e462bf525576dc88dd66_6319c72e431135e7168a30b2_subscription.png)

‍

When assigning a subscription, you can:

• Define your own **external\_id**;

• Choose between **anniversary** or **calendar** for the billing time - a subscription based on calendar dates is billed on the first day of each week/month/year, while a subscription based on the anniversary date is billed on the day it was created (e.g. every 4 of the month); and

• Enter a subscription name that will be displayed on the invoice and will allow you to differentiate subscriptions that share the same plan (e.g. Project 1 on the Free plan and Project 2 also on the Free plan).

As the base amount of the Team plan has to be paid in advance, Lago automatically generates a first invoice. The usage-based charge related to MTUs will be billed at the end of the period.

![Invoice generated by Lago](https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/6357e462bf5255170688dd64_6319c74e2b4bd83cee90285f_invoice.png)

‍

This invoice can be customized with information about your organization, your logo and a custom footer. For compliance purposes, invoices have an incremental **sequential\_id** and incremental **invoice\_number** as well.

### 6. Ingesting usage-based events

Lago has an event-based architecture. When a subscription is associated with a customer, you can start pushing events related to your billable metrics. By using a unique **transaction\_id**, we make sure that an event is not ingested twice. It’s what we call an idempotency key.

Below are three events ingested by Lago:

![Creation of the first event](https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/6357e462bf5255164e88dd6a_6319caf221f82b4ae6375d97_event-1.png)

![Creation of the second event](https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/6357e462bf525583b588dd69_6319cb06c09cf54b7e0d1c11_event-2.png)

![Creation of the third event](https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/6357e462bf525587b988dd6c_6319cb142149360d06199eb2_event-3.png)

![Debugger view](https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/6357e462bf5255234888dd68_6319c7cf214936db2f1977e2_debugger.png)

‍

We have three different events, however, two of them are sending the same **user\_id**. As we use a unique count aggregation type for the billable metric MTUs, **the number of units to be charged is 2**.

Lago then automatically calculates the fees depending on the charge model of the plan. With Segment’s pricing, the first 10,000 MTUs are free of charge. Therefore, these two units cost $0.

![Current usage information](https://uploads-ssl.webflow.com/63569f390f3a7ad4c76d2bd6/6357e462bf5255762a88dd6f_6319c7e49604eeaf5602f981_current-usage.png)

‍

This is how Lago can help you implement a usage-based [billing system](https://getlago.com/blog/understanding-billing-system-software) in just a few hours (not months). It’s easy to build but also easy to maintain. Here are other [examples of usage-based billing](https://getlago.com/blog/usage-based-pricing-examples).

In addition to this, Lago manages upgrades/downgrades, taxes, discounts, prepaid credits and prorated fees — including [handling usage adjustments in billing](https://getlago.com/blog/grace-period-to-adjust-invoice-usage) — and handles the [scalability considerations when building billing](https://getlago.com/blog/billing-system-scalability-horizontal-scaling-sharding-multi-tenancy) at high volume. [Ready to give it a try?](https://getlago.com/get-started)