Skip to main content

Lago Destination

Nexla's bi-directional connectors allow data to flow both to and from any location, making it simple to create a FlexFlow data flow that sends data to a Lago location.
lago_api.png

Lago

Create a Lago Destination​

  1. Click the + icon on the Nexset that will be sent to the Lago destination, and select the Send to Destination option from the menu.

  2. Select the Lago connector from the list of available destination connectors. Then, select the credential that will be used to connect to the Lago organization, and click Next; or, create a new Lago credential for use in this flow.

  3. In Nexla, Lago destinations can be created using pre-built endpoint templates, which expedite destination setup for common Lago write operations. Each template is designed specifically for the corresponding Lago endpoint, making destination configuration easy and efficient.
    • To configure this destination using a template, follow the instructions in Configure Using a Template.

    Lago destinations can also be configured manually, allowing you to send data to Lago endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
    • To configure this destination manually, follow the instructions in Configure Manually.

Configure Using a Template​

Nexla provides pre-built templates that can be used to rapidly configure destinations to send data to common Lago API endpoints. Each template is designed specifically for the corresponding Lago write operation, making destination setup easy and efficient.

  • To configure this destination using a template, select the endpoint to which data will be sent from the Endpoint pulldown menu. Then, click on the template in the list below to expand it, and follow the instructions to configure additional endpoint settings.

    Ingest Usage Event

    This endpoint sends a single usage event to Lago. Usage events are the core input of Lago's metering system — each event represents one measurable unit of consumption (such as one API call, one GB of storage, or one compute minute) and is associated with a specific customer subscription and billable metric. Use this endpoint when your Nexset contains individual event records that should be ingested into Lago in real time or near-real time.

    • Each event record in your Nexset should include the following fields, which Lago requires for event ingestion:

      • Transaction ID: A unique identifier for the event. This must be a unique string per event and is used by Lago for idempotency — if the same transaction ID is submitted more than once, Lago will deduplicate it. A UUID or a combination of your system's record ID and timestamp is recommended.
      • External Subscription ID: The external ID of the subscription to which this usage event belongs. This must match the external_id of an active subscription in Lago.
      • Code: The code of the billable metric this event corresponds to. This must match the code of an existing billable metric in your Lago organization.
      • Timestamp: The Unix timestamp (in seconds) at which the event occurred. Lago uses this timestamp to assign the event to the correct billing period.
      • Properties: A JSON object containing the event's measurable values. The required properties depend on the aggregation type of the associated billable metric — for example, a sum metric requires a numeric value field, while a count metric requires no additional properties.

    Lago processes usage events asynchronously. After submission, events are validated and aggregated in the background. For high-volume event ingestion, consider using the Batch Usage Events endpoint instead to reduce API call overhead. For complete details on event ingestion, see the Lago Events API documentation.

    Batch Ingest Usage Events

    This endpoint sends multiple usage events to Lago in a single API call. Batch ingestion is the recommended approach for high-volume event workflows, as it significantly reduces the number of API requests required and improves overall throughput. Use this endpoint when your Nexset contains many usage event records that should be ingested into Lago efficiently.

    • Each event record in your Nexset should include the same fields as the single event endpoint: Transaction ID, External Subscription ID, Code, Timestamp, and Properties.
    • Configure record batching in the Nexla destination settings to group multiple event records into a single API call. A batch size of up to 100 events per call is recommended for optimal performance.

    Lago's batch event ingestion endpoint processes events asynchronously. All events in a batch are validated together — if any event in the batch fails validation, Lago will return an error for the entire batch. Ensure that all event records in your Nexset are correctly formatted before enabling batch ingestion. For complete details, see the Lago Batch Events API documentation.

    Create or Update Customer

    This endpoint creates a new customer in Lago or updates an existing customer record. Lago uses an upsert pattern — if a customer with the specified external_id already exists, the record is updated; otherwise, a new customer is created. Use this endpoint to keep your Lago customer records synchronized with your application's user or account database.

    • Each customer record in your Nexset should include the following fields:

      • External ID: The unique identifier for the customer in your application. This is the key Lago uses to identify the customer and must remain consistent across all API interactions for this customer.
      • Name: The customer's display name.
      • Email: The customer's billing email address. Lago sends invoices and billing notifications to this address.
      • Currency: The billing currency for this customer (for example, USD, EUR). If not specified, Lago uses the organization's default currency.
      • Billing Configuration (optional): Payment provider settings, including the payment provider type (Stripe, Adyen, GoCardless) and the customer's ID in that payment system.
      • Metadata (optional): A JSON object of custom key-value pairs for storing additional customer information.

    The external_id field is immutable after a customer is created in Lago. Ensure that the value you use matches the customer identifier in your application. For complete details on the customer object and all available fields, see the Lago Create/Update Customer API documentation.

    Create Subscription

    This endpoint assigns a pricing plan to a customer, creating a new subscription in Lago. Use this endpoint to programmatically provision subscriptions when new customers sign up for your service, when customers upgrade or change their plan, or when migrating existing subscription data into Lago.

    • Each subscription record in your Nexset should include the following fields:

      • External Customer ID: The external ID of the customer to whom this subscription will be assigned. The customer must already exist in Lago.
      • Plan Code: The code of the Lago plan to assign to this customer. The plan must already exist in your Lago organization.
      • External ID: A unique identifier for this subscription in your application. This is used to reference the subscription in future API calls, including event ingestion.
      • Subscription At (optional): The ISO 8601 datetime at which the subscription should start. If not provided, the subscription starts immediately.
      • Billing Time (optional): Whether billing is calendar (aligned to the start of the month/year) or anniversary (aligned to the subscription start date). Defaults to calendar.

    Lago supports plan upgrades and downgrades through this same endpoint — if an active subscription already exists for the customer and plan combination, Lago will handle the transition based on the plan's upgrade/downgrade rules. For complete details on subscription creation and plan switching, see the Lago Create Subscription API documentation.

Configure Manually​

Lago destinations can be manually configured to send data to any valid Lago API endpoint.

Using manual configuration, you can also configure Nexla to automatically send the response received from the Lago API after each call to a new Nexla webhook data source.

API Method​

  1. To manually configure this destination, select the Advanced tab at the top of the configuration screen.

  2. Select the API method that will be used for calls to the Lago API from the Method pulldown menu. Common methods for Lago write operations include:

    • POST: For creating new resources or ingesting events (customers, subscriptions, events, add-ons applied to customers)
    • PUT: For updating existing resources (customers, subscriptions)
    • DELETE: For terminating subscriptions or removing resources

Data Format​

  1. Select the format in which the Nexset data will be sent to the Lago API from the Content Format pulldown menu. The Lago API exclusively uses JSON for request bodies, so select JSON as the content format. Nexla will automatically convert the Nexset data to JSON for each API call.

API Endpoint URL​

  1. Enter the URL of the Lago API endpoint to which you want to send the Nexset data in the URL field. The base URL depends on your Lago deployment:

    • US Cluster (Lago Cloud): https://api.getlago.com/api/v1
    • EU Cluster (Lago Cloud): https://api.eu.getlago.com/api/v1
    • Self-Hosted: Your instance URL, typically https://<your-domain>/api/v1

    Append the resource path to the base URL — for example, https://api.getlago.com/api/v1/events to ingest usage events, or https://api.getlago.com/api/v1/customers to create or update customers.

For update or upsert operations that target a specific resource by ID, include the resource's external ID at the end of the URL (for example, https://api.getlago.com/api/v1/customers/{'{external_customer_id}'}). Ensure that your Lago API key has Write permission for the resource type you are targeting.

Request Headers​

Optional

  • If Nexla should include any additional request headers in API calls to this destination, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (e.g., header1:value1,header2:value2).

    You do not need to include the Authorization header here — it is automatically applied from your Lago credential. The Lago API requires Content-Type: application/json for all write operations; Nexla sets this automatically when JSON is selected as the content format.

Exclude Attributes from the Call​

Optional

  • If any record attributes in the Nexset should be omitted when sending data to this Lago destination, select the attributes from the Exclude Attributes pulldown menu. This is useful when your Nexset contains fields that are not valid in the Lago API request body and would cause validation errors.

  • Any number of attributes can be selected for exclusion, and all excluded attributes will be shown in the field. To remove an attribute from the list, click the X icon next to the attribute name.

Record Batching​

Optional

  1. If records should be sent to this destination in batched API calls, check the box next to Would you like to batch your records together? to enable record batching. Batching is recommended for high-volume usage event ingestion using the Lago batch events endpoint (POST /events/batch).

  2. Enter the maximum number of records that should be batched together in a single API call in the Batch Size field. By default, this value is set to 100.

  3. Select the algorithm that will be used to group records into batches from the Grouping Algorithm pulldown menu. The sample request shown in the panel on the right will be updated to reflect the current batching settings. Some algorithms require additional settings—click on an algorithm listed below to view instructions for configuring these settings.

    Property Inside JSON Object

    1. Enter the name of the JSON property that should contain the batched records in the Property Name field. For Lago's batch events endpoint, enter events to match the expected request body structure.
    2. If any additional properties should be included in the request, enter the properties in the Other Props field in JSON format.

    Code

    1. Enter the code that will be used to create the batched request in the code editor below the Grouping Algorithm field.

Response Webhook​

Optional

Nexla can automatically send the response received from the Lago API after each call to a new Nexla webhook data source. This option allows you to keep track of the status of each API call and any additional information returned after each call — for example, the Lago-generated IDs for newly created customers or subscriptions.

  • To enable this option, check the box next to Would you like to process the API response as a Nexla Webhook source?.

Sample Request Payload​

Sample request payloads containing a portion of the Nexset data that will be sent to the Lago API endpoint based on the current settings are shown in the Sample Payload panel on the right. These samples can be referenced to ensure that the destination and request settings are correctly configured.

  • Click on a sample request payload to expand it and view the complete payload content.

  • Sample payloads are automatically updated with each setting change, making it easy to verify that changes achieve the desired effect.

Endpoint Testing (Manual Configuration)​

After all endpoint settings have been configured, Nexla can send a test payload to the Lago API to ensure that the destination is configured correctly.

  1. To send a test payload, select the Test button at the top of the Sample Payload panel, and click on a listed sample payload to expand it.

  2. If any modifications to the sample payload are needed, make the necessary changes directly within the sample window.

  3. Click the Send Test Data button at the top of a sample payload to send the test payload to the Lago API using the current settings.

Save & Activate the Destination​

  • Once all endpoint settings have been configured, click the Done button in the upper right corner of the screen to save and create the destination. To begin sending data to the configured Lago endpoint, open the destination resource menu, and select Activate.

    The Nexset data will not be sent to Lago until the destination is activated. Destinations can be activated immediately or at a later time, providing full control over data movement.