Usage-based API billing with Apache APISIX and Lago

Send the same request more than once with an identical transaction ID and confirm Lago counts it once. The lago plugin uses event_transaction_id to de-duplicate events, so the test is only meaningful if the ID is derived from something stable per request, such as a request ID header your gateway sets. Run the test with a known consumer and a known event code, then check the event list in Lago for that transaction ID. Also test the case where a client retries after a timeout, because that is the most common source of double counting in production. Confirm the exact de-duplication behavior and its window in your Lago version and with the plugin docs before you rely on it for invoices.

The lago plugin batches events and retries them, but batches are dropped permanently if Lago stays unreachable after retries. To test this, stop or block the Lago endpoint for a defined period while traffic runs through the gateway, then restore it. Afterward, compare the gateway request count for the window with the events Lago received. Any gap is usage that was not billed, and the plugin docs recommend pairing the plugin with another logging path so dropped batches can be recovered and reconciled. Confirm the retry count and timing in your deployed APISIX version, since those settings determine how much traffic a short outage can lose.

Reconcile per consumer and per billing period, not only in total. Count requests in your second log stream for each consumer over a fixed window, then count events in Lago for the same consumer and subscription over the same window. The two numbers should match except for requests you deliberately excluded, such as failed authentication or health checks, so define that filter before the test. Investigate every difference by transaction ID. Timezone boundaries and batches in flight at the cut-off are the usual causes of small mismatches, so align the window to UTC and allow for a flush interval at the edges.

Check that each event carries the expected event_code, a unique event_transaction_id, and an event_subscription_id that resolves to the right customer subscription. The subscription field can use variables such as the consumer name, so a naming mistake in consumers will send usage to the wrong subscription without any error. Test one consumer per subscription first, then several consumers at once, and verify that usage lands in the expected place each time. Record the mapping in a table so the reviewer can check it against the Lago customer records.

Review that each line item maps to a billable metric, that quantities match your reconciled event counts, and that the charge amounts follow the pricing you agreed. Check the billing period boundaries, the currency, and any tax or discount rules that apply to the test customers. Look at one invoice end to end and trace a few line items back to the gateway logs by transaction ID. Lago calculates what to charge and when, but payment collection runs through a separate payment processor, so also confirm that the invoice reaches the payment step as expected in your test environment.

Sign-off should come from the people who own each part of the chain: the platform team for gateway and plugin behavior, the finance or billing owner for pricing and invoices, and a reviewer independent of the build for reconciliation results. Written acceptance criteria help, for example a stated tolerance for the gap between gateway and Lago counts, a rule for how dropped batches are handled, and a list of invoice checks. Agree on these criteria before testing starts so that the result is a decision rather than a judgment made after the numbers are known.

Yes, if your team has the skills in gateway operations, the Lago API and finance reconciliation. The work is mostly careful setup and comparison, not complex code. The effort depends on how many consumers and plans you have, how much traffic the test needs to cover, and how much of the log pipeline already exists. Many teams underestimate the reconciliation step, so plan time for it separately. A partner can plan the test scope, run the failure scenarios and document the results in a fixed-scope engagement, with the scope agreed in writing before work begins.

Keep the test plan, the acceptance criteria, the raw gateway and Lago counts for each window, the list of duplicate and outage scenarios with their results, and the invoice samples you reviewed. Record the APISIX and Lago versions used, because behavior can change between releases, and keep the configuration of the lago plugin as deployed. This evidence helps finance answer disputes and gives auditors something concrete to examine. DeployOpen prepares systems, controls and evidence for compliance assessments, but independent auditors and certification bodies issue any audit reports or attestations.

The cost comes from three parts: the infrastructure you run for APISIX and Lago, the implementation work to map consumers, metrics and plans, and the payment processor fees Lago does not replace. Lago's FAQ states that businesses need a separate payment processor, since Lago calculates what to charge and when, then passes that to a gateway such as Stripe, Adyen or GoCardless. Effort rises with the number of billable metrics, plans and reconciliation rules. Ask any partner for a quote that lists one-time build work separately from recurring hosting, upgrades and support, and that names each payment provider in scope.

The duration depends mostly on your environment and your pricing model, not on the plugin configuration itself. Timing is driven by how many metrics and plan variants you bill, whether you connect an accounting system such as NetSuite, Xero, Salesforce or HubSpot, the access you get to your gateway and Lago environments, and how much testing you need against invoices before go-live. Lago's self-hosting docs also recommend pinning a tagged release, so you should plan an upgrade path early. Agree a timeline in writing only after the scope and the environment are documented.

You need to supply four things: administrative access to a self-hosted or Lago Cloud environment, your product catalog with billable metrics and plan rules, a defined consumer model that maps each API key or gateway consumer to a customer, and an owner for the payment provider account. You should also name the people who approve invoice logic and reconciliation rules. Without a clear consumer model, the event_subscription_id field cannot reliably point each request at the right subscription, so this is the item most worth settling first.

Yes, if your team has experience with both APISIX plugin configuration and billing data models. The work involves writing lago plugin settings for endpoint_addrs, token, event_code and event_transaction_id, deciding how consumer names are used as subscription identifiers, and designing reconciliation between gateway logs and Lago invoices. Teams without billing or finance engineering experience often underestimate the reconciliation design. A partner is useful when you want a fixed scope and written deliverables, or when your team cannot cover operations after go-live.

Lago's FAQ describes a forever-free open-source edition with fundamental billing features, and Enterprise plans that add premium features. Whether that edition covers you depends on which features you need beyond core metering, pricing and invoicing. Check the feature list against your plans, tax handling, dunning, reporting and integrations before you commit. The Lago platform is licensed under AGPLv3, so confirm with your legal team how that license applies to how you run and modify it.

The lago plugin sends events in batches of up to 100, flushes every 5 seconds or at 1,000 queued entries, and drops a batch permanently if Lago stays unreachable after retries. The plugin documentation recommends pairing it with other logging, so a usage record is never lost silently. A second stream, such as a Kafka, Loki or ClickHouse logger, gives you a durable copy to replay into Lago and to reconcile invoices against. Confirm the retry and backlog behavior of each logger with your team before you rely on it for revenue.

Check that your Lago version is pinned to a tagged release, since Lago's self-hosting docs recommend this rather than the latest image tag. Confirm the Docker Compose components are running as expected, including the API worker and clock worker, PostgreSQL, Redis and Gotenberg. If your event volume is high, ask whether ClickHouse is needed, because it is an optional external store and disabled by default. Also verify that test events produce the invoices you expect, with duplicate events blocked by event_transaction_id.