Create a customer
You can create or update a customer both from the API or the user interface. The entire customer's information can be retrieved from the customer detailed view, available on the UI.
To create a customer, 2 mandatory information are required:
external_id(Required): usual good practice is to send the unique id from your backend;
- A customer
name(Required): name of the customer.
You cannot change the
external_id of a customer with an active subscription (active plan assigned to this customer).
In addition to this, you can add optional information to a customer. This additional information is useful for invoicing. Here is the list of optional fields that can be retrieved for a customer:
address_line1(Optional): first line of the billing address of your customer;
address_line2(Optional): second line of the billing address of your customer;
city(Optional): city of the customer's billing address;
country(Optional): country code of the customer's billing address;
legal_name(Optional): legal company name of the customer;
legal_number(Optional): legal company number of the customer;
logo_url(Optional): logo URL of the customer;
phone(Optional): phone number of the customer;
state(Optional): state of the customer's billing address;
url(Optional): custom URL of the customer (domain url);
vat_rate(Optional): custom VAT applied to the customer. (It will override the one defined at organization level);
zipcode(Optional): zipcode of the customer's billing address.
These additional fields can be added later on by updating a customer.
Example of customer's information
"address_line1": "5230 Penfield Ave",
"city": "Woodland Hills",
"name": "Gavin Belson",
"phone": "1-171-883-3711 x245",
Update a customer
You can update a customer anytime you need by using the same endpoint. To do so, you just need to pass in the payload the
external_id of the customer you want to update.
Delete a customer
You can delete a customer only if this customer does not have an active subscription (active plan assigned to this customer).
Assigning a plan to a customer
You can create a subscription by assigning a plan to a customer. By creating a subscription, all the charges (base charge and additional charges) are appended to this customer. By ingesting events, the usage will be charged following the prices belonging to the current subscription's plan.
From both the UI and the API, you can:
- Create a subscription by assigning a plan to a customer
- Change a subscription by assigning a new plan to a customer
- Terminate a subscription
Ingesting events for a customer
Before sending event to a customer as usage measurement, you must define billable metric(s) from the UI. The
code of the billable metric is passed as a parameter of the event. Each paying feature of your product is a distinct billable metric and has a proper event
By sending an event to a customer, you are assigning a usage-based consumption from your application.
In Lago, all ingested events must hold an
external_customer_id, as shown in the following example:
"transaction_id": "__UNIQUE_ID__", // unique id of the event
"external_customer_id": "__CUSTOMER_ID__", // id of your customer
"code": "__EVENT_CODE__", // code of the targeted billable metric
Events represents the data delivered to Lago application that are aggregated into billable metrics. At the end of each billable period, Lago automatically aggregates those events into a billable metric with priced units that have been consumed by a customer. By clicking the following link, you can know more about the aggregation types.
Displaying customer current usage
After assigning a plan to a customer and start ingesting usage-based events, it is often useful to know what is the current usage of this specific customer during the ongoing billable period. This current usage displays:
- The total amount of usage that will be billed in the next invoice;
- The breakdown per usage-based charges (number of units consumed and amount to be billed).
To access this feature, select a specific customer and access the
On top of this, you can fetch via the API the current usage of a specific customer using the following endpoint
Invoicing a customer
Lago automatically generates an invoice for all your customers at the end of each billing period.
Click on the following link to know more about invoicing with Lago.
The customer slug is a unique identifier for a customer that will be used to build an invoice number. This slug respect this format:
LAGis the first 3 letters of the customer's organization
1234is the last 4 characters of the customer's organization's id
sequential_idof the customer scoped on the organization