Lago

Lago is an open-source metering and usage-based billing platform designed for engineers and product teams that need flexible, event-driven billing infrastructure. Lago ingests real-time consumption events, aggregates usage into billable metrics, manages subscription plans and pricing models (flat-rate, tiered, volume, pay-as-you-go, and hybrid), and automatically generates invoices. It supports prepaid credits, coupons, add-ons, payment orchestration, and revenue analytics—making it a comprehensive alternative to Stripe Billing, Chargebee, or Recurly for companies with complex pricing logic. Lago is available as a self-hosted deployment or as Lago Cloud.

Power end-to-end data operations for your Lago API with Nexla. Our bi-directional Lago connector is purpose-built for Lago, making it simple to ingest data, sync it across systems, and deliver it anywhere — all with no coding required. Nexla turns API-sourced data into ready-to-use, reusable data products and makes it easy to send data to Lago or any other destination. With comprehensive monitoring, lineage tracking, and access controls, Nexla keeps your Lago workflows fast, secure, and fully governed.

Features

Type: API

SourceDestination

• Seamless API Integration: Connect to any endpoint as source or destination without coding, with automatic data product creation
• Visual Composition & Chaining: Build complex integrations using visual templates, chain API calls, and compose workflows with data validation and filtering
• API Proxy: Expose curated slices of your data securely with a secure and customizable API proxy that validates and transforms data on the fly
• Request optimization with intelligent batching, retry, and caching to minimize API calls and costs

Prerequisites

Lago uses API key authentication. All API requests must include a Bearer token in the Authorization header. Your API key is scoped with granular permissions that you configure in the Lago dashboard.

Lago Account and API Key Setup

To connect Nexla to Lago, you need a Lago account (either self-hosted or Lago Cloud) and an API key.

For Lago Cloud:

1. Sign in to your Lago Cloud account at app.getlago.com.

2. Navigate to Developers in the left sidebar, then select API keys.

3. Click the Add a key button to create a new API key.

4. Optionally, provide a descriptive name for the key (for example, "Nexla Integration") to identify its purpose later.

5. Configure the permissions for this API key. Lago supports granular per-object permissions:

   • Set each resource (customers, subscriptions, invoices, events, billable metrics, plans, etc.) to Read, Write, or Read & Write as needed for your integration.

   • For a data source integration (reading data into Nexla), granting Read access to the relevant resources is sufficient.

   • For a destination integration (writing data from Nexla to Lago), grant Write or Read & Write access to the resources you intend to update.

6. Click Save (or Create) to generate the API key.

Important

Copy and securely store your API key immediately after creation. For security reasons, the full key value is only displayed once. If you lose access to it, you will need to rotate or delete the key and create a new one.

For Lago Self-Hosted:

1. Log in to your self-hosted Lago instance.

2. Navigate to Developers > API keys in the dashboard.

3. Click Add a key, optionally name it, configure permissions, and click Save.

4. Copy the generated API key and store it securely.

To rotate an existing API key, navigate to Developers > API keys and click the Rotate API key button. The previous key is immediately deactivated when a new key is generated. For additional details on API key management, see the Lago API Keys documentation.

Base URL

The API base URL depends on your 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 own instance URL, typically https://<your-domain>/api/v1

You will need this base URL when configuring data source and destination endpoints in Nexla.

Authenticate

Create a credential in Nexla

1. After selecting the data source/destination type, click the Add Credential tile to open the Add New Credential overlay.

2. Enter a name for the credential in the Credential Name field and a short, meaningful description in the Credential Description field.

3. Enter your Lago API key in the API Key field. This key authenticates all requests Nexla makes to the Lago API and should be kept secure. Nexla will include it as a Bearer token in the Authorization header of every API call.

   Your Lago API key is a sensitive credential. Do not share it publicly or include it in source code. Use Nexla's credential management to keep it secure.

4. Click the Save button at the bottom of the overlay. The newly added credential will now appear in a tile on the Authenticate screen during data source/destination creation.

Use as a data source

To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Select the Lago connector tile, then select the credential that will be used to connect to the Lago instance, and click Next; or, create a new Lago credential for use in this flow.

Endpoint templates

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Lago API endpoints. Each template is designed specifically for the corresponding Lago resource, making data source setup easy and efficient. Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below.

List Customers

This endpoint retrieves all customers in your Lago organization. Use this endpoint when you need to sync your customer records — including contact details, billing configuration, tax information, and custom metadata — into Nexla for reporting, analysis, or downstream processing.

• This endpoint automatically retrieves all customers accessible to your Lago organization. No additional configuration is required beyond selecting this endpoint template.
• The endpoint uses pagination to handle large customer lists efficiently, automatically fetching additional pages as needed.

Each customer record includes the customer's external ID (used to identify them in your application), billing email, payment provider configuration, tax codes, and any custom metadata fields. For complete details on the customer object schema, see the Lago Customers API documentation.

List Subscriptions

This endpoint retrieves all subscriptions in your Lago organization. Use this endpoint to sync subscription data — including plan assignments, billing intervals, start and end dates, and subscription status — into Nexla for revenue analysis, churn reporting, or operational workflows.

• This endpoint automatically retrieves all subscriptions. No additional configuration is required beyond selecting this endpoint template.

• Optionally, configure the following parameters to filter the results returned by this endpoint:

  • External Customer ID: Filter subscriptions for a specific customer by entering the customer's external ID. This is the ID used in your application to identify the customer.
  • Plan Code: Filter subscriptions by a specific plan code to retrieve only subscriptions assigned to that plan.
  • Status: Filter subscriptions by their current status (for example, active, pending, terminated, or canceled).

Subscription records include the assigned plan, billing interval, subscription dates, and current status. For complete details on the subscription object schema, see the Lago Subscriptions API documentation.

List Invoices

This endpoint retrieves all invoices generated in your Lago organization. Use this endpoint to sync invoice data — including line items, amounts, tax details, payment status, and associated customer and subscription information — into Nexla for financial reporting, accounts receivable workflows, or revenue recognition.

• This endpoint automatically retrieves all invoices. No additional configuration is required beyond selecting this endpoint template.

• Optionally, configure the following parameters to filter the invoices returned:

  • External Customer ID: Filter invoices for a specific customer.
  • Status: Filter invoices by payment status (for example, draft, finalized, or voided).
  • Issuing Date From / To: Restrict results to invoices issued within a specific date range by entering ISO 8601 formatted dates (for example, 2024-01-01).

Invoice records include all line items, tax amounts, total amounts due, payment provider details, and the full customer and subscription context. For complete details on the invoice object schema, see the Lago Invoices API documentation.

List Billable Metrics

This endpoint retrieves all billable metrics defined in your Lago organization. Billable metrics define how raw usage events are aggregated into measurable, billable values — for example, the number of API calls, the total gigabytes of storage used, or the number of active seats. Use this endpoint to sync your metric definitions into Nexla for documentation, auditing, or downstream analytics.

• This endpoint automatically retrieves all billable metrics. No additional configuration is required beyond selecting this endpoint template.

Billable metric records include the metric name, code, aggregation type (such as count, sum, max, or unique_count), and any associated filters or groups. For complete details, see the Lago Billable Metrics API documentation.

List Plans

This endpoint retrieves all pricing plans defined in your Lago organization. Plans define the charges, pricing models (flat fee, tiered, volume, pay-in-advance, etc.), and billing intervals available to your customers. Use this endpoint to sync your plan catalog into Nexla for product analytics, pricing audits, or revenue modeling.

• This endpoint automatically retrieves all plans. No additional configuration is required beyond selecting this endpoint template.

Plan records include the plan name, code, billing interval, currency, all associated charges and their pricing models, and any minimum commitment amounts. For complete details on the plan object schema, see the Lago Plans API documentation.

List Events

This endpoint retrieves usage events that have been ingested into your Lago organization. Usage events are the raw measurements — such as API calls, data transfers, or compute minutes — that Lago aggregates into billable metrics. Use this endpoint to sync event data into Nexla for usage analytics, debugging, or detailed billing audits.

• This endpoint automatically retrieves events. No additional configuration is required beyond selecting this endpoint template.

• Optionally, configure the following parameters to filter the events returned:

  • External Subscription ID: Filter events for a specific subscription by entering the subscription's external ID.
  • Code: Filter events by billable metric code to retrieve only events for a specific metric.
  • Timestamp From / To: Restrict results to events that occurred within a specific time range by entering Unix timestamps.

Event records include the transaction ID, external subscription ID, billable metric code, timestamp, and all associated properties. For complete details on the event object schema, see the Lago Events API documentation.

List Coupons

This endpoint retrieves all coupons defined in your Lago organization. Coupons represent discounts — either fixed amounts or percentages — that can be applied to customer invoices. Use this endpoint to sync coupon definitions into Nexla for promotional analysis, discount reporting, or revenue impact modeling.

• This endpoint automatically retrieves all coupons. No additional configuration is required beyond selecting this endpoint template.

Coupon records include the coupon name, code, discount type (fixed amount or percentage), amount or percentage value, frequency (once, recurring, or forever), expiration date, and usage limits. For complete details, see the Lago Coupons API documentation.

List Add-Ons

This endpoint retrieves all add-ons defined in your Lago organization. Add-ons are one-time charges that can be applied to a customer's invoice outside of regular subscription billing — for example, a setup fee, a professional services charge, or a hardware cost. Use this endpoint to sync add-on definitions into Nexla for financial reporting or catalog management.

• This endpoint automatically retrieves all add-ons. No additional configuration is required beyond selecting this endpoint template.

Add-on records include the add-on name, code, amount, currency, and associated tax codes. For complete details on the add-on object schema, see the Lago Add-Ons API documentation.

Get Customer Current Usage

This endpoint retrieves the current billing period usage for a specific customer and subscription. It returns the aggregated usage for each billable metric in the current, still-open billing period — including current amounts owed before the invoice is finalized. Use this endpoint when you need near-real-time visibility into a customer's active consumption.

• Configure the following required parameters for this endpoint:

  • External Customer ID: Enter the external ID of the customer whose current usage you want to retrieve. This is the ID used in your application to identify the customer (the same value used when the customer was created in Lago).
  • External Subscription ID: Enter the external ID of the subscription for which you want to retrieve usage data.

The current usage response includes per-metric usage records showing the aggregated value, units consumed, and the current amount due. This data is for the active billing period and will change as new events are ingested. For complete details, see the Lago Customer Usage API documentation.

Once the selected endpoint template has been configured, click the Test button to the right of the endpoint selection menu to retrieve a sample of the data that will be fetched. Sample data will be displayed in the Endpoint Test Result panel on the right, allowing you to verify that the source is configured correctly before saving.

Manual configuration

Lago data sources can also be manually configured to ingest data from any valid Lago API endpoint, including endpoints not covered by the pre-built templates, chained API calls, or custom request parameters. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, endpoint URL, date/time and lookup macros, path to data, metadata, and request headers.

Append the resource path to the Lago base URL (see Prerequisites) — for example, /customers to list customers or /invoices to list invoices. Ensure your Lago API key has Read permission for the resource you are accessing.

Lago API responses wrap resource lists in a named array alongside pagination metadata, so specifying the path to data is essential — for example, $.customers[*] for List Customers, $.invoices[*] for List Invoices, $.subscriptions[*] for List Subscriptions, $.billable_metrics[*] for List Billable Metrics, $.plans[*] for List Plans, and $.events[*] for List Events. Use $.meta as the path to metadata to capture Lago's pagination details (total count, current page, next/previous page).

You do not need to include the Authorization header here — it is automatically applied from your Lago credential.

Once all of the relevant settings have been configured, click the Create button in the upper right corner of the screen to save and create the new Lago data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.

Use as a destination

Click the + icon on the Nexset that will be sent to the Lago destination, and select the Send to Destination option from the menu. 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.

Endpoint templates

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. 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.

Manual configuration

Lago destinations can also be manually configured to send data to any valid Lago API endpoint. Select the Advanced tab at the top of the configuration screen, and follow the instructions in Connect to Any API to configure the API method, data format, endpoint URL, request headers, attribute exclusions, record batching, and response webhooks.

Common methods for Lago destinations include POST (creating customers and subscriptions, or ingesting events), PUT (updating existing customers or subscriptions), and DELETE (terminating subscriptions or removing resources). The Lago API exclusively uses JSON for request bodies.

Append the resource path to the Lago base URL (see Prerequisites) — for example, /events to ingest usage events or /customers to create or update customers. For update/upsert operations, include the resource's external ID at the end of the URL (e.g., /customers/{'{external_customer_id}'}).

You do not need to include the Authorization or Content-Type headers — these are applied automatically. If batching records for Lago's batch events endpoint (POST /events/batch), use the Property Inside JSON Object grouping algorithm with a Property Name of events; a batch size of up to 100 events per call is recommended.

Save & activate

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.