Metered events
Events represents the data delivered to lago application that will then be aggregated into billable metrics. By sending a metered event, it's not persisted through the next billable periods. At the end of each period, the total units to be charged is resumed to 0.
Metered events are available for all billable metrics having the following aggregation type: COUNT
, SUM
, MAX
and COUNT_UNIQUE
.
The following endpoint explains how to send a metered event for a customer.
Route
POST
api/v1/events
Usage
- Curl
- Python
- Ruby
- Node.js
- Go
- C#
- PHP
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": "__EVENT_CODE__",
"timestamp": $(date +%s),
"properties": {
"custom_field": 12
}
}
}'
from lago_python_client import Client
from lago_python_client.models import Event
client = Client(api_key='__YOUR_API_KEY__')
event = Event(
transaction_id="__UNIQUE_ID__",
external_customer_id="__UNIQUE_ID__",
external_subscription_id="__UNIQUE_ID__",
code="code",
timestamp=1650893379,
properties={"custom_field": "custom"}
)
client.events().create(event)
require 'lago-ruby-client'
client = Lago::Api::Client.new({api_key: '__YOUR_API_KEY__'})
client.events.create(
transaction_id: "__UNIQUE_ID__",
external_customer_id: "__CUSTOMER_ID__",
external_subscription_id: "__SUBSCRIPTION_ID__",
code: "code",
timestamp: Time.now.to_i,
properties: {
custom_field: 12
}
)
import Client from 'lago-nodejs-client'
import Event from 'lago-nodejs-client/event'
let client = new Client('__API_KEY__')
let event = new Event({
transactionId: "__UNIQUE_TRANSACTION_ID__",
externalCustomerId: "__UNIQUE_CUSTOMER_ID__",
externalSubscriptionId: "__UNIQUE_SUBSCRIPTION_ID__",
code: "code",
timestamp: 1650893379,
properties: {customField: "custom"}
})
await client.createEvent(event);
import "fmt"
import "github.com/getlago/lago-go-client"
func main() {
lagoClient := lago.New().
SetApiKey("__YOUR_API_KEY__")
eventInput := &lago.EventInput{
TransactionID: "transac_1234",
ExternalCustomerID: "vincent_12345",
ExternalSubscriptionID: "1dbe81ce-b092-401c-a00b-314292e17a98",
Code: "code",
Timestamp: time.Now().Unix(),
Properties: map[string]string{
"nbusers": "12",
},
}
err := lagoClient.Event().Create(eventInput)
if err != nil {
// Error is *lago.Error
panic(err)
}
}
using System.Collections.Generic;
using System.Diagnostics;
using Org.OpenAPITools.Api;
using Org.OpenAPITools.Client;
using Org.OpenAPITools.Model;
namespace Example
{
public class CreateEventExample
{
public static void Main()
{
Configuration.Default.BasePath = "https://api.getlago.com/api/v1";
// Configure HTTP bearer authorization: bearerAuth
Configuration.Default.AccessToken = "YOUR_ACCESS_TOKEN";
var apiInstance = new EventsApi(Configuration.Default);
var eventInput = new EventInput(); // EventInput | Event payload
try
{
// Create a new event
apiInstance.CreateEvent(eventInput);
}
catch (ApiException e)
{
Debug.Print("Exception when calling EventsApi.CreateEvent: " + e.Message );
Debug.Print("Status Code: "+ e.ErrorCode);
Debug.Print(e.StackTrace);
}
}
}
}
<?php
require_once(__DIR__ . '/vendor/autoload.php');
// Configure Bearer authorization: bearerAuth
$config = OpenAPI\Client\Configuration::getDefaultConfiguration()->setAccessToken('YOUR_ACCESS_TOKEN');
$apiInstance = new OpenAPI\Client\Api\EventsApi(
// If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
// This is optional, `GuzzleHttp\Client` will be used as default.
new GuzzleHttp\Client(),
$config
);
$event_input = new \OpenAPI\Client\Model\EventInput(); // \OpenAPI\Client\Model\EventInput | Event payload
try {
$apiInstance->createEvent($event_input);
} catch (Exception $e) {
echo 'Exception when calling EventsApi->createEvent: ', $e->getMessage(), PHP_EOL;
}
Arguments
{
"event": {
"transaction_id": "__UNIQUE_ID__",
"external_customer_id": "__CUSTOMER_ID__",
"external_subscription_id": "__SUBSCRIPTION_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 |
external_subscription_id | String Optional | Unique subscription ID in your application.external_subscription_id is required if the customer has multiple subscriptions or if external_customer_id is not provided (in case there's only one subscription) |
external_customer_id | String Optional | Unique customer ID in your application. If external_subscription_id is not given, external_customer_id is required if there is only one subscription attached to customer. For multiple subscriptions per customer this attribute is not enough |
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 in seconds of the event occurence (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 : not used- MAX : required. value must be a number- SUM : required. value must be a number- COUNT UNIQUE : required. value could have any datatype |
Responses
- HTTP 200
- HTTP 400
- HTTP 401
- HTTP 422
The event has been stored in the system and will be aggregated to generate fees.
Returns an empty response body.
{
"status": 400,
"error": "Bad Request",
}
The event
json root is not present in the request body.
{
"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
{
"status": 422,
"error": "Unprocessable entity",
"code": "validation_errors",
"error_details": {
"field": ["error"]
}
}
Possible errors:
field | error | description |
---|---|---|
base | missing_external_identifier | None of external_subscription_id or external_customer_id arguments were provided |
transaction_id | value_is_mandatory | transaction_id value is missing |
code | value_is_mandatory | code value is missing |
external_subscription_id | value_is_mandatory | external_subscription_id is missing |