Events

Events represents the data delivered to lago application that will then be aggregated into billable metrics. The following endpoint explains how to send an event for a customer.

Route

POST

api/v1/events

Usage

Curl

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__",
          "customer_id": "__CUSTOMER_ID__",
          "code": "__EVENT_CODE__", 
          "timestamp": $(date +%s), 
          "properties": { 
            "custom_field": 12 
          }
      } 
  }'

Python

from lago_python_client import Client
from lago_python_client.models import Event

client = Client(api_key='__YOUR_API_KEY__')

event = Event(
  customer_id="__UNIQUE_ID__",
  transaction_id="__UNIQUE_ID__",
  code="code",
  timestamp=1650893379,
  properties={"custom_field": "custom"}
)

client.events().create(event)

Ruby

require 'lago-ruby-client'

client = Lago::Api::Client.new({api_key: '__YOUR_API_KEY__'})

client.events.create(
  transaction_id: "__UNIQUE_ID__",
  customer_id:  "__CUSTOMER_ID__",
  code:  "code",
  timestamp: Time.now.to_i,
  properties: {
      custom_field: 12
  }
)

Node.js

import Client from 'lago-nodejs-client'
import Event from 'lago-nodejs-client/event'

let client = new Client('__API_KEY__')

let event = new Event(
  "5eb02857-a71e-4ea2-bcf9-57d8885990ba", // customerId
  "__UNIQUE_TRANSACTION_ID__",  // transactionId
  "code",  // code
  1650893379, // timestamp
  {customField: "custom"} // properties
)

await client.createEvent(event);

Arguments

{
  "event": {
    "transaction_id": "__UNIQUE_ID__",
    "customer_id": "__CUSTOMER_ID__",
    "code": "__EVENT_CODE__",
    "timestamp": 1650893379,
    "properties": {
      "custom_field": 12
    }
  }
}

Attributes	Type	Description
transaction_id	String      Required	Unique ID identifying the event. As it will be used for idempotency, it should be a unique identifier
customer_id	String      Required	Customer unique identifier in your application
code	String      Required	Code identifying the type of the event. It should match the code property of one of your active billable metrics, otherwise it will be ignored
timestamp	Integer      Optional Default: event reception timestamp	Unix timestamp of the event occurence in UTC. If not provided, the API will set the event reception time
properties	JSON      Variable	Extra data to use for the event aggregation. When mandatory, it should contains the field_name configured at billable metric level as key and any value as field value. Aggregation type: - COUNT: optional - MAX: required. value must be an integer - SUM: required. value must be an integer - COUNT UNIQUE: required. value could have any datatype

Responses

HTTP 200

The event has been stored in the system and will be aggregated to generate fees.

Returns an empty response body.

HTTP 400

{
  "status": 400,
  "error": "Bad Request",
}

The event json root is not present in the request body.

HTTP 401

{
  "status": 401,
  "error": "Unauthorized",
}

Access to the API end point is unhautorized.

Possible reasons are:

• The Authorization header is missing
• The Authorization header does not contain the API key
• The Api key is invalid or expired

HTTP 422

{
  "status": 422,
  "error": "Unprocessable entity",
  "message": "missing_mandatory_param",
  "error_details": [
      "transaction_id"
  ]
}

Required arguments are missing.