Send usage event

POST

events

Authorization

Body

LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/events" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
      "event": {
          "transaction_id": "__UNIQUE_ID__",
          "external_customer_id": "__YOUR_CUSTOMER_ID__",
          "external_subscription_id": "__YOUR_SUBSCRIPTION_ID__",
          "code": "__BILLABLE_METRIC_CODE__",
          "timestamp": $(date +%s),
          "properties": {
            "custom_field": 12
          }
      }
  }'

{
  "event": {
    "code": "storage",
    "created_at": "2022-04-29T08:59:51Z",
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "external_subscription_id": "sub_1234567890",
    "lago_customer_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "lago_subscription_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "properties": {
      "gb": 10
    },
    "timestamp": "2022-04-29T08:59:51.123Z",
    "transaction_id": "transaction_1234567890"
  }
}

Authorizations

Authorization

string

headerrequired

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

event

object

required

Response

200 - application/json

event

object

required

event.code

string

required

The code that identifies a targeted billable metric. It is essential that this code matches the code property of one of your active billable metrics. If the provided code does not correspond to any active billable metric, it will be ignored during the process.

event.created_at

string

required

The creation date of the event's record in the Lago application, presented in the ISO 8601 datetime format, specifically in Coordinated Universal Time (UTC). It provides the precise timestamp of when the event's record was created within the Lago application

event.external_customer_id

string | null

required

The customer external unique identifier (provided by your own application). This field is optional if you send the external_subscription_id, targeting a specific subscription.

event.external_subscription_id

string | null

required

The unique identifier of the subscription within your application. It is a mandatory field when the customer possesses multiple subscriptions or when the external_customer_id is not provided.

event.lago_customer_id

string | null

required

Unique identifier assigned to the customer within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the customer's record within the Lago system

event.lago_id

string

required

Unique identifier assigned to the event within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the event's record within the Lago system

event.lago_subscription_id

string | null

required

Unique identifier assigned to the subscription within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the subscriptionâ€™s record within the Lago system

event.properties

object

This field represents additional properties associated with the event, which are utilized in the calculation of the final fee. This object becomes mandatory when the targeted billable metric employs a sum_agg, max_agg, or unique_count_agg aggregation method. However, when using a simple count_agg, this object is not required.

event.timestamp

string

required

This field captures the Unix timestamp in seconds indicating the occurrence of the event in Coordinated Universal Time (UTC). If this timestamp is not provided, the API will automatically set it to the time of event reception.

event.transaction_id

string

required

This field represents a unique identifier for the event. It is crucial for ensuring idempotency, meaning that each event can be uniquely identified and processed without causing any unintended side effects.

Was this page helpful?

The event object Batch usage events

LAGO_URL="https://api.getlago.com"
API_KEY="__YOUR_API_KEY__"

curl --location --request POST "$LAGO_URL/api/v1/events" \
--header "Authorization: Bearer $API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
      "event": {
          "transaction_id": "__UNIQUE_ID__",
          "external_customer_id": "__YOUR_CUSTOMER_ID__",
          "external_subscription_id": "__YOUR_SUBSCRIPTION_ID__",
          "code": "__BILLABLE_METRIC_CODE__",
          "timestamp": $(date +%s),
          "properties": {
            "custom_field": 12
          }
      }
  }'

{
  "event": {
    "code": "storage",
    "created_at": "2022-04-29T08:59:51Z",
    "external_customer_id": "5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba",
    "external_subscription_id": "sub_1234567890",
    "lago_customer_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "lago_subscription_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    "properties": {
      "gb": 10
    },
    "timestamp": "2022-04-29T08:59:51.123Z",
    "transaction_id": "transaction_1234567890"
  }
}

API Reference

Authorizations

Body

Response