Customers
Customers in Velobase act as virtual accounts. They are tied to your own system’s users via acustomer_id — the unique identifier you assign.
You don’t need to manually create customers.
When you make an API call to deposit or deduct credits for a customer_id, Velobase will automatically create the customer profile if it doesn’t exist yet.
Wallet Categories and Expiry
Clicking on a customer reveals their complete balance details. A single customer can hold multiple Wallet Categories (known ascredit_type in the API).
| Wallet | Status | Expiry | Total | Available | Frozen |
|---|---|---|---|---|---|
default | ACTIVE | Never expires | 1,000 | 1,000 | 0 |
promo_campaign_2026 | ACTIVE | Dec 31, 2026 | 500 | 400 | 100 |
| Total | 1,500 | 1,400 | 100 |
- Expiring Credits: You can grant credits that are only valid until a certain date (e.g.,
promo_campaign_2026). Velobase automatically ignores expired wallets. - Consumption Priority: When you deduct credits without specifying a wallet, Velobase consumes the ones that expire soonest first, maximizing value for the user.
Ledger
The Ledger is the single source of truth for all balance changes. Every API call that modifies a balance results in an immutable Ledger record. Key concepts for tracking transactions:- Transaction ID: Every operation requires a unique
transaction_idfrom your system (oridempotency_keyfor deposits). This appears in the Ledger, allowing you to match a specific charge (e.g.,task_xyz) to the exact credits frozen and consumed. - Operation Types:
DEPOSIT: Credits added to an account.FREEZE: Credits reserved for an ongoing task.CONSUME: Credits permanently deducted (often following a freeze).UNFREEZE: Unused reserved credits returned to the available balance.