Billing SDK Guide for Developers 2026

A billing SDK should save you from writing HTTP plumbing, not hide how an invoice is calculated. Lago maintains clients for JavaScript, Python, Ruby, Go, PHP, and Kotlin. They call the billing API; payment collection remains a separate integration.

Use this sequence for a production integration: establish stable customer and subscription IDs, send reliable usage, handle billing webhooks, and reconcile a test invoice.

Choose a client and keep credentials server-side

Start at the Lago developer hub. Select the maintained client for your server language and configure the API key and base URL for your Lago deployment. Keep the key in server-side secret storage. Pin the client version so an upgrade is a deliberate change.

Establish stable identifiers

Create a Lago customer with an external_id that maps to your application customer. Create a subscription with an external subscription ID that your usage pipeline can carry. Store those IDs in your own system. A retry, migration, or support investigation should find the same billing objects.

Send one usage event

Configure a billable metric and a plan charge before testing. The Python client sends an event with the metric code, subscription ID, a unique transaction ID, a timestamp, and the properties used by the metric:

from lago_python_client.client import Client
from lago_python_client.models import Event

client = Client(api_key=LAGO_API_KEY)
client.events.create(Event(
    transaction_id=job_id,
    external_subscription_id=subscription_id,
    code="processed_jobs",
    timestamp=event_unix_time,
    properties={"jobs": 1},
))

Here job_id, subscription_id, event_unix_time, and LAGO_API_KEY come from your application. processed_jobs and jobs are illustrative; configure a matching metric before sending. The current usage event reference is the source for the exact payload and response.

Generate the transaction ID from the underlying business action, not from each delivery attempt. Reuse it when a worker retries. Record failed sends and replay them. Test duplicates, late events, and missing properties in staging. A successful API response alone does not prove the charge is correct.

Handle webhooks as retried messages

Use Lago webhooks for invoice and payment state changes. Verify the configured webhook signature before trusting the payload. Make processing idempotent, acknowledge promptly, and queue downstream work. Keep the Lago object ID and event record so finance can reconcile a change. The developer hub links to current webhook guidance.

Reconcile a complete billing path

In a test environment, create a customer, subscription, metric, plan charge, and usage event. Calculate the expected charge separately, then compare it with Lago's usage quantity and invoice line. Repeat with duplicate usage, a late event, a plan change, and a webhook retry. The SDK carries requests; your metric and price configuration determine the bill.

If Lago does not maintain a client for your language, use its OpenAPI contract or call the REST API directly. Review the API changes when you upgrade.