Prepaid Credit API Implementation Guide

A prepaid credit API has two jobs: record what the customer bought, and show what remains after billable usage. Mixing those jobs is how a product ends up granting credits before payment succeeds or showing a balance that ignores usage still waiting for an invoice.

In Lago, a customer wallet holds credits. Your product sends usage events against billable metrics; Lago applies eligible wallet credits to subscription and progressive billing invoices. Your application remains responsible for deciding what happens when a balance runs low or reaches zero.

1. Decide what a credit is worth

Set the wallet currency and the value of one credit before designing the purchase flow. A $500 balance can be represented as 500 credits worth $1 each, but your commercial terms may use another conversion. State the conversion and expiry terms to customers. Lago supports paid credits and granted credits; keep them separate in your reporting because only paid credits represent an advance payment.

2. Create the wallet and fund it

Use the Lago API reference for POST /wallets and POST /wallet_transactions. Create a wallet for the Lago customer, then issue a wallet transaction for paid or granted credits. Purchased credits become available after the payment succeeds. Granted credits are available immediately. A paid top-up that fails payment must not be treated as usable credit.

Credits do not expire by default. If the contract sets an expiry date, configure it on the wallet or top-up rule and tell the customer what happens to unused credits. Lago can void the remainder on that date.

3. Meter usage once

Define a billable metric for the unit you sell, such as API calls, tokens, or compute minutes. Each event you send to POST /events needs the metric code, a subscription or customer reference, and a unique transaction_id so retries do not bill the same event twice. The event API reference shows the request shape. Test duplicate, late, and corrected events before you use the balance to make access decisions.

4. Show the right balance

The wallet balance reflects credits left after finalized invoices. Lago's premium ongoing balance also estimates the effect of current usage, taxes, and draft invoices; it refreshes every minute and when an invoice is finalized. If customers can consume quickly, a finalized-invoice balance alone is too late for a low-credit warning. The credits guide explains both balances and the available alert and top-up rules.

Use balance alerts to notify your product as thresholds are crossed. Lago can send a depletion webhook, but it does not block API calls or shut off a customer's service. Your application must enforce any hard limit, with a policy for in-flight requests and delayed events.

5. Reconcile credits with invoices

Credits apply to subscription and progressive billing invoices in the wallet's currency, after tax and credit notes. They do not apply to one-off invoices. Compare wallet purchases, grants, consumption, voids, and invoice deductions by customer and period. Keep the advance payment separate from recognized revenue in your finance system: purchasing credits does not itself mean the service has been delivered.

Start with one customer in a test environment. Purchase credits, send one usage event, repeat that event with the same transaction ID, trigger a threshold, fail a paid top-up, and finalize an invoice. If the customer-visible balance, wallet ledger, and invoice do not reconcile, fix that flow before scaling it.

For API details, see the Lago API reference. For the product behavior and limits, see Credits & Spend Control.