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:

  • A customer_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 customer_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": {
    "customer_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 customer_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 a customer_id, as shown in the following example:

Event example
{
  "event": {
    "transaction_id": "__UNIQUE_ID__", // unique id of the event
    "customer_id": "__CUSTOMER_ID__", // customer_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.

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.