Dear Lago Community, 👋

We’re writing to inform you of upcoming changes in the Lago API that may impact your workflows.

​
Why are we doing this?

We understand that change can sometimes be challenging. However, we believe it’s essential for growth and improvement.

In our continuous efforts to improve Lago’s scalability and flexibility, we are updating our API to streamline the delivery of multiple features. This approach allows us to deliver more value to you and will pave the way for exciting new releases, including:

  1. Infinite Dimension Structure: With filters, enjoy unlimited depth in dimension structures, enabling you to merge multiple billable metrics into a single event code;
  2. High Usage Ingestion System: Overcome scalability issues with the ability to send over 10,000 events per second;
  3. Current/Past Usage Performance Improvements: Experience near-real-time data query with enhanced performance for current and past usage endpoints;
  4. Alerting Scenarios: Set up custom alerts for critical events such as unpaid invoices, reaching wallet credit thresholds, and many more;
  5. Workflow Creation: Seamlessly trigger actions within Lago based on custom scenarios, like pausing subscriptions or upgrading plans based on alerts; and
  6. Entitlements Scenarios: Utilize Lago’s aggregated usage data to manage access to product features based on custom rules.

​
Timeline

We will maintain the current API logic until July 9, 2024. However, after this date, previous versions will no longer be supported. We kindly ask you to update your integration before that day to avoid any potential breaking change.

​
What are the changes?

​
1. Transition from group to filters

We’re introducing a new method for building infinite levels of dimensions in Lago with the concept of filters.

Creating or editing billable metrics or plans via the user interface will result in the creation of filters. Therefore, you may encounter issues if you make changes via the interface but still use groups when creating or editing objects via API.

​
Impact on billable metrics

  • Introducing billable_metrics.filters
  • Deprecating billable_metrics.group

Deprecating “billable_metrics.group” The group object is deprecated and will be removed from the billable_metric object on July 9, 2024. Please update all integrations currently using billable_metrics.group (see example below).

with 1 level
{
  "billable_metric": {
    …
-    "group": {
-      "key": "provider",
-      "values": ["AWS", "Google", "Azure"]
-   }
+   "filters": [
+	  {
+	    "key": "provider",
+	    "values": ["AWS", "Google", "Azure"]
+	  }
+	]
  }
}
with 2 levels
{
  "billable_metric": {
    …
-    "group": {
-      "key": "provider",
-      "values": [
-        {
-          "name": "AWS",
-          "key": "region",
-          "values": ["Europe", "Africa", "Asia"]
-        },
-        {
-          "name": "Google",
-          "key": "region",
-          "values": ["Europe", "North America"]
-        },
-        {
-          "name": "Azure",
-          "key": "region",
-          "values": ["North America", "Asia"]
-        }
-      ]
-    }
+    "filters": [
+      {
+        "key": "provider",
+        "values": ["AWS", "Google", "Azure"]
+      },
+      {
+        "key": "region",
+        "values": ["Europe", "Africa", "Asia", "North America"]
+      }
+    ]
  }
}

Note that the billable_metric object will only display filters and groups if applicable.

​
Impact on API endpoints

  • Deprecating List all billable metric groups.

The endpoint List all billable metric groups is deprecated. It will be supported until July 9, 2024 and will then be removed.

GET https://api.getlago.com/api/v1/billable_metrics/{code}/groups

​
Impact on plans

  • Introducing plans.charges.filters
  • Deprecating plans.charges.group_properties

Deprecating “billable_metrics.groups” with one level The group_properties object is deprecated and will be removed from plans.charges on July 9, 2024.

Please update all integrations currently using plans.charges.group_properties (see example below).

{
  "plans": {
    …
    "charges": [
    {
      …
      "properties": {
        "amount": "0",
      },
-      "group_properties": [
-        {
-          "group_id": "__GROUP_ID__",
-          "invoice_display_name": "AWS in Europe",
-          "values": {
-            "amount": "15",
-          }
-        },
-        {
-          "group_id": "__GROUP_ID__",
-          "invoice_display_name": "Google in Europe",
-          "values": {
-            "amount": "20",
-          }
-        }
-      ]
+      "filters": [
+        {
+          "values": {
+            "provider": "AWS",
+            "region": "Europe"
+          },
+          "invoice_display_name": "AWS in Europe"
+          "properties": { "amount": "15" }
+        },
+        {
+          "values": {
+            "provider": "Google",
+            "region": "Europe"
+          },
+          "invoice_display_name": "Google in Europe"
+          "properties": { "amount": "20" }
+        }
+      ]
    }
  }
}

Note that the plan object will only display filters and group_properties if applicable.

​
Impact on fees

  • Introducing fees.lago_charge_filter_id
  • Deprecating fees.lago_group_id

Deprecating “billable_metrics.groups” with one level The lago_group_id field is deprecated and will be removed from fees on July 9, 2024.

Please update all integrations currently using fees.lago_group_id or invoice.fees.lago_group_id (see example below).

{
  "fees": {
    …
-    "lago_group_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
+    "lago_group_id": null,
+    "lago_charge_filter_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
    …
  }
}
This change also affects the invoice object.

​
Impact on customer usage

  • Introducing customer_usage.charges_usage.filters
  • Deprecating customer_usage.charges_usage.groups

Deprecating “billable_metrics.groups” with one level The charges_usage.groups field is deprecated and will be removed from customer_usage on July 9, 2024.

Please update all integrations currently using customer_usage.charges_usage.groups (see example below).

{
  "customer_usage": {
    …
    "charges_usage": [
      …
      {
-        "groups": [
-          {
-            "lago_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
-            "key": "null",
-            "value": "europe",
-            "units": "0.9",
-            "amount_cents": 1000,
-            "events_count": 10
-          }
-        ]
+        "filters": [
+          {
+            "values": {
+              "provider": "AWS",
+              "region": "Europe"
+            }
+            "units": "0.9",
+            "amount_cents": 1000,
+            "events_count": 10
+          }
+        ]
      }
    ]
    …
  }
}

​
2. Mandatory external_subscription_id field in event payloads

To enable real-time functionalities, event payloads must include external_subscription_id. Events that only include external_customer_id will not be taken into account when aggregating usage in upcoming versions.

  • Making events.external_subscription_id required

Making “events.external_subscription_id” required Sending event.external_subscription_id will be mandatory starting July 9, 2024.

Please update all integrations currently using POST /events (see example below).

{
  "event": {
    "transaction_id": "__UNIQUE_ID__",
-   "external_customer_id": "__YOUR_CUSTOMER_ID__",
+   "external_subscription_id": "__YOUR_SUBSCRIPTION_ID__",
    "code": "__BILLABLE_METRIC_CODE__",
    "timestamp": $(date +%s),
    "properties": {
      "custom_field": 12
    }
  }
}

​
3. Deprecated fields

We will remove the following deprecated fields in order to preserve the quality of the API and for clarity.

Deprecated fieldSubstitution field
applied_coupon.expiration_dateapplied_coupon.expiration_at
billable_metric.groupbillable_metric.filters
coupon.expiration_datecoupon.expiration_at
credit.before_vatcredit.before_taxes
credit.item.lago_idcredit.item.lago_item_id
credit_note.balance_amount_currencycredit_note.currency
credit_note.credit_amount_currencycredit_note.currency
credit_note.refund_amount_currencycredit_note.currency
credit_note.sub_total_vat_excluded_amount_currencycredit_note.currency
credit_note.sub_total_vat_excluded_amount_centscredit_note.sub_total_excluding_taxes_amount_cents
credit_note.total_amount_currencycredit_note.currency
credit_note.vat_amount_currencycredit_note.currency
credit_note.vat_amount_centscredit_note.taxes_amount_cents
credit_note.vat_amount_currencycredit_note.currency
customer.billing_configuration.vat_ratecustomer.taxes[].rate
customer_usage.amount_currencycustomer_usage.currency
customer_usage.charge_usages.groupscustomer_usage.charge_usages.filters
customer_usage.from_datecustomer_usage.from_datetime
customer_usage.to_datecustomer_usage.to_datetime
customer_usage.total_amount_currencycustomer_usage.currency
customer_usage.vat_amount_centscustomer_usage.taxes_amount_cents
customer_usage.vat_amount_currencycustomer_usage.currency
event_error.input_params.codeevent_error.event.code
event_error.input_params.external_customer_idevent_error.event.external_customer_id
event_error.input_params.external_subscription_idevent_error.event.external_subscription_id
event_error.input_params.propertiesevent_error.event.properties
event_error.input_params.timestampevent_error.event.timestamp
event_error.input_params.transaction_idevent_error.event.transaction_id
fee.unit_amount_centsfee.precise_unit_amount
fee.vat_amount_centsfee.taxes_amount_cents
fee.vat_amount_currencyfee.amount_currency
invoice.amount_currencyinvoice.currency
invoice.amount_centsinvoice.fees_amount_cents
invoice.credit_amount_currencyinvoice.currency
invoice.credit_amount_centsinvoice.credits[].amount_cents
invoice.fees.group_invoice_display_nameinvoice.fees.filter_invoice_display_name
invoice.fees.lago_group_idn/a
invoice.legacyn/a
invoice.sub_total_vat_excluded_amount_centsinvoice.sub_total_excluding_taxes_amount_cents
invoice.sub_total_vat_included_amount_centsinvoice.sub_total_including_taxes_amount_cents
invoice.total_amount_currencyinvoice.currency
invoice.vat_amount_centsinvoice.taxes_amount_cents
invoice.vat_amount_currencyinvoice.currency
organization.billing_configuration.vat_rateorganization.taxes[].rate
plan.charges.group_propertiesplan.charges.filters
subscription.subscription_datesubscription.subscription_at
wallet.balancewallet.balance_cents
wallet.expiration_datewallet.expiration_at `

​
Get involved

Your feedback is important to us. If you have any questions, encounter issues, or have suggestions, please reach out to us via the Slack community.

We understand that breaking changes may require you to adapt, so we apologize for any inconvenience caused. Our team is committed to providing support throughout this transition process to minimize disruptions.

Thanks for your understanding and continued support.

The Lago Team