Wallets

Overview

Wallets provide a prepaid credit system for customers. Credits can be granted manually or automatically, and are consumed during invoice finalization to reduce the amount due.

Wallet properties

Field	Type	Description
id	uuid	Unique wallet identifier
customer_id	uuid	Customer this wallet belongs to
name	string	Display name
code	string	Optional unique code per customer
status	enum	active, terminated
balance_cents	string	Current balance in cents
credits_balance	string	Current balance in credits
consumed_amount_cents	string	Total consumed amount in cents
consumed_credits	string	Total consumed credits
rate_amount	string	Conversion rate: balance_cents = credits × rate_amount × 100. Default: 1.0 (1 credit = $1)
currency	string	ISO 4217 currency code
priority	integer	Consumption order (1–50, lower = consumed first)
expiration_at	datetime	Optional expiration date
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

Wallet lifecycle

  ACTIVE → TERMINATED

Active wallets accumulate and consume credits. Terminated wallets cannot process further transactions. Wallets can optionally expire at a set date.

Create a wallet

curl -X POST /v1/wallets \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "customer-uuid",
    "name": "Main Credits",
    "code": "main",
    "currency": "USD",
    "rate_amount": "1.0",
    "priority": 1,
    "initial_granted_credits": "100.00",
    "expiration_at": "2026-12-31T23:59:59Z"
  }'

Key fields

Field	Description
rate_amount	Conversion rate: balance_cents = credits × rate_amount × 100. Default: 1.0 (1 credit = $1)
priority	Consumption order (1–50, lower = consumed first)
initial_granted_credits	Credits to grant immediately on creation
expiration_at	Optional expiration date
code	Optional unique code per customer

Top up credits

curl -X POST /v1/wallets/{wallet_id}/top_up \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credits": "50.00",
    "source": "manual"
  }'

Sources

Source	Description
manual	Manually granted by admin
interval	Automatically granted on a recurring schedule
threshold	Granted when usage crosses a threshold

Each top-up creates an inbound wallet transaction and increases the wallet balance.

Transfer credits between wallets

Transfer credits from one wallet to another:

curl -X POST /v1/wallets/transfer \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_wallet_id": "source-wallet-uuid",
    "target_wallet_id": "target-wallet-uuid",
    "credits": "25.00"
  }'

The response returns updated source_wallet and target_wallet objects along with credits_transferred.

Credit consumption

When an invoice is finalized, wallet credits are consumed automatically:

1. Active, non-expired wallets are sorted by priority (ascending), then by creation date
2. For each wallet, the consumable amount is min(wallet.balance, remaining_invoice_amount)
3. An outbound wallet transaction is created
4. An InvoiceSettlement record links the consumption to the invoice
5. The process continues until the invoice is fully covered or no wallets remain

Example

A customer has two wallets:

Wallet	Priority	Balance
Promo Credits	1	$25.00
Main Credits	2	$100.00

For a $40.00 invoice:

1. Promo Credits consumed: $25.00 (balance → $0.00)
2. Main Credits consumed: $15.00 (balance → $85.00)
3. Invoice prepaid_credit_amount: $40.00

Terminate a wallet

DELETE /v1/wallets/{wallet_id}

Sets the wallet status to terminated. Remaining balance is forfeited.

Expiration

Wallets with an expiration_at date are automatically terminated by a background task when the expiration date passes. The check_expired_wallets task handles this.

Wallet transactions

List all transactions for a wallet:

curl /v1/wallets/{wallet_id}/transactions \
  -H "Authorization: Bearer $API_KEY"

Transaction fields

Field	Type	Description
id	uuid	Transaction identifier
wallet_id	uuid	Parent wallet
customer_id	uuid	Customer identifier
transaction_type	string	inbound (credit) or outbound (debit)
transaction_status	string	Transaction status
source	string	manual, interval, or threshold
status	string	Current status
amount	string	Amount in currency
credit_amount	string	Amount in credits
invoice_id	uuid	Linked invoice (if outbound)
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

Transaction types

Type	Direction	Description
inbound	Credit	Top-up or grant
outbound	Debit	Consumption against invoice

Transaction statuses

Status	Description
granted	Credits granted
purchased	Credits purchased
voided	Transaction voided
invoiced	Linked to an invoice

Balance timeline

Get a daily breakdown of credits in and out over a date range:

curl "/v1/wallets/{wallet_id}/balance_timeline?start_date=2026-01-01&end_date=2026-01-31" \
  -H "Authorization: Bearer $API_KEY"

Each point in the response contains:

Field	Description
date	Calendar date
inbound	Total credits added on this date
outbound	Total credits consumed on this date
balance	End-of-day balance

Depletion forecast

Get a projected depletion date based on recent consumption rate:

curl "/v1/wallets/{wallet_id}/depletion_forecast?days=30" \
  -H "Authorization: Bearer $API_KEY"

The days parameter controls how many days of historical consumption to use for the projection.

Response fields

Field	Description
wallet_id	Wallet identifier
current_balance_cents	Current balance
avg_daily_consumption	Average daily consumption over the lookback period
projected_depletion_date	Estimated date the wallet will reach zero (null if no consumption)
days_remaining	Estimated days until depletion (null if no consumption)

Customer portal endpoints

Wallets are also accessible via the customer portal API:

Method	Path	Description
GET	/portal/wallet	Get wallet balance and transactions
GET	/portal/wallet/{wallet_id}/balance_timeline	Get wallet balance timeline
POST	/portal/wallet/{wallet_id}/top_up	Request a wallet top-up
GET	/portal/wallet/{wallet_id}/transactions	List wallet transactions

API endpoints

Method	Path	Description
POST	/v1/wallets	Create a wallet
GET	/v1/wallets	List wallets
GET	/v1/wallets/{id}	Get wallet details
PUT	/v1/wallets/{id}	Update wallet (name, expiration, priority)
DELETE	/v1/wallets/{id}	Terminate a wallet
POST	/v1/wallets/{id}/top_up	Add credits
POST	/v1/wallets/transfer	Transfer credits between wallets
GET	/v1/wallets/{id}/transactions	List transactions
GET	/v1/wallets/{id}/balance_timeline	Get daily balance timeline
GET	/v1/wallets/{id}/depletion_forecast	Get projected depletion date