Skip to main content

Customers

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.

Mandatory fields​

To create a customer, 2 mandatory information are required:

  • An external_id (Required): usual good practice is to send the unique id from your backend;
  • A customer name (Required): name of the customer.
caution

You cannot change the external_id of a customer with an active subscription (active plan assigned to this customer).

Additional fields​

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:

  • An address_line1 (Optional): first line of the billing address of your customer;
  • An address_line2(Optional): second line of the billing address of your customer;
  • A city (Optional): city of the customer's billing address;
  • A country (Optional): country code of the customer's billing address;
  • An email (Optional): main email of the customer;
  • A legal_name (Optional): legal company name of the customer;
  • A legal_number (Optional): legal company number of the customer;
  • A logo_url (Optional): logo URL of the customer;
  • A phone (Optional): phone number of the customer;
  • A state (Optional): state of the customer's billing address;
  • An url (Optional): custom URL of the customer (domain url);
  • A vat_rate (Optional): custom VAT applied to the customer. (It will override the one defined at organization level);
  • A zipcode (Optional): zipcode of the customer's billing address.
info

These additional fields can be added later on by updating a customer.

Example of customer's information​

Customer's information example
{
  "customer": {
    "external_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "address_line1": "5230 Penfield Ave",
    "address_line2": null,
    "city": "Woodland Hills",
    "country": "US",
    "email": "dinesh@piedpiper.test",
    "legal_name": "Coleman-Blair",
    "legal_number": "49-008-2965",
    "logo_url": "http://hooli.com/logo.png",
    "name": "Gavin Belson",
    "phone": "1-171-883-3711 x245",
    "state": "CA",
    "url": "http://hooli.com",
    "vat_rate": 12.5,
    "zipcode": "91364"
  }
}

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 code.

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:

Event example
{
  "event": {
    "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
    "timestamp": 1650893379,
    "properties": {
      "custom_field": 12
    }
  }
}

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 Usage tab.

On top of this, you can fetch via the API the current usage of a specific customer using the following endpoint GET /api/v1/customers/:external_customer_id/current_usage.

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.

Customer Slug​

The customer slug is a unique identifier for a customer that will be used to build an invoice number. This slug respect this format:

  • LAG-1234-001
  • LAG is the first 3 letters of the customer's organization
  • 1234 is the last 4 characters of the customer's organization's id
  • 001 is the sequential_id of the customer scoped on the organization