Lago Data Source

The Lago connector enables you to ingest billing and subscription data — including customers, subscriptions, invoices, billable metrics, plans, coupons, events, and usage records — from your Lago account into Nexla. Follow the instructions below to create a new data flow that ingests data from a Lago source in Nexla.

Lago

Create a New Data Flow

1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

2. Select the Lago connector tile from the list of available connectors. 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.

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

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

Configure Using a Template

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.

Endpoint Settings

• 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. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

  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.

Endpoint Testing

Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.

• To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

• If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually

Lago data sources can be manually configured to ingest data from any valid Lago API endpoint. Manual configuration provides maximum flexibility for accessing endpoints not covered by pre-built templates or when you need custom API configurations.

With manual configuration, you can also create more complex Lago sources, such as sources that use chained API calls to fetch data from multiple endpoints or sources that require custom request parameters.

API Method

1. To manually configure this source, 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. The most common methods are:

   • GET: For retrieving data from the API (used for all read operations such as listing customers, invoices, and subscriptions)
   • POST: For sending data to the API or triggering actions (used for creating resources or ingesting events)
   • PUT: For updating existing data
   • PATCH: For partial updates to existing data
   • DELETE: For removing data

API Endpoint URL

3. Enter the URL of the Lago API endpoint from which this source will fetch data in the Set API 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/customers to list all customers, or https://api.getlago.com/api/v1/invoices to list all invoices.

Lago's REST API follows a consistent URL pattern. All resource endpoints are documented in the Lago API Reference. Ensure that your Lago API key has Read permission for the resource you are trying to access.

Date/Time Macros (API URL)

Optional

Optionally, the API URL can be customized using macros—all macros added to the API URL will be converted into values when Nexla executes the API call. Macros are dynamic placeholders that allow you to create flexible API endpoints that can adapt to different time periods or data requirements.

Date/time macros are particularly useful with Lago endpoints that support date range filtering — for example, filtering invoices by issuing_date_from and issuing_date_to query parameters to ingest only invoices from the current billing period.

1. To add a macro, type { at the appropriate position in the API URL (within the Set API URL field), and select the desired macro from the dropdown list.

   • {now} – The current datetime
   • {now-1} – The datetime one time unit before the current datetime
   • {now+1} – The datetime one time unit after the current datetime
   • custom – Datetime macros can reference any number of time units before or after the current datetime—for example, enter (now-4) to indicate the datetime four time units before the current datetime

2. Select the format that will be applied to datetime macros from the Date Format for Date/Time Macro pulldown menu. This format will be applied to the base datetime value of the macro—i.e., the value of {now} in {now-1}.

3. Select the datetime unit that will be used to perform mathematical operations in the included macro(s) from the Time Unit for Operations pulldown menu—for example, for the macro {now-1}, when Day is selected, {now-1} will be converted to the datetime one day before the current datetime.

Lookup-Based Macros (API URL)

Optional

Column values from existing lookups can also be included as macros in the API URL. Lookup-based macros allow you to reference data from previously configured data sources or lookups, enabling dynamic API endpoints that can adapt based on existing data.

Lookup-based macros are particularly useful with Lago's customer-scoped and subscription-scoped endpoints. For example, you can use a lookup containing customer external IDs to dynamically construct per-customer usage URLs such as https://api.getlago.com/api/v1/customers/{'{external_customer_id}'}/current_usage.

1. To include a lookup column value macro, select the relevant lookup from the Add Lookups to Supported Macros pulldown menu.

2. Type { at the appropriate position in the API URL, and select the lookup column-based macro from the dropdown list. Lookup-based macros are automatically populated into the macro list when a lookup is selected in the Add Lookups to Supported Macros pulldown menu.

Path to Data

Optional

If only a subset of the data that will be returned by the API endpoint is needed, you can designate the part(s) of the response that should be included in the Nexset(s) produced from this source by specifying the path to the relevant data within the response. Lago API responses consistently wrap resource lists in a named array within the JSON response body.

For example, a GET /customers request returns a JSON object with a customers array containing the customer records, along with pagination metadata.

Path to Data is essential for Lago API responses. Without specifying the correct path, Nexla will treat the entire response — including the pagination metadata — as a single record rather than extracting the individual resource records.

• To specify which data should be treated as relevant in responses from this source, enter the path to the relevant data in the Set Path to Data in Response field.

  • For Lago responses in JSON format, enter the JSON path that points to the array of records. JSON paths use dot notation (e.g., $.customers[*] to access the customers array, $.invoices[*] for invoices, $.subscriptions[*] for subscriptions).
  Path to Data Examples for Common Lago Endpoints:

  • List Customers: $.customers[*]
  • List Invoices: $.invoices[*]
  • List Subscriptions: $.subscriptions[*]
  • List Billable Metrics: $.billable_metrics[*]
  • List Plans: $.plans[*]
  • List Events: $.events[*]

Autogenerate Path Suggestions

Nexla can also autogenerate data path suggestions based on the response from the API endpoint. These suggested paths can be used as-is or modified to exactly suit your needs.

• To use this feature, click the Test button next to the Set API URL field to fetch a sample response from the API endpoint. Suggested data paths generated based on the content & format of the response will be displayed in the Suggestions box below the Set Path to Data in Response field.

• Click on a suggestion to automatically populate the Set Path to Data in Response field with the corresponding path. The populated path can be modified directly within the field if further customization is needed.

  

Metadata

If metadata is included in the response but is located outside of the defined path to relevant data, you can configure Nexla to include this data as common metadata in each record. Lago API list responses include a meta object with pagination details — total count, current page, next page, and previous page — alongside the data array.

Capturing Lago's pagination metadata (such as total record count) as record-level metadata can be useful for monitoring data completeness and tracking ingestion coverage.

• To specify the location of metadata that should be included with each record, enter the path to the relevant metadata in the Path to Metadata in Response field.

  • For Lago responses in JSON format, enter the JSON path to the metadata object — for example, $.meta to capture Lago's standard pagination metadata.

Request Headers

Optional

• If Nexla should include any additional request headers in API calls to this source, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (e.g., header1:value1,header2:value2). The Lago API uses JSON for all request and response bodies.

  You do not need to include the Authorization header here — it is automatically applied from your Lago credential. If you are calling a Lago endpoint that requires a specific API version header, you can include it here (e.g., Content-Type:application/json).

Endpoint Testing

After configuring all settings for the selected endpoint, Nexla can retrieve a sample of the data that will be fetched according to the current configuration. This allows users to verify that the source is configured correctly before saving.

• To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

• If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Save & Activate the Source

1. Once all of the relevant steps in the above sections have been completed, 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.