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.

​

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

- { "billable_metric": {
    …
    "group": {
      "key": "provider",
      "values": ["AWS", "Google", "Azure"]
    }
  }
}
+ { "billable_metric": {
    …
    "filters": [
			{
	      "key": "provider",
	      "values": ["AWS", "Google", "Azure"]
	    }
		]
  }
}

- { "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"]
        }
      ]
    }
  }
}
+ { "billable_metric": {
    …
    "filters": [
			{
	      "key": "provider",
	      "values": ["AWS", "Google", "Azure"]
	    },
			{
	      "key": "region",
	      "values": ["Europe", "Africa", "Asia", "North America"]
	    }
		]
  }
}

​

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",
          }
        }
      ]
    }
  }
}
+ { "plans": {
    …
    "charges": [
		{
	    …
      "properties": {
        "amount": "0",
      },
      "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" }
				}
      ]
    }
  }
}

​

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",
		…
	}
}
+ { "fees": {
		…
		"lago_group_id": null,
		"lago_charge_filter_id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
		…
	}
}

​

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
          }
				]
			}
		]
		…
	}
}
+ { "customer_usage": {
		…
		"charges_usage": [
			…
			{
				"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.

• Making events.external_subscription_id required

Making “events.external_subscription_id” required Sending event.external_subscription_id will be mandatory from 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__",
	"code": "__BILLABLE_METRIC_CODE__",
	"timestamp": $(date +%s),
	"properties": {
		  "custom_field": 12
		}
	}
}
+ { "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.

​

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