Managing Balances

Credit, debit, and manage customer wallet balances with transaction history and lot tracking

Manage customer wallet balances through the dashboard or API. Every balance change is tracked as a transaction with full audit history.

Credit Wallet (Add Funds)

Add funds to a customer's wallet in three ways:

From the Dashboard

Go to Customers and select a customer
Open the Wallet tab
Click Credit Wallet
Enter the amount, select the funding type, and add an optional description
Click Confirm

Via Wallet Code Redemption

Customers redeem wallet codes through the Customer Portal or at checkout. See Wallet Codes for details.

Via the API

POST /v2/wallet/customers/{customerId}/credit
Content-Type: application/json

{
  "amountCents": 5000,
  "currency": "GBP",
  "sourceType": "manual",
  "fundingType": "cash",
  "description": "Loyalty reward"
}

Response:

{
  "transactionId": "wt_abc123",
  "balanceCents": 7500,
  "lotId": "wl_def456"
}

Debit Wallet (Remove Funds)

Debit funds manually or automatically at checkout.

Manual Debit (Dashboard)

Open the customer's Wallet tab
Click Debit Wallet
Enter the amount and reason
Click Confirm

Manual Debit (API)

POST /v2/wallet/customers/{customerId}/debit
Content-Type: application/json

{
  "amountCents": 2000,
  "currency": "GBP",
  "sourceType": "manual",
  "description": "Correction"
}

Debits fail with a 422 error if the customer has insufficient balance.

Transaction History

Every wallet operation creates a transaction record. View the full history in the customer's Wallet tab or via the API.

Transaction Fields

Field	Description
type	`credit` or `debit`
amountCents	Amount in minor units
sourceType	Origin: `manual`, `checkout`, `code_redemption`, `refund`, `system`
fundingType	Balance category: `cash`, `promotional`, `code_redemption`, `refund`
description	Human-readable note
createdAt	Timestamp
lotId	Associated wallet lot (for credits)

Query via API

GET /v2/wallet/customers/{customerId}/transactions?limit=50&offset=0&type=credit

Wallet Lots

Credits are tracked as lots — individual balance entries with optional expiry dates. When a debit occurs, lots are consumed in FIFO order (oldest first).

Lot Fields

Field	Description
id	Unique lot identifier
originalAmountCents	Amount when created
remainingAmountCents	Current remaining balance
fundingType	Balance category
expiresAt	Optional expiry date (null = never expires)
status	`active`, `depleted`, `expired`

Expired lots are automatically marked by a daily cron job. The remaining balance of expired lots is forfeited.

Holds (Reservations)

Holds reserve wallet balance during checkout to prevent double-spending.

Hold Lifecycle

Create hold — Reserves amount from available balance
Capture hold — Converts hold to a debit (payment confirmed)
Release hold — Returns held amount to available balance (checkout abandoned)

Create Hold (API)

POST /v2/wallet/customers/{customerId}/hold

{
  "amountCents": 3000,
  "currency": "GBP",
  "reference": "inv_abc123"
}

Capture Hold

POST /v2/wallet/customers/{customerId}/hold/{holdId}/capture

Release Hold

POST /v2/wallet/customers/{customerId}/hold/{holdId}/release

Holds expire automatically after 30 minutes if neither captured nor released.

Wallets Overview — What wallets are and how they work
Wallet Codes — Redeemable credit codes
Checkout Integration — Wallet at checkout

Managing Balances

On this page