---
title: "Prepaid Credit API Implementation Guide"
url: https://getlago.com/blog/prepaid-credit-api-implementation-guide
description: "Build prepaid credits with Lago wallets, top-ups, usage events, balance alerts, and invoice reconciliation. Includes payment and expiry rules."
authors: ["Anh-Tho Chuong"]
tags: ["Engineering"]
published: 2026-03-30
updated: 2026-10-17
reading_time_minutes: 2
---

# 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](https://swagger.getlago.com/) 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](https://getlago.com/docs/api-reference/events/usage) 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](https://getlago.com/platform/credits) 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](https://swagger.getlago.com/). For the product behavior and limits, see [Credits & Spend Control](https://getlago.com/platform/credits).