Persisted events

Events represents the data delivered to lago application that will then be aggregated into billable metrics. By sending a persisted event, it's kept in memory and persisted through the next billable periods, unless you or your clients change it. At the end of each period, the total units to be charged is resumed to 0. Persisted events are available for all billable metrics having the following aggregation type: RECURRING_COUNT.

The following endpoint explains how to send a persisted event to a specific 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__",
          "external_customer_id": "__YOUR_CUSTOMER_ID__",
          "external_subscription_id": "__YOUR_SUBSCRIPTION_ID__",
          "code": "__EVENT_CODE__",
          "timestamp": $(date +%s),
          "properties": {
            "custom_field": 12,
            "operation_type": "add"
          }
      }
  }'

Python

from lago_python_client.client import Client
from lago_python_client.exceptions import LagoApiError
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", "operation_type": "add"}
)

try:
    client.events.create(event)
except LagoApiError as e:
    repair_broken_state(e)  # do something on error or raise your own exception

Ruby

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,
      operation_type: "add"
  }
)

Javascript

await client.events.createEvent({
  event: {
    transactionId: "__UNIQUE_TRANSACTION_ID__",
    externalCustomerId: "__UNIQUE_CUSTOMER_ID__",
    externalSubscriptionId: "__UNIQUE_SUBSCRIPTION_ID__",
    code: "code",
    timestamp: 1650893379,
    properties: { customField: "custom", operationType: "add" },
  },
});

Go

  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",
        "operation_type": "add",
            },
    }

    err := lagoClient.Event().Create(eventInput)
    if err != nil {
      // Error is *lago.Error
      panic(err)
    }
  }

C#

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

<?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,
      "operation_type": "add"
    }
  }
}

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. It might also contain an operation_type that can be either add or remove. Aggregation type: - RECURRING COUNT: required. value must be the unique identifier of the persisted object.

Content of the event properties object

Attributes	Types	Description
field_name (*)	String      Required	(*) Key must be the field_name configured at billable metric level and be the unique identifier of the object to persist.
operation_type	String      Required	Type of operation to perform on the persisted object. Possible values - add: Add or unsuspend a persisted object. - remove: Remove or suspend a persisted object.

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",
  "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