Description
@blackswampai/n8n-nodes-lago
Installation · Operations · Credentials · Compatibility · Usage · Troubleshooting · Resources · Black Swamp AI
This is an n8n community node. It lets you use Lago in your n8n workflows.
Lago is an open-source billing and metering platform for subscription, usage-based, and hybrid pricing. It turns raw usage events into invoices, and covers plans, prepaid credit wallets, coupons, credit notes, and the billing lifecycle around them.
> This is an independent community integration and is not affiliated with, endorsed by,
> sponsored by, or maintained by Lago. The Lago name and logo belong to their respective owners
> and are used only to identify compatibility.
n8n is a fair-code licensed workflow automation platform.
Installation
Lago is a community package that is not currently available through verified-node discovery. On a
self-hosted n8n instance, open Settings → Community Nodes, select Install, and enter this exact
package name:
@blackswampai/n8n-nodes-lago
See n8n’s
GUI installation guide
for the current self-hosted community-node requirements. As an advanced self-hosted
administrator fallback, install the package in the n8n environment:
npm install @blackswampai/n8n-nodes-lago
Published from GitHub Actions with an SLSA provenance attestation,
so the package can be traced to the repository and commit it was built from:
npm view @blackswampai/n8n-nodes-lago dist.attestations
Operations
The Lago node currently supports:
| Resource | Operations |
| —————— | ———————————————————————————————— |
| Billable Metric | Create, Get, Get Many, Update, Delete, Evaluate Expression |
| Coupon | Create, Get, Get Many, Update, Delete, Apply to Customer, Get Many Applied, Remove from Customer |
| Credit Note | Create, Estimate, Get, Get Many, Download, Void |
| Customer | Create or Update, Get, Get Many, Delete |
| Event | Send, Send Batch, Get, Get Many, Estimate Fees |
| Invoice | Create One-Off, Get, Get Many, Update, Finalize, Void, Download, Retry Payment |
| Plan | Create, Get, Get Many, Update, Delete |
| Plan Charge | Create, Get, Get Many, Update, Delete |
| Subscription | Create, Get, Get Many, Update, Terminate |
| Wallet | Create, Get, Get Many, Update, Terminate |
| Wallet Transaction | Create, Get Many |
| Webhook Endpoint | Create, Get, Get Many, Update, Delete |
The Lago Trigger node starts a workflow when Lago sends a billing event. It registers a
webhook endpoint in Lago when the workflow is activated, reusing an existing one for the same URL
rather than adding another, and removes it on deactivation. Every delivery is verified before the
workflow runs — with JWT by default, whose key is fetched automatically, or HMAC using the key
set on the credential. Lago retries a delivery up to three times, so repeats are recognised by
their delivery key and skipped.
Webhook endpoints register where Lago sends events. Event names are dotted
(invoice.created), not underscored as the OpenAPI specification shows them, and the node
offers the catalogue from the Lago version it targets so a selection cannot be rejected. An
organization may have at most ten endpoints.
Prepaid credit wallets distinguish paid credits from granted credits: granted credits
settle immediately, while paid credits are recorded as a pending transaction until the top-up
invoice is paid, so they do not appear in the balance straight away. One top-up request can
therefore return more than one transaction. Wallets are terminated, not deleted.
Automatic recurring and threshold top-ups are not exposed: Lago answers HTTP 500 on the free
edition rather than refusing cleanly, so offering the field would make the node look broken.
Credit note Create and Estimate require a Lago premium licence and are marked as such;
reading, downloading and voiding credit notes works on the free edition. Lago answers 403 for a
premium gate as well as for a rejected key, so the node distinguishes them and reports a licence
problem rather than sending you to check a working credential.
Invoices do not follow ordinary CRUD. A one-off invoice is issued already finalized, so
there is no draft to finalize afterwards; finalizing an invoice that is already finalized is
reported by Lago as not found. Voiding keeps the record with a voided status. Download
renders the PDF asynchronously, so file_url may still be empty on the first call. Invoice
refresh and draft invoices both require a Lago premium licence.
Usage events are the metering half of the integration. The Billable Metric Code is chosen
from the metrics defined in Lago rather than typed, because Lago accepts an event whose code
matches no active metric, stores it, and then never bills it — there is no error to notice.
Events are also aggregated asynchronously, so usage does not reflect a send immediately, and
Lago deduplicates on the transaction ID, which the node derives from the execution so an n8n
retry cannot double-bill.
Subscriptions are terminated, not deleted — the record is kept with a terminated status.
Note that Get Many returns only active subscriptions unless a status filter is set, and that a
terminated subscription reports as not found by Get while still appearing in Get Many. Sending
Create again with the same external ID and a different plan performs an upgrade or downgrade:
an upgrade replaces the subscription immediately, while a downgrade is queued as pending until
the period ends.
Plan charges price a billable metric on a plan, and every charge model — standard, package,
percentage, graduated, volume and dynamic — is offered as real fields rather than raw JSON.
Charge amounts are decimal strings ("0.01"), unlike plan amounts; Lago rejects a plain
number. Graduated Percentage requires a Lago premium licence.
Plan amounts are in the currency’s smallest unit — 10000 is 100.00, not 10000.00. Plan
deletion is processed asynchronously, so a deleted plan stays readable for a moment afterwards.
Billable metric expressions address event properties as event.properties. and the
event time as event.timestamp. The Evaluate Expression operation checks one against a
sample event, so a metering expression can be validated before any usage depends on it.
Customer has no update endpoint in the Lago API — POST /customers upserts on the external ID — so the node exposes a single Create or Update operation rather than implying semantics the API does not have.
The Lago Trigger node covers the full event catalogue — customers, subscriptions, invoices, payments, wallets, plans, billable metrics, credit notes, fees and alerts.
Credentials
You need a Lago API key. Either:
- Lago Cloud — sign up at getlago.com and copy the API key from your account settings, or
- Self-hosted — deploy Lago with Docker Compose or the official Helm charts, then take the API key from your instance.
The credential takes a Base URL and an API Key. Self-hosted instances are a first-class target: set the Base URL to your own instance instead of the default.
| Deployment | Base URL |
| ————— | —————————- |
| Lago Cloud (US) | https://api.getlago.com |
| Lago Cloud (EU) | https://api.eu.getlago.com |
| Self-hosted | your instance URL |
Lago authenticates with a bearer token, and the credential test verifies that the Base URL is reachable and the API key is accepted.
Webhook signatures
The Lago Trigger verifies every delivery before it starts a workflow. Lago signs webhooks with either JWT (RS256) or HMAC (SHA-256), chosen per webhook endpoint.
JWT is the default and needs no extra configuration: the node fetches Lago’s public key using the API key it already has. HMAC uses an organization-level key that the REST API does not expose, so you must copy it from the Lago dashboard into the credential yourself.
Compatibility
Requires n8n 1.x and Node.js 22.22.0 or later. Tested against the free self-hosted edition of Lago and Lago Cloud.
Some Lago functionality is premium-only, including per-subscription charge and fixed-charge overrides. The node does not require a premium license, and operations that depend on one are marked in the node UI.
Usage
Lago’s core loop is: define a billable metric, attach it to a plan as a charge, subscribe a customer to that plan, then send usage events as your product is consumed. Lago aggregates the events and generates invoices.
A typical usage-metering workflow sends one event per unit of consumption:
Your app -> n8n -> Lago: Event: Send
externalsubscriptionid: acme-prod
code: ai_tokens
properties: { tokens: 143217, model: example-model }
Event sending is idempotent on the transaction ID, and Lago deduplicates on it, so retries never double-bill. The node defaults the transaction ID from the n8n execution, which makes ordinary n8n retries safe without any configuration.
Resources
Troubleshooting
exact scoped package name was entered.
balance, generated PDF, or completed deletion.
Release provenance
Releases are published from the tag-only GitHub Actions workflow with npm provenance. The
repository tag, package version, packed contents, and official n8n source scan are checked before
publication; the published package is scanned again after registry propagation.
