> ## Documentation Index
> Fetch the complete documentation index at: https://lago-ftr-wallet-improvements.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Ingesting usage

> This guide explains how Lago ingests usage-based events coming from your application.

## Define a billable metric[](#define-a-billable-metric "Direct link to heading")

**Usage events are designed to target very specific
[billable metrics](/guide/billable-metrics/create-billable-metrics) created from the UI**. If you don't understand the
concept of billable metrics, we recommend you to read it first.

First things first, you need to define a billable metric from the UI to send
usage measurement events:

1. In the Lago app, go to the **"Billable metrics"** section;
2. Click **"Add a billable metric"**;
3. Add metric information, including:
   * `name`
   * `code` (used to send events via API)
   * `description` (optional)
4. Define whether or not this metric is `recurring`; and
5. Choose an aggregation type to define how usage should be calculated.

Billable metrics represent the features of your product. Events should automatically be sent to Lago by your application
based on your customers' actions.

## Send usage measurements to Lago[](#send-usage-measurements-to-lago "Direct link to heading")

To send usage events to Lago, you need to use the **Lago API**. A measurement
event is JSON with the following fields:

```json
{
  "transaction_id": "__TRANSACTION_ID__" // (Required) Unique identifier of the event
  "external_subscription_id": "__SUBSCRIPTION_ID__" // (Required) Unique identifier of your customer's subscription
  "code": "__EVENT_CODE__", // (Required) The billable metric's code
  "timestamp": 1650893379, // (Required) UNIX timestamp of the event
  "properties": {
    "custom_field": 12, // (Optional) Custom variables defined as properties
    "operation_type": "add" or "remove" // (Optional) Required only for recurring metric based on the unique count aggregation
  }
}
```

<AccordionGroup>
  <Accordion title="1. The transaction_id">
    The `transaction_id` is very useful to ensure the uniqueness of the events
    received. It is mandatory to define on your own a unique `transaction_id` for
    each event you send to Lago.

    This identifier is used to deduplicate events ingested, making sure we don't
    ingest twice the same event (otherwise, this could create billing errors for
    your customers).

    * If a `transaction_id` is new to Lago, the event is ingested;
    * If a `transaction_id` has already been received by Lago, it's ignored.

    <Tip>
      **Good practice:**
      Send the id of the transaction coming from your backend.
      If you do not have an existing id for a transaction, you can create a unique one
      by concatenating the `code` of the Billable metric and the `timestamp` of the
      event \*(example: `api_searches_2022-04-01T03:49:23Z`).
    </Tip>
  </Accordion>

  <Accordion title="2. The external_subscription_id">
    This attribute allows Lago to assign the event to the right subscription (and therefore to the right customer).
    The `external subscription_id` is required, as it ensures accurate billing.
  </Accordion>

  <Accordion title="3. The event code">
    The event `code` represents the unique code of the Billable metric you want to
    start ingest measurements on. This code is required for all events received in
    Lago. For instance, you can start ingesting events for Billable metrics with
    codes `api_seaches` *(for api products example)*, `storage` *(cloud companies
    example)*, `atm_withdrawals` *(fintech example)*, or anything you need to define
    as a paying feature.
  </Accordion>

  <Accordion title="4. The event timestamp">
    The event timestamp is the date when the billing event occurs in your
    application and sent to Lago. This event must be a
    **[UNIX Timestamp](https://www.unixtimestamp.com/).** For instance, you could
    define `1650893379` for *Mon Apr 25 2022 13:29:39 GMT+0000* or `1651682217`for
    *Wed May 04 2022 16:36:57 GMT+0000*.

    **This `timestamp` is not mandatory to send the event**. If you do not specify a
    timestamp on your own, Lago automatically defines the reception date of the
    event as the event timestamp.
  </Accordion>

  <Accordion title="5. The event properties">
    Event properties are useful to send more context in usage events. Moreover, they
    are also very useful when you need to aggregate a Billable metrics for `SUM`,
    `MAX` and `UNIQUE COUNT`. Event properties can be `strings`, `integers`,
    `floats`, `uuids` or `timestamps`.

    In case of an aggregation type `UNIQUE COUNT` for a metric that is `recurring`
    , the `operation_type` is required.
    By sending `add`, you will add a value. By sending `remove`, you will remove a value.
  </Accordion>
</AccordionGroup>

<Warning>If you were using the `external_customer_id` to send usage measurement, note that this field is deprecated and is no longer supported or maintained. Please use the `external_subscription_id` instead.</Warning>

## Idempotency and retries[](#idempotency-and-retries "Direct link to heading")

By using a unique `transaction_id`, can send events to Lago as much as you want
without worrying about sending twice the same event. Duplicates will be ignored
by our system. This ensures that your customers' usage is counted once. In case
of duplicates, we guarantee that only one of the events will be ingested, and
the other ones are ignored.

In case you are not sure if an event has been ingested, we recommend you to send
it multiple times (or to replay it). Once again, with the uniqueness of the
`transaction_id`, your customers won't be badly affected.

## User action trigger or periodic trigger[](#user-action-trigger-or-periodic-trigger "Direct link to heading")

With Lago, you can define when you need to trigger events based on the actions
your customers make in your application. There are 2 ways of tracking billing
events with Lago.

### User action trigger[](#user-action-trigger "Direct link to heading")

Anytime a user perform an action in your product, this sends an event to Lago.
This can be useful for companies tracking usage with a lot of granularity. As we
do the math for you, you can send events whenever you need and don't compute
hard calculations on your own.

For instance, think of a *fintech company* tracking user action. Each time a
customer withdraw money at an ATM, you send an event to Lago. We aggregate the
usage of a billable period based on what you defined in a Billable metric called
`atm_withdrawals`.

### Periodic trigger[](#periodic-trigger "Direct link to heading")

Some companies, such as infrastructure or cloud ones, often use periodic
triggers to calculate consumption. Think of the example of a thermometer to
measure fever. We would probably track the temperature once per hour (at a
periodic time). This is the same for cloud companies selling computation. You
could send an event to Lago each single minute measuring the CPU consumption of
a customer.

## Batching events

In Lago, event batching allows for the efficient ingestion of multiple events through a single API call.
This capability enhances data throughput and reduces the number of API requests needed for event management.

* **Batching multiple events:** Users can aggregate multiple events into a single batch. This consolidation enables the ingestion of numerous events simultaneously, significantly optimizing the data transmission process.
* **API call limitation:** Lago supports batching of up to 100 events per API call. This feature is designed to balance between high-volume data handling and system performance.
* **Validation process:** If any event within the batch does not meet the structural requirements, the entire batch will be rejected. This ensures data integrity and consistency. Users are advised to verify the structure of each event before batching to prevent rejections.

## Designed for flexibility[](#designed-for-flexibility "Direct link to heading")

Lago is designed to ingest a high number of events. By defining aggregation
rules, you can define any billing use cases your company might want to track.
Whether you need to send **[user action triggered](#user-action-trigger)**
events or **[periodic triggered](#periodic-trigger)** events, Lago does the math
on your own so you don't have to query heavy databases before charging your
customers.

## Next steps[](#next-steps "Direct link to heading")

Once you defined your Billable metrics (with their aggregation rules), and
started ingesting events to track usage, you are able to define how much your
customers will pay for it. This has to be specified in
**[Plans](/guide/plans/overview)**.