diff --git a/app/screens/CreditBalanceScreen.tsx b/app/screens/CreditBalanceScreen.tsx
index 6e96b01c..02bc3145 100644
--- a/app/screens/CreditBalanceScreen.tsx
+++ b/app/screens/CreditBalanceScreen.tsx
@@ -1,61 +1,305 @@
-import React, { useState } from 'react';
-import { View, Text, TextInput, Button, FlatList, StyleSheet } from 'react-native';
-import { useCreditStore, CreditTransaction } from '../stores/creditStore';
+import React, { useMemo, useState } from 'react';
+import {
+  View,
+  Text,
+  TextInput,
+  StyleSheet,
+  FlatList,
+  ScrollView,
+  Pressable,
+  Alert,
+} from 'react-native';
+import { useCreditStore, type AccountCredit, type CreditLot } from '../stores/creditStore';
+
+type Tab = 'balance' | 'analytics' | 'history' | 'wallets';
+
+const colorScheme = {
+  bg: '#f7fafc',
+  card: '#ffffff',
+  border: '#e2e8f0',
+  primary: '#1d4ed8',
+  credit: '#15803d',
+  debit: '#b91c1c',
+  warning: '#c2410c',
+  text: '#0f172a',
+  textMuted: '#475569',
+};
+
+const currency = (n: number): string => n.toLocaleString(undefined, { minimumFractionDigits: 0 });
 
 const styles = StyleSheet.create({
-  container: { flex: 1, padding: 16 },
-  header: { fontSize: 18, fontWeight: '700', marginVertical: 8 },
-  balance: { fontSize: 32, fontWeight: '800', color: '#15803d' },
-  label: { fontSize: 12, color: '#666', marginTop: 8 },
-  input: { height: 40, borderColor: '#ccc', borderWidth: 1, paddingHorizontal: 8, borderRadius: 4, marginTop: 4 },
-  row: { flexDirection: 'row', gap: 8, marginTop: 8 },
-  item: { paddingVertical: 6, borderBottomWidth: 1, borderColor: '#eee' },
-  credit: { color: '#15803d' },
-  debit: { color: '#b91c1c' },
+  container: { flex: 1, backgroundColor: colorScheme.bg },
+  scrollContent: { padding: 16, gap: 12 },
+  heroCard: {
+    backgroundColor: colorScheme.card,
+    borderRadius: 12,
+    padding: 20,
+    borderWidth: 1,
+    borderColor: colorScheme.border,
+  },
+  heroLabel: { color: colorScheme.textMuted, fontSize: 12, textTransform: 'uppercase', letterSpacing: 1 },
+  heroBalance: { color: colorScheme.text, fontSize: 36, fontWeight: '800', marginTop: 4 },
+  heroSub: { color: colorScheme.textMuted, fontSize: 13, marginTop: 6 },
+  tabRow: { flexDirection: 'row', gap: 8, marginBottom: 8 },
+  tab: {
+    flex: 1,
+    paddingVertical: 10,
+    paddingHorizontal: 12,
+    backgroundColor: colorScheme.card,
+    borderRadius: 8,
+    borderWidth: 1,
+    borderColor: colorScheme.border,
+    alignItems: 'center',
+  },
+  tabActive: { backgroundColor: colorScheme.primary, borderColor: colorScheme.primary },
+  tabLabel: { color: colorScheme.text, fontWeight: '600' },
+  tabLabelActive: { color: '#fff' },
+  card: {
+    backgroundColor: colorScheme.card,
+    borderRadius: 12,
+    padding: 16,
+    borderWidth: 1,
+    borderColor: colorScheme.border,
+    gap: 12,
+  },
+  cardTitle: { fontWeight: '700', fontSize: 16, color: colorScheme.text },
+  cardSubtitle: { color: colorScheme.textMuted, fontSize: 12 },
+  row: { flexDirection: 'row', gap: 8 },
+  input: {
+    flex: 1,
+    borderColor: colorScheme.border,
+    borderWidth: 1,
+    borderRadius: 8,
+    paddingHorizontal: 10,
+    paddingVertical: 8,
+    color: colorScheme.text,
+    backgroundColor: '#fff',
+  },
+  button: {
+    paddingHorizontal: 14,
+    paddingVertical: 10,
+    backgroundColor: colorScheme.primary,
+    borderRadius: 8,
+    alignItems: 'center',
+  },
+  buttonLabel: { color: '#fff', fontWeight: '600' },
+  buttonGhost: {
+    paddingHorizontal: 14,
+    paddingVertical: 10,
+    backgroundColor: '#fff',
+    borderWidth: 1,
+    borderColor: colorScheme.border,
+    borderRadius: 8,
+    alignItems: 'center',
+  },
+  buttonGhostLabel: { color: colorScheme.text, fontWeight: '600' },
+  itemRow: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    paddingVertical: 8,
+    borderBottomWidth: 1,
+    borderColor: colorScheme.border,
+  },
+  itemAmount: { fontWeight: '600' },
+  credit: { color: colorScheme.credit },
+  debit: { color: colorScheme.debit },
+  muted: { color: colorScheme.textMuted },
+  expiryPill: {
+    paddingHorizontal: 10,
+    paddingVertical: 4,
+    borderRadius: 12,
+    alignSelf: 'flex-start',
+  },
+  statGrid: { flexDirection: 'row', flexWrap: 'wrap', gap: 8 },
+  statTile: {
+    flexBasis: '48%',
+    backgroundColor: '#fff',
+    borderRadius: 8,
+    borderWidth: 1,
+    borderColor: colorScheme.border,
+    padding: 12,
+  },
+  statLabel: { color: colorScheme.textMuted, fontSize: 12 },
+  statValue: { color: colorScheme.text, fontSize: 18, fontWeight: '700', marginTop: 2 },
+  chartBar: {
+    height: 8,
+    backgroundColor: '#e2e8f0',
+    borderRadius: 4,
+    overflow: 'hidden',
+  },
+  chartFill: {
+    height: '100%',
+    backgroundColor: colorScheme.primary,
+  },
 });
 
-const sign = (tx: CreditTransaction) => (tx.amount >= 0 ? styles.credit : styles.debit);
+const BucketBar: React.FC<{ label: string; value: number; total: number; tone?: 'pos' | 'neg' | 'mute' }> = ({
+  label,
+  value,
+  total,
+  tone = 'pos',
+}) => {
+  const pct = total > 0 ? Math.min(100, Math.round((value / total) * 100)) : 0;
+  const fill =
+    tone === 'neg' ? colorScheme.debit : tone === 'mute' ? colorScheme.textMuted : colorScheme.primary;
+  return (
+    <View style={{ gap: 4 }}>
+      <View style={{ flexDirection: 'row', justifyContent: 'space-between' }}>
+        <Text style={styles.muted}>{label}</Text>
+        <Text style={styles.muted}>{currency(value)}</Text>
+      </View>
+      <View style={styles.chartBar}>
+        <View style={[styles.chartFill, { width: `${pct}%`, backgroundColor: fill }]} />
+      </View>
+    </View>
+  );
+};
 
-export const CreditBalanceScreen: React.FC<{ subscriber?: string }> = ({ subscriber = 'me' }) => {
-  const { issueCredit, applyCredit, expireCredits, getBalance, getAccount } = useCreditStore();
-  const [amount, setAmount] = useState('100');
-  const [due, setDue] = useState('50');
-  // Read from store on each render so issuing/applying refreshes the figures.
-  const balance = useCreditStore((s) => s.accounts[subscriber]?.balance ?? 0);
-  void balance; // stored balance; available balance shown below accounts for expiry
+const AnalyticsPanel: React.FC<{ account: AccountCredit }> = ({ account }) => {
+  const issued = useMemo(
+    () =>
+      account.transactions
+        .filter((t) => t.kind === 'issue')
+        .reduce((s, t) => s + t.amount, 0),
+    [account.transactions]
+  );
+  const applied = useMemo(
+    () =>
+      account.transactions
+        .filter((t) => t.kind === 'apply')
+        .reduce((s, t) => s + Math.abs(t.amount), 0),
+    [account.transactions]
+  );
+  const transferIn = useMemo(
+    () =>
+      account.transactions
+        .filter((t) => t.kind === 'transfer_in')
+        .reduce((s, t) => s + t.amount, 0),
+    [account.transactions]
+  );
+  const transferOut = useMemo(
+    () =>
+      account.transactions
+        .filter((t) => t.kind === 'transfer_out')
+        .reduce((s, t) => s + Math.abs(t.amount), 0),
+    [account.transactions]
+  );
+  const expired = useMemo(
+    () =>
+      account.transactions
+        .filter((t) => t.kind === 'expire')
+        .reduce((s, t) => s + Math.abs(t.amount), 0),
+    [account.transactions]
+  );
 
-  const available = getBalance(subscriber);
-  const account = getAccount(subscriber);
+  const consumptionRate = issued > 0 ? Math.round((applied / issued) * 100) : 0;
+  const channelTotal = issued + transferIn;
+
+  const expiryBuckets = useMemo(() => {
+    const nowSec = Math.floor(Date.now() / 1000);
+    const buckets = { within_7d: 0, within_30d: 0, beyond_30d: 0, no_expiry: 0 };
+    for (const lot of account.lots) {
+      if (lot.remaining <= 0) continue;
+      if (!lot.expiresAt) {
+        buckets.no_expiry += lot.remaining;
+        continue;
+      }
+      const secToExpiry = lot.expiresAt - nowSec;
+      if (secToExpiry <= 7 * 86_400) buckets.within_7d += lot.remaining;
+      else if (secToExpiry <= 30 * 86_400) buckets.within_30d += lot.remaining;
+      else buckets.beyond_30d += lot.remaining;
+    }
+    return buckets;
+  }, [account.lots]);
 
   return (
-    <View style={styles.container}>
-      <Text style={styles.header}>Account Credit</Text>
-      <Text style={styles.balance}>{available.toLocaleString()}</Text>
-      <Text style={styles.label}>Available credit (excludes expired)</Text>
-
-      <Text style={styles.label}>Issue credit</Text>
-      <TextInput style={styles.input} keyboardType="numeric" value={amount} onChangeText={setAmount} />
-      <Button
-        title="Issue Credit"
-        onPress={() => issueCredit(subscriber, Number(amount) || 0, 'manual_grant')}
-      />
+    <View style={styles.card}>
+      <Text style={styles.cardTitle}>Credit analytics</Text>
+      <Text style={styles.cardSubtitle}>Roll-up of lifetime issuance, application and expiry</Text>
 
-      <Text style={styles.label}>Apply credit to a charge</Text>
-      <TextInput style={styles.input} keyboardType="numeric" value={due} onChangeText={setDue} />
-      <View style={styles.row}>
-        <Button title="Apply" onPress={() => applyCredit(subscriber, 'sub_1', Number(due) || 0)} />
-        <Button title="Expire now" onPress={() => expireCredits(subscriber)} />
+      <View style={styles.statGrid}>
+        <View style={styles.statTile}>
+          <Text style={styles.statLabel}>Consumption rate</Text>
+          <Text style={styles.statValue}>{consumptionRate}%</Text>
+        </View>
+        <View style={styles.statTile}>
+          <Text style={styles.statLabel}>Outstanding lots</Text>
+          <Text style={styles.statValue}>{account.lots.filter((l) => l.remaining > 0).length}</Text>
+        </View>
+        <View style={styles.statTile}>
+          <Text style={styles.statLabel}>Outstanding balance</Text>
+          <Text style={styles.statValue}>{currency(account.balance)}</Text>
+        </View>
+        <View style={styles.statTile}>
+          <Text style={styles.statLabel}>Available (unexpired)</Text>
+          <Text style={[styles.statValue, { color: colorScheme.credit }]}>
+            {currency(account.lots.reduce((s, l) => s + l.remaining, 0))}
+          </Text>
+        </View>
       </View>
 
-      <Text style={styles.header}>History</Text>
+      <View style={{ gap: 8 }}>
+        <Text style={styles.cardTitle}>Channel mix</Text>
+        <BucketBar label="Issuance" value={issued} total={channelTotal} />
+        <BucketBar label="Transfers in" value={transferIn} total={channelTotal} />
+      </View>
+
+      <View style={{ gap: 8 }}>
+        <Text style={styles.cardTitle}>Ledger flow</Text>
+        <BucketBar label="Applied" value={applied} total={issued + transferIn || 1} tone="pos" />
+        <BucketBar label="Transferred out" value={transferOut} total={issued + transferIn || 1} tone="mute" />
+        <BucketBar label="Expired" value={expired} total={issued + transferIn || 1} tone="neg" />
+      </View>
+
+      <View style={{ gap: 8 }}>
+        <Text style={styles.cardTitle}>Expiry forecast (outstanding lots)</Text>
+        <BucketBar
+          label="Within 7 days"
+          value={expiryBuckets.within_7d}
+          total={Math.max(1, expiryBuckets.within_7d + expiryBuckets.within_30d + expiryBuckets.beyond_30d + expiryBuckets.no_expiry)}
+          tone="neg"
+        />
+        <BucketBar label="Within 30 days" value={expiryBuckets.within_30d} total={Math.max(1, expiryBuckets.within_7d + expiryBuckets.within_30d + expiryBuckets.beyond_30d + expiryBuckets.no_expiry)} tone="mute" />
+        <BucketBar label="Beyond 30 days" value={expiryBuckets.beyond_30d} total={Math.max(1, expiryBuckets.within_7d + expiryBuckets.within_30d + expiryBuckets.beyond_30d + expiryBuckets.no_expiry)} />
+        <BucketBar label="Never expires" value={expiryBuckets.no_expiry} total={Math.max(1, expiryBuckets.within_7d + expiryBuckets.within_30d + expiryBuckets.beyond_30d + expiryBuckets.no_expiry)} />
+      </View>
+    </View>
+  );
+};
+
+const HistoryPanel: React.FC<{ account: AccountCredit }> = ({ account }) => {
+  const entries = useMemo(
+    () => [...account.transactions].sort((a, b) => b.timestamp - a.timestamp),
+    [account.transactions]
+  );
+  if (entries.length === 0) {
+    return (
+      <View style={styles.card}>
+        <Text style={styles.cardTitle}>Transaction history</Text>
+        <Text style={styles.muted}>No credit activity yet.</Text>
+      </View>
+    );
+  }
+  return (
+    <View style={styles.card}>
+      <Text style={styles.cardTitle}>Transaction history</Text>
+      <Text style={styles.cardSubtitle}>Full audit trail — every issuance, application, transfer and expiry</Text>
       <FlatList
-        data={[...account.transactions].reverse()}
+        scrollEnabled={false}
+        data={entries}
         keyExtractor={(t) => String(t.id)}
         renderItem={({ item }) => (
-          <View style={styles.item}>
-            <Text style={sign(item)}>
-              {item.kind} {item.amount >= 0 ? '+' : ''}
-              {item.amount} · {item.reason}
+          <View style={styles.itemRow}>
+            <View style={{ flex: 1 }}>
+              <Text style={styles.muted}>{item.reason}</Text>
+              <Text style={styles.muted}>
+                {new Date(item.timestamp * 1000).toLocaleString()} ·{' '}
+                <Text style={styles[item.amount >= 0 ? 'credit' : 'debit']}>{item.kind}</Text>
+              </Text>
+            </View>
+            <Text style={[styles.itemAmount, item.amount >= 0 ? styles.credit : styles.debit]}>
+              {item.amount >= 0 ? '+' : ''}
+              {currency(item.amount)}
             </Text>
           </View>
         )}
@@ -64,4 +308,229 @@ export const CreditBalanceScreen: React.FC<{ subscriber?: string }> = ({ subscri
   );
 };
 
+const LotsPanel: React.FC<{ lots: CreditLot[] }> = ({ lots }) => {
+  if (lots.length === 0) {
+    return (
+      <View style={styles.card}>
+        <Text style={styles.cardTitle}>Credit lots</Text>
+        <Text style={styles.muted}>No credit lots yet.</Text>
+      </View>
+    );
+  }
+  return (
+    <View style={styles.card}>
+      <Text style={styles.cardTitle}>Credit lots</Text>
+      <Text style={styles.cardSubtitle}>Each lot is consumed oldest-first</Text>
+      {lots.map((lot) => {
+        const issuedAt = new Date(lot.issuedAt * 1000).toLocaleDateString();
+        const expiresAt = lot.expiresAt ? new Date(lot.expiresAt * 1000).toLocaleDateString() : '—';
+        const expired = lot.expiresAt !== undefined && lot.expiresAt * 1000 <= Date.now();
+        return (
+          <View key={lot.id} style={styles.itemRow}>
+            <View style={{ flex: 1 }}>
+              <Text style={{ color: colorScheme.text, fontWeight: '600' }}>Lot #{lot.id}</Text>
+              <Text style={styles.muted}>Issued {issuedAt} · Expires {expiresAt}</Text>
+              <View style={[styles.expiryPill, { backgroundColor: expired ? '#fee2e2' : '#ecfdf5' }]}>
+                <Text style={{ color: expired ? colorScheme.debit : colorScheme.credit, fontWeight: '600' }}>
+                  {expired ? 'expired' : 'active'}
+                </Text>
+              </View>
+            </View>
+            <Text style={styles.itemAmount}>{currency(lot.remaining)}</Text>
+          </View>
+        );
+      })}
+    </View>
+  );
+};
+
+export interface CreditBalanceScreenProps {
+  subscriber?: string;
+  /** Pre-supplied analytics callbacks so the screen stays backend-agnostic. */
+  onExportReport?: (format: 'csv' | 'json') => void;
+}
+
+export const CreditBalanceScreen: React.FC<CreditBalanceScreenProps> = ({
+  subscriber = 'me',
+  onExportReport,
+}) => {
+  const {
+    issueCredit,
+    setExpirationPolicy,
+    applyCredit,
+    transferCredit,
+    expireCredits,
+    getAccount,
+    getBalance,
+  } = useCreditStore();
+  const account = getAccount(subscriber);
+  const available = getBalance(subscriber);
+
+  const [tab, setTab] = useState<Tab>('balance');
+  const [amount, setAmount] = useState('100');
+  const [due, setDue] = useState('50');
+  const [recipient, setRecipient] = useState('bob');
+  const [policyDays, setPolicyDays] = useState('30');
+
+  const onIssue = () => {
+    const v = Number(amount) || 0;
+    if (v <= 0) {
+      Alert.alert('Enter a positive amount');
+      return;
+    }
+    issueCredit(subscriber, v, 'manual_grant');
+  };
+
+  const onApply = () => {
+    const v = Number(due) || 0;
+    if (v < 0) return;
+    applyCredit(subscriber, 'sub_1', v);
+  };
+
+  const onTransfer = () => {
+    const v = Number(amount) || 0;
+    const to = recipient.trim();
+    if (v <= 0 || !to) {
+      Alert.alert('Enter a recipient and a positive amount');
+      return;
+    }
+    const ok = transferCredit(subscriber, to, v, 'gift');
+    if (!ok) Alert.alert('Transfer failed — insufficient balance');
+  };
+
+  const onExpire = () => {
+    const expired = expireCredits(subscriber);
+    Alert.alert('Expire', `Expired ${currency(expired)} of credit`);
+  };
+
+  const onSetPolicy = () => {
+    const days = Number(policyDays) || 0;
+    if (days <= 0) return;
+    setExpirationPolicy(subscriber, { kind: 'after_secs', seconds: days * 86_400 });
+    Alert.alert('Policy updated', `New credit will expire in ${days} days`);
+  };
+
+  const tabs: Array<{ key: Tab; label: string }> = [
+    { key: 'balance', label: 'Balance' },
+    { key: 'analytics', label: 'Analytics' },
+    { key: 'history', label: 'History' },
+    { key: 'wallets', label: 'Lots' },
+  ];
+
+  return (
+    <ScrollView style={styles.container} contentContainerStyle={styles.scrollContent}>
+      <View style={styles.heroCard}>
+        <Text style={styles.heroLabel}>Account credit</Text>
+        <Text style={styles.heroBalance}>{currency(available)}</Text>
+        <Text style={styles.heroSub}>
+          Available · {currency(account.balance)} lifetime · {account.transactions.length} ledger entries
+        </Text>
+      </View>
+
+      {onExportReport ? (
+        <View style={styles.row}>
+          <Pressable style={styles.buttonGhost} onPress={() => onExportReport('csv')}>
+            <Text style={styles.buttonGhostLabel}>Export CSV</Text>
+          </Pressable>
+          <Pressable style={styles.buttonGhost} onPress={() => onExportReport('json')}>
+            <Text style={styles.buttonGhostLabel}>Export JSON</Text>
+          </Pressable>
+        </View>
+      ) : null}
+
+      <View style={styles.tabRow}>
+        {tabs.map((t) => (
+          <Pressable
+            key={t.key}
+            style={[styles.tab, tab === t.key && styles.tabActive]}
+            onPress={() => setTab(t.key)}
+            accessibilityRole="button"
+            accessibilityState={{ selected: tab === t.key }}>
+            <Text style={[styles.tabLabel, tab === t.key && styles.tabLabelActive]}>{t.label}</Text>
+          </Pressable>
+        ))}
+      </View>
+
+      {tab === 'balance' ? (
+        <>
+          <View style={styles.card}>
+            <Text style={styles.cardTitle}>Issue credit</Text>
+            <View style={styles.row}>
+              <TextInput
+                style={styles.input}
+                keyboardType="numeric"
+                value={amount}
+                onChangeText={setAmount}
+              />
+              <Pressable style={styles.button} onPress={onIssue}>
+                <Text style={styles.buttonLabel}>Issue</Text>
+              </Pressable>
+            </View>
+          </View>
+          <View style={styles.card}>
+            <Text style={styles.cardTitle}>Apply to a charge</Text>
+            <View style={styles.row}>
+              <TextInput
+                style={styles.input}
+                keyboardType="numeric"
+                value={due}
+                onChangeText={setDue}
+              />
+              <Pressable style={styles.button} onPress={onApply}>
+                <Text style={styles.buttonLabel}>Apply</Text>
+              </Pressable>
+            </View>
+          </View>
+          <View style={styles.card}>
+            <Text style={styles.cardTitle}>Transfer to another account</Text>
+            <View style={styles.row}>
+              <TextInput
+                style={styles.input}
+                placeholder="Recipient"
+                value={recipient}
+                onChangeText={setRecipient}
+              />
+            </View>
+            <View style={styles.row}>
+              <TextInput
+                style={[styles.input, { flex: 1 }]}
+                keyboardType="numeric"
+                value={amount}
+                onChangeText={setAmount}
+              />
+              <Pressable style={styles.button} onPress={onTransfer}>
+                <Text style={styles.buttonLabel}>Transfer</Text>
+              </Pressable>
+            </View>
+          </View>
+          <View style={styles.card}>
+            <Text style={styles.cardTitle}>Expiration policy</Text>
+            <Text style={styles.cardSubtitle}>
+              New lots will auto-expire after this many days
+            </Text>
+            <View style={styles.row}>
+              <TextInput
+                style={styles.input}
+                keyboardType="numeric"
+                value={policyDays}
+                onChangeText={setPolicyDays}
+              />
+              <Pressable style={styles.button} onPress={onSetPolicy}>
+                <Text style={styles.buttonLabel}>Save</Text>
+              </Pressable>
+            </View>
+            <Pressable style={styles.buttonGhost} onPress={onExpire}>
+              <Text style={styles.buttonGhostLabel}>Run expiry now</Text>
+            </Pressable>
+          </View>
+        </>
+      ) : null}
+
+      {tab === 'analytics' ? <AnalyticsPanel account={account} /> : null}
+      {tab === 'history' ? <HistoryPanel account={account} /> : null}
+      {tab === 'wallets' ? <LotsPanel lots={account.lots} /> : null}
+    </ScrollView>
+  );
+};
+
 export default CreditBalanceScreen;
diff --git a/app/stores/analyticsStore.ts b/app/stores/analyticsStore.ts
index 8b246b5f..79ed5109 100644
--- a/app/stores/analyticsStore.ts
+++ b/app/stores/analyticsStore.ts
@@ -18,6 +18,7 @@ import type {
   SubscriberRecord,
   AnomalyFlaggedPoint,
 } from '../../src/types/cohortAnalytics';
+import { useCreditStore } from './creditStore';
 
 const DAY_MS = 24 * 60 * 60 * 1_000;
 
@@ -49,6 +50,21 @@ const toSubscriberRecords = (subscriptions: Subscription[]): SubscriberRecord[]
           : subscription.price,
   }));
 
+interface CreditMetricSnapshot {
+  outstandingBalance: number;
+  outstandingLots: number;
+  lifetimeIssued: number;
+  lifetimeApplied: number;
+  lifetimeExpired: number;
+  lifetimeTransferredIn: number;
+  lifetimeTransferredOut: number;
+  /** 0-100 integer; issuance-to-application conversion. */
+  consumptionRate: number;
+  /** Lots expiring within 7 / 30 days. */
+  expiringWithin7d: number;
+  expiringWithin30d: number;
+}
+
 interface AnalyticsStoreState {
   report: SubscriptionAnalyticsReport | null;
   granularity: CohortGranularity;
@@ -61,6 +77,7 @@ interface AnalyticsStoreState {
   planMigrationFlows: PlanMigrationFlow[];
   ltvBySource: LtvSourceBreakdown[];
   revenueTrendWithAnomalies: AnomalyFlaggedPoint[];
+  creditSnapshot: CreditMetricSnapshot | null;
   setGranularity: (granularity: CohortGranularity) => void;
   setForecastModel: (model: 'linear' | 'exponential') => void;
   toggleWidget: (widgetId: string) => void;
@@ -86,6 +103,7 @@ export const useAnalyticsStore = create<AnalyticsStoreState>()((set, get) => ({
   planMigrationFlows: [],
   ltvBySource: [],
   revenueTrendWithAnomalies: [],
+  creditSnapshot: null,
 
   setGranularity: (granularity) => {
     set({ granularity });
@@ -130,6 +148,7 @@ export const useAnalyticsStore = create<AnalyticsStoreState>()((set, get) => ({
       revenueTrendWithAnomalies: CohortService.filterAnomalousSpikes(
         report.revenueTrend.map((point) => ({ label: point.label, value: point.mrr }))
       ),
+      creditSnapshot: computeCreditSnapshot(),
     });
   },
 
@@ -187,3 +206,5 @@ export const useAnalyticsStore = create<AnalyticsStoreState>()((set, get) => ({
     ].join('\n');
   },
 }));
+
+export type { CreditMetricSnapshot };
diff --git a/app/stores/creditStore.ts b/app/stores/creditStore.ts
index 81a2484f..4f877990 100644
--- a/app/stores/creditStore.ts
+++ b/app/stores/creditStore.ts
@@ -50,7 +50,10 @@ const isExpired = (lot: CreditLot, now: number): boolean =>
   lot.expiresAt !== undefined && lot.expiresAt <= now;
 
 const availableOf = (account: AccountCredit, now: number): number =>
-  account.lots.reduce((sum, lot) => (lot.remaining > 0 && !isExpired(lot, now) ? sum + lot.remaining : sum), 0);
+  account.lots.reduce(
+    (sum, lot) => (lot.remaining > 0 && !isExpired(lot, now) ? sum + lot.remaining : sum),
+    0
+  );
 
 interface CreditStoreState {
   accounts: Record<string, AccountCredit>;
@@ -80,8 +83,9 @@ export const useCreditStore = create<CreditStoreState>()(
       const account = (subscriber: string): AccountCredit =>
         get().accounts[subscriber] ?? blankAccount(subscriber);
 
-      const commit = (acc: AccountCredit) =>
+      const commit = (acc: AccountCredit): void => {
         set((s) => ({ accounts: { ...s.accounts, [acc.subscriber]: acc } }));
+      };
 
       const nextId = (): number => {
         const id = get().nextId;
@@ -94,15 +98,15 @@ export const useCreditStore = create<CreditStoreState>()(
         kind: CreditTxKind,
         amount: number,
         reason: string,
-        counterparty?: string,
-      ) => {
+        counterparty?: string
+      ): void => {
         acc.transactions = [
           ...acc.transactions,
           { id: nextId(), kind, amount, timestamp: get().now(), reason, counterparty },
         ];
       };
 
-      const realizeExpiry = (acc: AccountCredit, now: number) => {
+      const realizeExpiry = (acc: AccountCredit, now: number): number => {
         let expired = 0;
         acc.lots = acc.lots.map((lot) => {
           if (lot.remaining > 0 && isExpired(lot, now)) {
@@ -129,6 +133,12 @@ export const useCreditStore = create<CreditStoreState>()(
         return amount - remaining;
       };
 
+      const cloneAccount = (acc: AccountCredit): AccountCredit => ({
+        ...acc,
+        lots: [...acc.lots],
+        transactions: [...acc.transactions],
+      });
+
       return {
         accounts: {},
         nextId: 0,
@@ -137,13 +147,13 @@ export const useCreditStore = create<CreditStoreState>()(
         issueCredit: (subscriber, amount, reason, expiresAt) => {
           if (amount <= 0) return;
           const now = get().now();
-          const acc = { ...account(subscriber) };
-          acc.lots = [...acc.lots];
-          acc.transactions = [...acc.transactions];
+          const acc = cloneAccount(account(subscriber));
           realizeExpiry(acc, now);
           const expiry =
             expiresAt ??
-            (acc.expirationPolicy.kind === 'after_secs' ? now + acc.expirationPolicy.seconds : undefined);
+            (acc.expirationPolicy.kind === 'after_secs'
+              ? now + acc.expirationPolicy.seconds
+              : undefined);
           acc.lots.push({ id: nextId(), remaining: amount, issuedAt: now, expiresAt: expiry });
           acc.balance += amount;
           record(acc, 'issue', amount, reason);
@@ -157,7 +167,7 @@ export const useCreditStore = create<CreditStoreState>()(
 
         applyCredit: (subscriber, subscriptionId, amountDue) => {
           const now = get().now();
-          const acc = { ...account(subscriber), lots: [...account(subscriber).lots], transactions: [...account(subscriber).transactions] };
+          const acc = cloneAccount(account(subscriber));
           realizeExpiry(acc, now);
           const applied = consume(acc, now, Math.max(0, amountDue));
           if (applied > 0) {
@@ -165,13 +175,18 @@ export const useCreditStore = create<CreditStoreState>()(
             record(acc, 'apply', -applied, 'charge_application');
           }
           commit(acc);
-          return { subscriptionId, applied, remainingDue: amountDue - applied, balanceAfter: acc.balance };
+          return {
+            subscriptionId,
+            applied,
+            remainingDue: amountDue - applied,
+            balanceAfter: acc.balance,
+          };
         },
 
         transferCredit: (from, to, amount, reason) => {
           if (amount <= 0 || from === to) return false;
           const now = get().now();
-          const sender = { ...account(from), lots: [...account(from).lots], transactions: [...account(from).transactions] };
+          const sender = cloneAccount(account(from));
           realizeExpiry(sender, now);
           if (availableOf(sender, now) < amount) return false;
           const moved = consume(sender, now, amount);
@@ -179,10 +194,12 @@ export const useCreditStore = create<CreditStoreState>()(
           record(sender, 'transfer_out', -moved, reason, to);
           commit(sender);
 
-          const recipient = { ...account(to), lots: [...account(to).lots], transactions: [...account(to).transactions] };
+          const recipient = cloneAccount(account(to));
           realizeExpiry(recipient, now);
           const expiry =
-            recipient.expirationPolicy.kind === 'after_secs' ? now + recipient.expirationPolicy.seconds : undefined;
+            recipient.expirationPolicy.kind === 'after_secs'
+              ? now + recipient.expirationPolicy.seconds
+              : undefined;
           recipient.lots.push({ id: nextId(), remaining: moved, issuedAt: now, expiresAt: expiry });
           recipient.balance += moved;
           record(recipient, 'transfer_in', moved, reason, from);
@@ -192,7 +209,7 @@ export const useCreditStore = create<CreditStoreState>()(
 
         expireCredits: (subscriber) => {
           const now = get().now();
-          const acc = { ...account(subscriber), lots: [...account(subscriber).lots], transactions: [...account(subscriber).transactions] };
+          const acc = cloneAccount(account(subscriber));
           const expired = realizeExpiry(acc, now);
           commit(acc);
           return expired;
@@ -210,6 +227,5 @@ export const useCreditStore = create<CreditStoreState>()(
         nextId: state.nextId,
       }),
     }
-    getAccount: (subscriber) => account(subscriber),
-  };
-});
+  )
+);
diff --git a/backend/services/billing/__tests__/creditService.test.ts b/backend/services/billing/__tests__/creditService.test.ts
new file mode 100644
index 00000000..9bcb1791
--- /dev/null
+++ b/backend/services/billing/__tests__/creditService.test.ts
@@ -0,0 +1,646 @@
+import { CreditService, creditReportToCsv } from '../creditService';
+import type { CreditReport } from '../creditTypes';
+import { BillingError, BillingErrorCode } from '../errors';
+
+type BillingErrorCodeValue = (typeof BillingErrorCode)[keyof typeof BillingErrorCode];
+
+/** Asserts that calling `fn` throws a `BillingError` with the given error code. */
+function expectBillingErrorCode(fn: () => unknown, code: BillingErrorCodeValue): void {
+  let caught: unknown;
+  try {
+    fn();
+  } catch (e) {
+    caught = e;
+  }
+  expect(caught).toBeInstanceOf(BillingError);
+  expect((caught as BillingError).code).toBe(code);
+}
+
+const ONE_DAY = 86_400;
+const BASE = 1_700_000_000;
+
+function makeService(): CreditService {
+  const clockVal = BASE;
+  return new CreditService({ clock: () => clockVal });
+}
+
+describe('CreditService', () => {
+  describe('issueCredit', () => {
+    it('issues credit and updates available balance', () => {
+      const svc = makeService();
+      const acc = svc.issueCredit({
+        accountId: 'alice',
+        actor: 'admin',
+        amount: 500,
+        reason: 'promo',
+      });
+      expect(acc.balance).toBe(500);
+      expect(acc.available).toBe(500);
+      expect(svc.getBalance('alice')).toBe(500);
+      expect(acc.entries).toHaveLength(1);
+      expect(acc.entries[0].kind).toBe('issue');
+      expect(acc.entries[0].amount).toBe(500);
+      expect(acc.entries[0].counterparty).toBe('admin');
+    });
+
+    it('rejects non-positive amounts', () => {
+      const svc = makeService();
+      expectBillingErrorCode(
+        () => svc.issueCredit({ accountId: 'alice', actor: 'admin', amount: 0, reason: 'bad' }),
+        BillingErrorCode.CREDIT_INVALID_AMOUNT
+      );
+    });
+
+    it('applies expiration policy when no expiresAt is supplied', () => {
+      const svc = makeService();
+      svc.setExpirationPolicy('alice', { kind: 'after_secs', seconds: 100 });
+      const beforeIssue = BASE;
+      svc.issueCredit({ accountId: 'alice', actor: 'admin', amount: 100, reason: 'promo' });
+      const lot = svc.getAccount('alice').lots[0];
+      expect(lot.expiresAt).toBe(beforeIssue + 100);
+    });
+
+    it('honours an explicit expiresAt override', () => {
+      const svc = makeService();
+      const explicit = BASE + 10 * ONE_DAY;
+      svc.issueCredit({
+        accountId: 'alice',
+        actor: 'admin',
+        amount: 100,
+        reason: 'make-good',
+        expiresAt: explicit,
+      });
+      expect(svc.getAccount('alice').lots[0].expiresAt).toBe(explicit);
+    });
+  });
+
+  describe('applyCreditToCharge', () => {
+    it('caps application at the amount due', () => {
+      const svc = makeService();
+      svc.issueCredit({ accountId: 'alice', actor: 'admin', amount: 300, reason: 'refund' });
+      const result = svc.applyCreditToCharge({
+        accountId: 'alice',
+        subscriptionId: 'sub_1',
+        amountDue: 500,
+      });
+      expect(result.applied).toBe(300);
+      expect(result.remainingDue).toBe(200);
+      expect(result.balanceAfter).toBe(0);
+      expect(svc.getBalance('alice')).toBe(0);
+    });
+
+    it('never goes negative when no credit exists', () => {
+      const svc = makeService();
+      const result = svc.applyCreditToCharge({
+        accountId: 'alice',
+        subscriptionId: 'sub_1',
+        amountDue: 1000,
+      });
+      expect(result.applied).toBe(0);
+      expect(result.remainingDue).toBe(1000);
+      expect(svc.getBalance('alice')).toBe(0);
+    });
+
+    it('rejects negative amountDue', () => {
+      const svc = makeService();
+      expectBillingErrorCode(
+        () => svc.applyCreditToCharge({ accountId: 'alice', subscriptionId: 'sub_1', amountDue: -10 }),
+        BillingErrorCode.CREDIT_INVALID_AMOUNT
+      );
+    });
+
+    it('consumes oldest lots first', () => {
+      const svc = makeService();
+      // first lot is smaller, issued earlier
+      const firstExpiry = BASE + 5 * ONE_DAY;
+      const secondExpiry = BASE + 30 * ONE_DAY;
+      svc.issueCredit({
+        accountId: 'alice',
+        actor: 'admin',
+        amount: 50,
+        reason: 'first',
+        expiresAt: firstExpiry,
+      });
+      svc.issueCredit({
+        accountId: 'alice',
+        actor: 'admin',
+        amount: 200,
+        reason: 'second',
+        expiresAt: secondExpiry,
+      });
+      // consume 100 — should take all 50 of first + 50 of second
+      const result = svc.applyCreditToCharge({
+        accountId: 'alice',
+        subscriptionId: 'sub_1',
+        amountDue: 100,
+      });
+      expect(result.applied).toBe(100);
+      const lots = svc.getAccount('alice').lots;
+      expect(lots[0].remaining).toBe(0);
+      expect(lots[1].remaining).toBe(150);
+    });
+  });
+
+  describe('transferCredit', () => {
+    it('transfers balance between accounts', () => {
+      const svc = makeService();
+      svc.issueCredit({ accountId: 'alice', actor: 'admin', amount: 400, reason: 'gift' });
+      const result = svc.transferCredit({
+        fromAccountId: 'alice',
+        toAccountId: 'bob',
+        amount: 150,
+        reason: 'gift',
+      });
+      expect(result.from.balance).toBe(250);
+      expect(result.to.balance).toBe(150);
+      expect(svc.getBalance('bob')).toBe(150);
+      const bobEntries = result.to.entries;
+      const transferIn = bobEntries.find((e) => e.kind === 'transfer_in');
+      expect(transferIn?.counterparty).toBe('alice');
+    });
+
+    it('rejects transfers exceeding available', () => {
+      const svc = makeService();
+      svc.issueCredit({ accountId: 'alice', actor: 'admin', amount: 100, reason: 'gift' });
+      expectBillingErrorCode(
+        () =>
+          svc.transferCredit({
+            fromAccountId: 'alice',
+            toAccountId: 'bob',
+            amount: 200,
+            reason: 'gift',
+          }),
+        BillingErrorCode.CREDIT_INSUFFICIENT
+      );
+    });
+
+    it('rejects self-transfer', () => {
+      const svc = makeService();
+      svc.issueCredit({ accountId: 'alice', actor: 'admin', amount: 100, reason: 'gift' });
+      expectBillingErrorCode(
+        () =>
+          svc.transferCredit({
+            fromAccountId: 'alice',
+            toAccountId: 'alice',
+            amount: 50,
+            reason: 'self',
+          }),
+        BillingErrorCode.CREDIT_SELF_TRANSFER
+      );
+    });
+
+    it('rejects non-positive amounts', () => {
+      const svc = makeService();
+      expectBillingErrorCode(
+        () =>
+          svc.transferCredit({
+            fromAccountId: 'alice',
+            toAccountId: 'bob',
+            amount: 0,
+            reason: 'gift',
+          }),
+        BillingErrorCode.CREDIT_INVALID_AMOUNT
+      );
+    });
+  });
+
+  describe('expiry', () => {
+    it('expires credit past its deadline', () => {
+      let clockVal = BASE;
+      const svc = new CreditService({ clock: () => clockVal });
+      svc.issueCredit({
+        accountId: 'alice',
+        actor: 'admin',
+        amount: 500,
+        reason: 'promo',
+        expiresAt: BASE + 100,
+      });
+      expect(svc.getBalance('alice')).toBe(500);
+      clockVal = BASE + 5_000;
+      const result = svc.expireAccount('alice');
+      expect(result.expiredAmount).toBe(500);
+      expect(svc.getAccount('alice').balance).toBe(0);
+    });
+
+    it('uses the expiration policy as a default expiry', () => {
+      let clockVal = BASE;
+      const svc = new CreditService({ clock: () => clockVal });
+      svc.setExpirationPolicy('alice', { kind: 'after_secs', seconds: 100 });
+      svc.issueCredit({ accountId: 'alice', actor: 'admin', amount: 200, reason: 'promo' });
+      clockVal = BASE + 50;
+      expect(svc.getBalance('alice')).toBe(200);
+      clockVal = BASE + 200;
+      const result = svc.expireAccount('alice');
+      expect(result.expiredAmount).toBe(200);
+    });
+
+    it('expireAll sweeps every account', () => {
+      let clockVal = BASE;
+      const svc = new CreditService({ clock: () => clockVal });
+      svc.issueCredit({
+        accountId: 'a',
+        actor: 'admin',
+        amount: 100,
+        reason: 'r',
+        expiresAt: BASE + 10,
+      });
+      svc.issueCredit({
+        accountId: 'b',
+        actor: 'admin',
+        amount: 200,
+        reason: 'r',
+        expiresAt: BASE + 10,
+      });
+      clockVal = BASE + 5_000;
+      const results = svc.expireAll();
+      expect(results).toHaveLength(2);
+      const total = results.reduce((s, r) => s + r.expiredAmount, 0);
+      expect(total).toBe(300);
+    });
+  });
+
+  describe('prepayment wallets', () => {
+    it('createWallet / deposit / withdraw / drawdown', () => {
+      const svc = makeService();
+      const wallet = svc.createWallet({
+        accountId: 'alice',
+        subscriptionId: 'sub_1',
+        currency: 'USD',
+      });
+      expect(wallet.balance).toBe(0);
+      svc.deposit({ walletId: wallet.id, accountId: 'alice', amount: 200 });
+      const afterDeposit = svc.getWallet(wallet.id);
+      expect(afterDeposit?.balance).toBe(200);
+      expect(afterDeposit?.totalDeposited).toBe(200);
+
+      svc.withdraw({ walletId: wallet.id, accountId: 'alice', amount: 50 });
+      const afterWithdraw = svc.getWallet(wallet.id);
+      expect(afterWithdraw?.balance).toBe(150);
+
+      const afterDrawdown = svc.drawdown({
+        walletId: wallet.id,
+        accountId: 'alice',
+        invoiceId: 'inv_1',
+        amount: 100,
+      });
+      expect(afterDrawdown.balance).toBe(50);
+      expect(afterDrawdown.totalWithdrawn).toBe(150);
+
+      const txs = svc.getWalletTransactions(wallet.id);
+      expect(txs).toHaveLength(3);
+      expect(txs[0].kind).toBe('deposit');
+      expect(txs[2].kind).toBe('drawdown');
+      expect(txs[2].invoiceId).toBe('inv_1');
+    });
+
+    it('drawdown caps at wallet balance (does not go negative)', () => {
+      const svc = makeService();
+      const w = svc.createWallet({ accountId: 'a', subscriptionId: 's', currency: 'USD' });
+      svc.deposit({ walletId: w.id, accountId: 'a', amount: 50 });
+      const after = svc.drawdown({ walletId: w.id, accountId: 'a', invoiceId: 'i', amount: 100 });
+      // draws down to zero, never negative; "drawn less than requested" is the
+      // graceful partial-fulfilment contract.
+      expect(after.balance).toBe(0);
+      expect(after.totalWithdrawn).toBe(50);
+    });
+
+    it('rejects deposit / withdraw when wallet is missing', () => {
+      const svc = makeService();
+      expectBillingErrorCode(
+        () => svc.deposit({ walletId: 9999, accountId: 'a', amount: 100 }),
+        BillingErrorCode.WALLET_NOT_FOUND
+      );
+      expectBillingErrorCode(
+        () => svc.withdraw({ walletId: 9999, accountId: 'a', amount: 100 }),
+        BillingErrorCode.WALLET_NOT_FOUND
+      );
+    });
+
+    it('rejects withdraw exceeding balance', () => {
+      const svc = makeService();
+      const w = svc.createWallet({ accountId: 'a', subscriptionId: 's', currency: 'USD' });
+      expectBillingErrorCode(
+        () => svc.withdraw({ walletId: w.id, accountId: 'a', amount: 1 }),
+        BillingErrorCode.CREDIT_INSUFFICIENT
+      );
+    });
+
+    it('listWalletsForAccount returns only matching wallets', () => {
+      const svc = makeService();
+      svc.createWallet({ accountId: 'a', subscriptionId: 's', currency: 'USD' });
+      svc.createWallet({ accountId: 'b', subscriptionId: 's', currency: 'USD' });
+      const list = svc.listWalletsForAccount('a');
+      expect(list).toHaveLength(1);
+      expect(list[0].accountId).toBe('a');
+    });
+  });
+
+  describe('analytics', () => {
+    it('getAccountSummary computes per-account lifetime aggregates', () => {
+      let clockVal = BASE;
+      const svc = new CreditService({ clock: () => clockVal });
+      svc.issueCredit({ accountId: 'alice', actor: 'admin', amount: 1000, reason: 'promo' });
+      svc.applyCreditToCharge({ accountId: 'alice', subscriptionId: 'sub', amountDue: 250 });
+      clockVal = BASE + 5;
+      svc.applyCreditToCharge({ accountId: 'alice', subscriptionId: 'sub', amountDue: 100 });
+      clockVal = BASE + 100_000;
+      svc.transferCredit({
+        fromAccountId: 'alice',
+        toAccountId: 'bob',
+        amount: 200,
+        reason: 'gift',
+      });
+
+      const summary = svc.getAccountSummary('alice');
+      expect(summary.totalIssued).toBe(1000);
+      expect(summary.totalApplied).toBe(350);
+      expect(summary.totalTransferredOut).toBe(200);
+      expect(summary.balance).toBe(450);
+      expect(summary.availableBalance).toBe(450);
+      expect(summary.averageConsumptionDays).toBeGreaterThan(0);
+    });
+
+    it('getGlobalBreakdown aggregates across accounts', () => {
+      const svc = makeService();
+      svc.issueCredit({ accountId: 'a', actor: 'admin', amount: 100, reason: 'refund' });
+      svc.issueCredit({ accountId: 'a', actor: 'admin', amount: 200, reason: 'promo' });
+      svc.issueCredit({ accountId: 'b', actor: 'admin', amount: 50, reason: 'adjustment' });
+      svc.applyCreditToCharge({ accountId: 'a', subscriptionId: 's', amountDue: 50 });
+
+      const breakdown = svc.getGlobalBreakdown();
+      expect(breakdown.totalIssuedAllTime).toBe(350);
+      expect(breakdown.totalAppliedAllTime).toBe(50);
+      expect(breakdown.totalActiveAccounts).toBe(2);
+      // Projected side accounts for the same amount since no past-due lots.
+      expect(breakdown.totalOutstandingLiability).toBe(300);
+      expect(breakdown.totalOutstandingLiabilityCommitted).toBe(300);
+      expect(breakdown.totalExpiredProjectedAllTime).toBe(0);
+      expect(breakdown.issuanceByReason.refund).toBe(100);
+      expect(breakdown.issuanceByReason.promo).toBe(200);
+      expect(breakdown.issuanceByReason.adjustment).toBe(50);
+    });
+
+    it('getGlobalBreakdown exposes committed vs projected outstanding liability', () => {
+      let clockVal = BASE;
+      const svc = new CreditService({ clock: () => clockVal });
+      svc.issueCredit({
+        accountId: 'a',
+        actor: 'admin',
+        amount: 100,
+        reason: 'p',
+        expiresAt: BASE + 50,
+      });
+      clockVal = BASE + 5_000; // past expiry
+      const breakdown = svc.getGlobalBreakdown();
+      // Past-due 100 is reflected on the projected side only.
+      expect(breakdown.totalOutstandingLiability).toBe(0);
+      expect(breakdown.totalOutstandingLiabilityCommitted).toBe(100);
+      expect(breakdown.totalExpiredProjectedAllTime).toBe(100);
+    });
+
+    it('getUsageTrend produces N buckets sorted ascending', () => {
+      let clockVal = BASE;
+      const svc = new CreditService({ clock: () => clockVal });
+      svc.issueCredit({ accountId: 'a', actor: 'admin', amount: 100, reason: 'promo' });
+      clockVal = BASE + ONE_DAY;
+      svc.applyCreditToCharge({ accountId: 'a', subscriptionId: 's', amountDue: 30 });
+      clockVal = BASE + 2 * ONE_DAY;
+      svc.issueCredit({ accountId: 'a', actor: 'admin', amount: 50, reason: 'refund' });
+
+      const trend = svc.getUsageTrend(7);
+      expect(trend).toHaveLength(7);
+      expect(trend[0].timestamp).toBeLessThan(trend[6].timestamp);
+      const totalIssued = trend.reduce((s, p) => s + p.issued, 0);
+      expect(totalIssued).toBe(150);
+      const totalApplied = trend.reduce((s, p) => s + p.applied, 0);
+      expect(totalApplied).toBe(30);
+    });
+
+    it('getUsageTrend returns empty array for non-positive days', () => {
+      const svc = makeService();
+      expect(svc.getUsageTrend(0)).toEqual([]);
+    });
+
+    it('getExpiryForecast returns lots within the horizon', () => {
+      const svc = makeService();
+      svc.issueCredit({
+        accountId: 'a',
+        actor: 'admin',
+        amount: 100,
+        reason: 'r',
+        expiresAt: BASE + 5 * ONE_DAY,
+      });
+      svc.issueCredit({
+        accountId: 'a',
+        actor: 'admin',
+        amount: 50,
+        reason: 'r',
+        expiresAt: BASE + 60 * ONE_DAY,
+      });
+      const forecast = svc.getExpiryForecast('a', 30 * ONE_DAY);
+      expect(forecast).toHaveLength(1);
+      expect(forecast[0].amount).toBe(100);
+      expect(forecast[0].daysRemaining).toBe(5);
+    });
+
+    it('topAccountsByBalance returns ranked accounts', () => {
+      const svc = makeService();
+      svc.issueCredit({ accountId: 'a', actor: 'admin', amount: 50, reason: 'r' });
+      svc.issueCredit({ accountId: 'b', actor: 'admin', amount: 200, reason: 'r' });
+      svc.issueCredit({ accountId: 'c', actor: 'admin', amount: 100, reason: 'r' });
+      const top = svc.topAccountsByBalance(2);
+      expect(top).toHaveLength(2);
+      expect(top[0].accountId).toBe('b');
+      expect(top[1].accountId).toBe('c');
+    });
+
+    it('monitoring hours bucket classifies lots correctly', () => {
+      const svc = makeService();
+      svc.issueCredit({
+        accountId: 'a',
+        actor: 'admin',
+        amount: 50,
+        reason: 'r',
+        expiresAt: BASE + 3 * ONE_DAY,
+      });
+      svc.issueCredit({
+        accountId: 'a',
+        actor: 'admin',
+        amount: 75,
+        reason: 'r',
+        expiresAt: BASE + 20 * ONE_DAY,
+      });
+      svc.issueCredit({ accountId: 'a', actor: 'admin', amount: 200, reason: 'never' });
+      const summary = svc.getAccountSummary('a');
+      expect(summary.expiringByTimeBucket.expires_within_7d).toBe(50);
+      expect(summary.expiringByTimeBucket.expires_within_30d).toBe(75);
+      expect(summary.expiringByTimeBucket.no_expiry).toBe(200);
+    });
+  });
+
+  describe('reporting', () => {
+    it('printReport contains summary + entries + ledger flow', () => {
+      const svc = makeService();
+      svc.issueCredit({ accountId: 'a', actor: 'admin', amount: 100, reason: 'r' });
+      svc.applyCreditToCharge({ accountId: 'a', subscriptionId: 's', amountDue: 30 });
+      const report: CreditReport = svc.printReport('a');
+      expect(report.accountId).toBe('a');
+      expect(report.summary.totalIssued).toBe(100);
+      expect(report.summary.totalApplied).toBe(30);
+      expect(report.ledgerFlow.issued).toBe(100);
+      expect(report.ledgerFlow.applied).toBe(30);
+      expect(report.entries.length).toBe(2);
+      expect(report.entries.map((e) => e.kind).sort()).toEqual(['apply', 'issue']);
+    });
+
+    it('exportReport csv contains sections', () => {
+      const svc = makeService();
+      svc.issueCredit({ accountId: 'a', actor: 'admin', amount: 100, reason: 'r' });
+      const w = svc.createWallet({
+        accountId: 'a',
+        subscriptionId: 'sub',
+        currency: 'USD',
+      });
+      svc.deposit({ walletId: w.id, accountId: 'a', amount: 50 });
+      const csv = svc.exportReport('a', 'csv');
+      expect(csv).toContain('# Credit Report');
+      expect(csv).toContain('section,entries');
+      expect(csv).toContain('section,wallets');
+      expect(csv).toContain('section,wallet_transactions');
+      expect(csv).toContain('deposit');
+    });
+
+    it('exportReport json serialises the report structure', () => {
+      const svc = makeService();
+      svc.issueCredit({ accountId: 'a', actor: 'admin', amount: 100, reason: 'r' });
+      const json = svc.exportReport('a', 'json');
+      const parsed = JSON.parse(json);
+      expect(parsed.summary.totalIssued).toBe(100);
+      expect(parsed.ledgerFlow.issued).toBe(100);
+      expect(Array.isArray(parsed.entries)).toBe(true);
+    });
+
+    it('creditReportToCsv escapes commas in reasons', () => {
+      const report: CreditReport = {
+        generatedAt: BASE,
+        accountId: 'with,comma',
+        summary: {
+          accountId: 'with,comma',
+          balance: 0,
+          availableBalance: 0,
+          totalIssued: 0,
+          totalApplied: 0,
+          totalTransferredIn: 0,
+          totalTransferredOut: 0,
+          totalExpired: 0,
+          expiringByTimeBucket: {
+            expires_within_7d: 0,
+            expires_within_30d: 0,
+            no_expiry: 0,
+          },
+          averageConsumptionDays: 0,
+        },
+        entries: [
+          {
+            id: 1,
+            kind: 'issue',
+            amount: 10,
+            timestamp: BASE,
+            reason: 'has,comma',
+          },
+        ],
+        wallets: [],
+        transactions: [],
+        ledgerFlow: { issued: 10, applied: 0, expired: 0 },
+      };
+      const csv = creditReportToCsv(report);
+      expect(csv).toContain('"with,comma"');
+      expect(csv).toContain('"has,comma"');
+    });
+  });
+
+  describe('audit trail', () => {
+    it('getAuditTrail filters by kind and time', () => {
+      let clockVal = BASE;
+      const svc = new CreditService({ clock: () => clockVal });
+      svc.issueCredit({ accountId: 'a', actor: 'admin', amount: 100, reason: 'r' });
+      clockVal = BASE + ONE_DAY;
+      svc.applyCreditToCharge({ accountId: 'a', subscriptionId: 's', amountDue: 50 });
+      clockVal = BASE + 2 * ONE_DAY;
+      svc.issueCredit({ accountId: 'a', actor: 'admin', amount: 30, reason: 'r' });
+
+      const page = svc.getAuditTrail({
+        accountId: 'a',
+        kinds: ['issue'],
+        limit: 10,
+      });
+      expect(page.entries.every((e) => e.kind === 'issue')).toBe(true);
+      expect(page.totalEntries).toBe(2);
+      expect(page.hasMore).toBe(false);
+
+      const timeFilter = svc.getAuditTrail({
+        accountId: 'a',
+        fromTime: BASE + ONE_DAY + 1,
+        limit: 10,
+      });
+      // oldest issue at BASE is excluded
+      expect(timeFilter.entries.length).toBe(1);
+      expect(timeFilter.entries[0].kind).toBe('issue');
+    });
+
+    it('getAuditTrail paginates with limit + offset', () => {
+      let clockVal = BASE;
+      const svc = new CreditService({ clock: () => clockVal });
+      for (let i = 0; i < 5; i += 1) {
+        svc.issueCredit({ accountId: 'a', actor: 'admin', amount: 10, reason: 'r' });
+        clockVal += ONE_DAY;
+      }
+      const page1 = svc.getAuditTrail({ accountId: 'a', limit: 2, offset: 0 });
+      const page2 = svc.getAuditTrail({ accountId: 'a', limit: 2, offset: 2 });
+      const page3 = svc.getAuditTrail({ accountId: 'a', limit: 2, offset: 4 });
+      expect(page1.entries).toHaveLength(2);
+      expect(page2.entries).toHaveLength(2);
+      expect(page3.entries).toHaveLength(1);
+      expect(page1.hasMore).toBe(true);
+      expect(page2.hasMore).toBe(true);
+      expect(page3.hasMore).toBe(false);
+      expect(page3.nextOffset).toBeNull();
+      // newest first
+      expect(page1.entries[0].timestamp).toBeGreaterThan(page1.entries[1].timestamp);
+      expect(page2.entries[0].timestamp).toBeGreaterThan(page3.entries[0].timestamp);
+    });
+
+    it('clamps negative offset / zero limit to safe defaults', () => {
+      const svc = makeService();
+      svc.issueCredit({ accountId: 'a', actor: 'admin', amount: 10, reason: 'r' });
+      const page = svc.getAuditTrail({ accountId: 'a', offset: -50, limit: 0 });
+      expect(page.entries.length).toBe(1);
+    });
+
+    it('audit trail does not leak synthetic entries on reads (no commit needed)', () => {
+      let clockVal = BASE;
+      const svc = new CreditService({ clock: () => clockVal });
+      svc.issueCredit({
+        accountId: 'a',
+        actor: 'admin',
+        amount: 100,
+        reason: 'p',
+        expiresAt: BASE + 50,
+      });
+      // Past the expiry but never called expireAccount(). Audit trail MUST NOT
+      // contain the synthetic expire entry that read-only projections used to
+      // synthesise.
+      clockVal = BASE + 5_000;
+      const page = svc.getAuditTrail({ accountId: 'a', kinds: ['expire'], limit: 10 });
+      expect(page.entries).toHaveLength(0);
+      expect(page.totalEntries).toBe(0);
+
+      // After explicit commit, the expire entry is real and shows up.
+      const expired = svc.expireAccount('a');
+      expect(expired.expiredAmount).toBe(100);
+      const pageAfter = svc.getAuditTrail({ accountId: 'a', kinds: ['expire'], limit: 10 });
+      expect(pageAfter.entries).toHaveLength(1);
+      expect(pageAfter.entries[0].kind).toBe('expire');
+    });
+  });
+});
diff --git a/backend/services/billing/creditService.ts b/backend/services/billing/creditService.ts
new file mode 100644
index 00000000..00c64d87
--- /dev/null
+++ b/backend/services/billing/creditService.ts
@@ -0,0 +1,889 @@
+/**
+ * Server-side credit service for SubTrackr.
+ *
+ * Architectural notes
+ * -------------------
+ * * The **source of truth** is a ledger model (lots + signed entries +
+ *   running balance). It intentionally mirrors the on-chain
+ *   `subtrackr-credit` Soroban contract and the mobile `AccountCredit`
+ *   store so we can later replay a stream of contract transactions into
+ *   this service without translation.
+ * * This service integrates with billing **at invoice close**:
+ *     draft invoice  →  metering  →  applyCreditToCharge  →  payments / dunning.
+ *   Anything downstream of `applyCreditToCharge` only ever sees the net
+ *   amount due.
+ * * Where it differs from the Soroban contract:
+ *   * In-process state (no persistence) — substitute with a database later.
+ *   * Includes off-chain analytics (deferred liability, breakage, burn rate,
+ *     top accounts, expiry forecast) and CSV/JSON reports that we don't put
+ *     on-chain.
+ * * Read methods (`getAccount`, `getGlobalBreakdown`, `listAccounts`,
+ *   `topAccountsByBalance`, `getExpiryForecast`) are **strictly
+ *   non-mutating**: they clone state and project expiry-aware figures
+ *   without committing them back. The mutating expiry surface is
+ *   `expireAccount()` / `expireAll()` — call those explicitly when
+ *   you actually want the ledger updated.
+ *
+ * The web app keeps its own `CreditNote` store for the higher-level
+ * status-projection UX (DRAFT/ISSUED/PARTIALLY_APPLIED/APPLIED/etc.). That
+ * projection is owned by the web store and not duplicated here to keep the
+ * backend's contract-shaped ledger clean.
+ */
+
+import type {
+  AccountCreditSummary,
+  ApplyCreditInput,
+  ApplyCreditResult,
+  CreditAccount,
+  CreditAuditPage,
+  CreditAuditQuery,
+  CreditBucketBreakdown,
+  CreditEntry,
+  CreditEntryKind,
+  CreditExpiryForecast,
+  CreditLot,
+  CreditReport,
+  CreditUsageTrendPoint,
+  ExpirationPolicy,
+  IssueCreditInput,
+  PrepaymentTransaction,
+  PrepaymentWallet,
+  TopAccount,
+  TransferCreditInput,
+} from './creditTypes';
+import { BillingError } from './errors';
+
+const ONE_DAY_SECS = 86_400;
+const ONE_HOUR_SECS = 3_600;
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+const nowSec = (): number => Math.floor(Date.now() / 1_000);
+
+const isExpiredLot = (lot: CreditLot, now: number): boolean =>
+  lot.expiresAt !== undefined && lot.expiresAt <= now;
+
+const availableOf = (account: CreditAccount, now: number): number =>
+  account.lots.reduce(
+    (sum, lot) => (lot.remaining > 0 && !isExpiredLot(lot, now) ? sum + lot.remaining : sum),
+    0
+  );
+
+const cloneAccount = (acc: CreditAccount): CreditAccount => ({
+  ...acc,
+  lots: [...acc.lots],
+  entries: [...acc.entries],
+});
+
+/** Deep-clone a returned account so callers cannot mutate stored state. */
+const deepCloneAccount = (acc: CreditAccount): CreditAccount => ({
+  ...acc,
+  lots: acc.lots.map((l) => ({ ...l })),
+  entries: acc.entries.map((e) => ({ ...e })),
+});
+
+const deepCloneEntry = (e: CreditEntry): CreditEntry => ({ ...e });
+
+const deepCloneTransaction = (t: PrepaymentTransaction): PrepaymentTransaction => ({ ...t });
+
+// ─── Service ────────────────────────────────────────────────────────────────
+
+export class CreditService {
+  private readonly accounts = new Map<string, CreditAccount>();
+  private readonly wallets = new Map<number, PrepaymentWallet>();
+  private readonly walletTx = new Map<number, PrepaymentTransaction[]>();
+  private nextLotId = 1;
+  private nextEntryId = 1;
+  private nextWalletId = 1;
+  private nextTxId = 1;
+  private readonly now: () => number;
+
+  constructor(opts: { clock?: () => number } = {}) {
+    this.now = opts.clock ?? nowSec;
+  }
+
+  // ─── Account housekeeping ───────────────────────────────────────────────
+
+  private ensureAccount(accountId: string): CreditAccount {
+    let acc = this.accounts.get(accountId);
+    if (!acc) {
+      acc = {
+        accountId,
+        balance: 0,
+        available: 0,
+        lots: [],
+        entries: [],
+        expirationPolicy: { kind: 'never' },
+      };
+      this.accounts.set(accountId, acc);
+    }
+    return acc;
+  }
+
+  private commit(acc: CreditAccount): void {
+    this.accounts.set(acc.accountId, acc);
+  }
+
+  private record(
+    acc: CreditAccount,
+    kind: CreditEntryKind,
+    amount: number,
+    reason: string,
+    counterparty?: string
+  ): void {
+    acc.entries.push({
+      id: this.nextEntryId++,
+      kind,
+      amount,
+      timestamp: this.now(),
+      reason,
+      counterparty,
+    });
+  }
+
+  /** Realises expiry on the supplied account *in place*; returns how much was
+   *  expired. Does NOT record an entry — callers either commit the synthetic
+   *  entry themselves (mutating path: expireAccount) or rely on the projection
+   *  helper below (read path). */
+  private realiseExpiryInPlace(acc: CreditAccount, now: number): number {
+    let expired = 0;
+    acc.lots = acc.lots.map((lot) => {
+      if (lot.remaining > 0 && isExpiredLot(lot, now)) {
+        expired += lot.remaining;
+        return { ...lot, remaining: 0 };
+      }
+      return lot;
+    });
+    if (expired > 0) acc.balance -= expired;
+    return expired;
+  }
+
+  /** Mutating helper: zeroes expired lots, decrements balance, and records a
+   *  single `expire` ledger entry. */
+  private realiseExpiry(acc: CreditAccount, now: number): number {
+    const expired = this.realiseExpiryInPlace(acc, now);
+    if (expired > 0) this.record(acc, 'expire', -expired, 'expired');
+    return expired;
+  }
+
+  /** Truly non-mutating projection: returns a clone of `acc` whose lots
+   *  reflect a hypothetical "if we ran expireAccount right now" outcome.
+   *  The plane of `entries` is **unchanged** (no synthetic entries pushed) and
+   *  no instance counters are advanced — callers can iterate `projected.entries`
+   *  safely for audit-trail / reporting purposes. */
+  private projectExpiry(acc: CreditAccount, now: number): CreditAccount {
+    const projected = cloneAccount(acc);
+    let pastDueTotal = 0;
+    projected.lots = projected.lots.map((lot) => {
+      if (lot.remaining > 0 && isExpiredLot(lot, now)) {
+        pastDueTotal += lot.remaining;
+        return { ...lot, remaining: 0 };
+      }
+      return lot;
+    });
+    projected.available = availableOf(projected, now);
+    if (pastDueTotal > 0) projected.balance -= pastDueTotal;
+    return projected;
+  }
+
+  private consume(acc: CreditAccount, now: number, amount: number): number {
+    let remaining = amount;
+    acc.lots = acc.lots.map((lot) => {
+      if (remaining <= 0 || lot.remaining <= 0 || isExpiredLot(lot, now)) return lot;
+      const take = Math.min(lot.remaining, remaining);
+      remaining -= take;
+      return { ...lot, remaining: lot.remaining - take };
+    });
+    return amount - remaining;
+  }
+
+  private refreshAvailable(acc: CreditAccount): void {
+    acc.available = availableOf(acc, this.now());
+  }
+
+  // ─── Account-level configuration ────────────────────────────────────────
+
+  setExpirationPolicy(accountId: string, policy: ExpirationPolicy): void {
+    const acc = this.ensureAccount(accountId);
+    acc.expirationPolicy = policy;
+    this.commit(acc);
+  }
+
+  /** Deep-clone read of an account. Callers cannot mutate stored state. */
+  getAccount(accountId: string): CreditAccount {
+    const acc = this.ensureAccount(accountId);
+    const projected = this.projectExpiry(acc, this.now());
+    this.refreshAvailable(projected);
+    return deepCloneAccount(projected);
+  }
+
+  getBalance(accountId: string): number {
+    return availableOf(this.ensureAccount(accountId), this.now());
+  }
+
+  // ─── Issue ─────────────────────────────────────────────────────────────
+
+  issueCredit(input: IssueCreditInput): CreditAccount {
+    if (input.amount <= 0) {
+      throw BillingError.creditInvalidAmount('amount must be positive');
+    }
+    const now = this.now();
+    const acc = cloneAccount(this.ensureAccount(input.accountId));
+    this.realiseExpiry(acc, now);
+
+    const expiry =
+      input.expiresAt ??
+      (acc.expirationPolicy.kind === 'after_secs'
+        ? now + acc.expirationPolicy.seconds
+        : undefined);
+
+    acc.lots.push({
+      id: this.nextLotId++,
+      remaining: input.amount,
+      issuedAt: now,
+      expiresAt: expiry,
+    });
+    acc.balance += input.amount;
+    this.record(acc, 'issue', input.amount, input.reason, input.actor);
+    this.refreshAvailable(acc);
+    this.commit(acc);
+    return this.getAccount(acc.accountId);
+  }
+
+  // ─── Apply to a charge ─────────────────────────────────────────────────
+
+  applyCreditToCharge(input: ApplyCreditInput): ApplyCreditResult {
+    if (input.amountDue < 0) {
+      throw BillingError.creditInvalidAmount('amountDue may not be negative');
+    }
+    const now = this.now();
+    const acc = cloneAccount(this.ensureAccount(input.accountId));
+    this.realiseExpiry(acc, now);
+    const available = availableOf(acc, now);
+    const applied = this.consume(acc, now, Math.min(input.amountDue, available));
+    if (applied > 0) {
+      acc.balance -= applied;
+      this.record(acc, 'apply', -applied, 'charge_application');
+    }
+    this.refreshAvailable(acc);
+    this.commit(acc);
+    return {
+      accountId: acc.accountId,
+      subscriptionId: input.subscriptionId,
+      applied,
+      remainingDue: input.amountDue - applied,
+      balanceAfter: acc.balance,
+    };
+  }
+
+  // ─── Transfer between accounts ─────────────────────────────────────────
+
+  transferCredit(input: TransferCreditInput): { from: CreditAccount; to: CreditAccount } {
+    if (input.amount <= 0) {
+      throw BillingError.creditInvalidAmount('amount must be positive');
+    }
+    if (input.fromAccountId === input.toAccountId) {
+      throw BillingError.creditSelfTransfer(input.fromAccountId);
+    }
+    const now = this.now();
+    const sender = cloneAccount(this.ensureAccount(input.fromAccountId));
+    this.realiseExpiry(sender, now);
+    if (availableOf(sender, now) < input.amount) {
+      throw BillingError.creditInsufficient(
+        input.fromAccountId,
+        input.amount,
+        availableOf(sender, now)
+      );
+    }
+    const moved = this.consume(sender, now, input.amount);
+    sender.balance -= moved;
+    this.record(sender, 'transfer_out', -moved, input.reason, input.toAccountId);
+    this.refreshAvailable(sender);
+    this.commit(sender);
+
+    const recipient = cloneAccount(this.ensureAccount(input.toAccountId));
+    this.realiseExpiry(recipient, now);
+    const expiry =
+      recipient.expirationPolicy.kind === 'after_secs'
+        ? now + recipient.expirationPolicy.seconds
+        : undefined;
+    recipient.lots.push({
+      id: this.nextLotId++,
+      remaining: moved,
+      issuedAt: now,
+      expiresAt: expiry,
+    });
+    recipient.balance += moved;
+    this.record(recipient, 'transfer_in', moved, input.reason, input.fromAccountId);
+    this.refreshAvailable(recipient);
+    this.commit(recipient);
+
+    return { from: this.getAccount(sender.accountId), to: this.getAccount(recipient.accountId) };
+  }
+
+  // ─── Expiry (mutating — explicitly named) ──────────────────────────────
+
+  expireAccount(accountId: string): { expiredAmount: number; account: CreditAccount } {
+    const now = this.now();
+    const acc = cloneAccount(this.ensureAccount(accountId));
+    const expiredAmount = this.realiseExpiry(acc, now);
+    this.refreshAvailable(acc);
+    this.commit(acc);
+    return { expiredAmount, account: this.getAccount(accountId) };
+  }
+
+  /** Cron-style sweep across every account (or a particular subset). */
+  expireAll(accounts?: string[]): Array<{ accountId: string; expiredAmount: number }> {
+    const targets = accounts ?? Array.from(this.accounts.keys());
+    return targets.map((id) => ({
+      accountId: id,
+      expiredAmount: this.expireAccount(id).expiredAmount,
+    }));
+  }
+
+  // ─── Prepayment wallets ────────────────────────────────────────────────
+
+  createWallet(input: {
+    accountId: string;
+    subscriptionId: string;
+    currency: string;
+  }): PrepaymentWallet {
+    const now = this.now();
+    const wallet: PrepaymentWallet = {
+      id: this.nextWalletId++,
+      accountId: input.accountId,
+      subscriptionId: input.subscriptionId,
+      currency: input.currency,
+      balance: 0,
+      totalDeposited: 0,
+      totalWithdrawn: 0,
+      createdAt: now,
+      updatedAt: now,
+    };
+    this.wallets.set(wallet.id, wallet);
+    this.walletTx.set(wallet.id, []);
+    return { ...wallet };
+  }
+
+  deposit(input: { walletId: number; accountId: string; amount: number }): PrepaymentWallet {
+    if (input.amount <= 0) {
+      throw BillingError.creditInvalidAmount('deposit must be positive');
+    }
+    const wallet = this.wallets.get(input.walletId);
+    if (!wallet || wallet.accountId !== input.accountId) {
+      throw BillingError.walletNotFound(input.walletId);
+    }
+    const now = this.now();
+    wallet.balance += input.amount;
+    wallet.totalDeposited += input.amount;
+    wallet.updatedAt = now;
+    const tx: PrepaymentTransaction = {
+      id: this.nextTxId++,
+      walletId: wallet.id,
+      kind: 'deposit',
+      amount: input.amount,
+      balanceAfter: wallet.balance,
+      timestamp: now,
+    };
+    const txs = this.walletTx.get(wallet.id) ?? [];
+    txs.push(tx);
+    this.walletTx.set(wallet.id, txs);
+    return { ...wallet };
+  }
+
+  withdraw(input: { walletId: number; accountId: string; amount: number }): PrepaymentWallet {
+    if (input.amount <= 0) {
+      throw BillingError.creditInvalidAmount('withdraw must be positive');
+    }
+    const wallet = this.wallets.get(input.walletId);
+    if (!wallet || wallet.accountId !== input.accountId) {
+      throw BillingError.walletNotFound(input.walletId);
+    }
+    if (wallet.balance < input.amount) {
+      throw BillingError.creditInsufficient(
+        `wallet:${input.walletId}`,
+        input.amount,
+        wallet.balance
+      );
+    }
+    const now = this.now();
+    wallet.balance -= input.amount;
+    wallet.totalWithdrawn += input.amount;
+    wallet.updatedAt = now;
+    const tx: PrepaymentTransaction = {
+      id: this.nextTxId++,
+      walletId: wallet.id,
+      kind: 'withdraw',
+      amount: input.amount,
+      balanceAfter: wallet.balance,
+      timestamp: now,
+    };
+    const txs = this.walletTx.get(wallet.id) ?? [];
+    txs.push(tx);
+    this.walletTx.set(wallet.id, txs);
+    return { ...wallet };
+  }
+
+  drawdown(input: {
+    walletId: number;
+    accountId: string;
+    invoiceId: string;
+    amount: number;
+  }): PrepaymentWallet {
+    if (input.amount <= 0) {
+      throw BillingError.creditInvalidAmount('drawdown must be positive');
+    }
+    const wallet = this.wallets.get(input.walletId);
+    if (!wallet || wallet.accountId !== input.accountId) {
+      throw BillingError.walletNotFound(input.walletId);
+    }
+    const drawdownAmount = Math.min(wallet.balance, input.amount);
+    if (drawdownAmount <= 0) return { ...wallet };
+    const now = this.now();
+    wallet.balance -= drawdownAmount;
+    wallet.totalWithdrawn += drawdownAmount;
+    wallet.updatedAt = now;
+    const tx: PrepaymentTransaction = {
+      id: this.nextTxId++,
+      walletId: wallet.id,
+      kind: 'drawdown',
+      amount: drawdownAmount,
+      balanceAfter: wallet.balance,
+      invoiceId: input.invoiceId,
+      timestamp: now,
+    };
+    const txs = this.walletTx.get(wallet.id) ?? [];
+    txs.push(tx);
+    this.walletTx.set(wallet.id, txs);
+    return { ...wallet };
+  }
+
+  getWallet(walletId: number): PrepaymentWallet | undefined {
+    const w = this.wallets.get(walletId);
+    return w ? { ...w } : undefined;
+  }
+
+  getWalletTransactions(walletId: number): PrepaymentTransaction[] {
+    return (this.walletTx.get(walletId) ?? []).map(deepCloneTransaction);
+  }
+
+  listWalletsForAccount(accountId: string): PrepaymentWallet[] {
+    return Array.from(this.wallets.values())
+      .filter((w) => w.accountId === accountId)
+      .map((w) => ({ ...w }));
+  }
+
+  // ─── Analytics (strictly non-mutating reads) ───────────────────────────
+
+  getAccountSummary(accountId: string): AccountCreditSummary {
+    const projected = this.projectExpiry(this.ensureAccount(accountId), this.now());
+    return computeSummary(projected, this.now());
+  }
+
+  /**
+   * Global roll-up: outstanding liability (deferred-credit figure for the
+   * accounting/finance team), all-time issuance/application/expiry totals,
+   * and the issuance-by-reason distribution (refund vs promo vs adjustment).
+   */
+  getGlobalBreakdown(): CreditBucketBreakdown {
+    const now = this.now();
+    let active = 0;
+    let outstandingProjected = 0;
+    let outstandingCommitted = 0;
+    let totalIssued = 0;
+    let totalApplied = 0;
+    let totalExpired = 0;
+    let totalExpiredProjected = 0;
+    const issuanceByReason: Record<string, number> = {};
+
+    for (const acc of this.accounts.values()) {
+      const projected = this.projectExpiry(acc, now);
+      if (projected.available > 0) active += 1;
+      outstandingProjected += projected.available;
+      // Committed-side outstanding = sum of lot remaining values from the
+      // canonical account (no past-due lot zeroing applied).
+      outstandingCommitted += acc.lots.reduce((s, lot) => s + lot.remaining, 0);
+      totalExpiredProjected += projected.balance < acc.balance
+        ? acc.balance - projected.balance
+        : 0;
+
+      for (const entry of acc.entries) {
+        if (entry.kind === 'issue' && entry.amount > 0) {
+          totalIssued += entry.amount;
+          issuanceByReason[entry.reason] =
+            (issuanceByReason[entry.reason] ?? 0) + entry.amount;
+        } else if (entry.kind === 'apply' && entry.amount < 0) {
+          totalApplied += -entry.amount;
+        } else if (entry.kind === 'expire' && entry.amount < 0) {
+          totalExpired += -entry.amount;
+        }
+      }
+    }
+
+    return {
+      totalActiveAccounts: active,
+      totalOutstandingLiability: outstandingProjected,
+      totalOutstandingLiabilityCommitted: outstandingCommitted,
+      totalIssuedAllTime: totalIssued,
+      totalAppliedAllTime: totalApplied,
+      totalExpiredAllTime: totalExpired,
+      totalExpiredProjectedAllTime: totalExpiredProjected,
+      issuanceByReason,
+    };
+  }
+
+  /**
+   * Issuance / application / expiry bucketed by day for the last N days.
+   * Reads expiry-realised entries (projection-only) so past-due lots show up
+   * immediately in the trend.
+   */
+  getUsageTrend(days = 30, bucketSecs = ONE_DAY_SECS): CreditUsageTrendPoint[] {
+    if (days <= 0) return [];
+    const now = this.now();
+    // Window is inclusive of `now`: the last bucket ends at `now`, so we
+    // anchor the buckets at `start = now - (days - 1) * bucketSecs`.
+    const start = now - (days - 1) * bucketSecs;
+    const buckets = new Map<number, CreditUsageTrendPoint>();
+
+    for (let i = 0; i < days; i += 1) {
+      const ts = start + i * bucketSecs;
+      buckets.set(ts, {
+        timestamp: ts,
+        issued: 0,
+        applied: 0,
+        expired: 0,
+        expiredProjected: 0,
+        netIssuance: 0,
+      });
+    }
+
+    for (const acc of this.accounts.values()) {
+      const projected = this.projectExpiry(acc, now);
+      const projectedExpiredDelta =
+        projected.balance < acc.balance ? acc.balance - projected.balance : 0;
+      // Bucket past-due expirable amounts into the LAST bucket — they're
+      // "about-to-expire" from the consumer's perspective at read time.
+      if (projectedExpiredDelta > 0) {
+        const lastBucketTs = start + (days - 1) * bucketSecs;
+        const lastBucket = buckets.get(lastBucketTs);
+        if (lastBucket) lastBucket.expiredProjected += projectedExpiredDelta;
+      }
+
+      for (const entry of acc.entries) {
+        if (entry.timestamp < start || entry.timestamp > now) continue;
+        const idx = Math.min(days - 1, Math.floor((entry.timestamp - start) / bucketSecs));
+        const bucketTs = start + idx * bucketSecs;
+        const bucket = buckets.get(bucketTs);
+        if (!bucket) continue;
+        if (entry.kind === 'issue') {
+          bucket.issued += entry.amount;
+          bucket.netIssuance += entry.amount;
+        } else if (entry.kind === 'apply') {
+          bucket.applied += -entry.amount;
+          bucket.netIssuance -= -entry.amount;
+        } else if (entry.kind === 'expire') {
+          bucket.expired += -entry.amount;
+        }
+      }
+    }
+
+    return Array.from(buckets.values()).sort((a, b) => a.timestamp - b.timestamp);
+  }
+
+  /**
+   * Expiry forecast for an account. Only includes lots that will expire in
+   * the future — past-due lots are excluded since their expiry should already
+   * have been (or about to be) realised by `expireAccount()`.
+   */
+  getExpiryForecast(
+    accountId: string,
+    horizonSecs = 30 * ONE_DAY_SECS
+  ): CreditExpiryForecast[] {
+    const acc = this.ensureAccount(accountId);
+    const now = this.now();
+    const horizonEnd = now + horizonSecs;
+    const out: CreditExpiryForecast[] = [];
+    for (const lot of acc.lots) {
+      if (lot.remaining <= 0 || lot.expiresAt === undefined) continue;
+      if (lot.expiresAt <= now) continue;
+      if (lot.expiresAt > horizonEnd) continue;
+      out.push({
+        accountId,
+        amount: lot.remaining,
+        expiresAt: lot.expiresAt,
+        daysRemaining: Math.max(1, Math.ceil((lot.expiresAt - now) / ONE_DAY_SECS)),
+      });
+    }
+    return out.sort((a, b) => a.expiresAt - b.expiresAt);
+  }
+
+  /** Top accounts by available balance (descending). Uses projected expiry. */
+  topAccountsByBalance(limit = 10): TopAccount[] {
+    const now = this.now();
+    const snapshot = Array.from(this.accounts.values()).map((acc) => {
+      const projected = this.projectExpiry(acc, now);
+      return {
+        accountId: acc.accountId,
+        balance: projected.balance,
+        availableBalance: projected.available,
+      };
+    });
+    snapshot.sort((a, b) => b.availableBalance - a.availableBalance);
+    return snapshot.slice(0, limit).map((row, idx) => ({ ...row, rank: idx + 1 }));
+  }
+
+  /** List all known accounts (projection-only read). */
+  listAccounts(): CreditAccount[] {
+    const now = this.now();
+    return Array.from(this.accounts.values()).map((acc) => {
+      const projected = this.projectExpiry(acc, now);
+      return deepCloneAccount(projected);
+    });
+  }
+
+  // ─── Reporting ─────────────────────────────────────────────────────────
+
+  printReport(accountId: string): CreditReport {
+    const now = this.now();
+    const live = this.projectExpiry(this.ensureAccount(accountId), now);
+    const summary = computeSummary(live, now);
+    const wallets = this.listWalletsForAccount(accountId);
+    const transactions = wallets.flatMap((w) => this.getWalletTransactions(w.id));
+
+    const issued = live.entries
+      .filter((e) => e.kind === 'issue')
+      .reduce((s, e) => s + e.amount, 0);
+    const applied = live.entries
+      .filter((e) => e.kind === 'apply')
+      .reduce((s, e) => s + -e.amount, 0);
+    const expired = live.entries
+      .filter((e) => e.kind === 'expire')
+      .reduce((s, e) => s + -e.amount, 0);
+
+    return {
+      generatedAt: now,
+      accountId,
+      summary,
+      entries: live.entries.map(deepCloneEntry),
+      wallets,
+      transactions,
+      ledgerFlow: { issued, applied, expired },
+    };
+  }
+
+  exportReport(accountId: string, format: 'csv' | 'json'): string {
+    const report = this.printReport(accountId);
+    if (format === 'json') {
+      return JSON.stringify(report, null, 2);
+    }
+    return creditReportToCsv(report);
+  }
+
+  // ─── Audit trail (paginated queries) ───────────────────────────────────
+
+  getAuditTrail(query: CreditAuditQuery): CreditAuditPage {
+    const now = this.now();
+    const projected = this.projectExpiry(this.ensureAccount(query.accountId), now);
+    let entries = projected.entries.slice();
+
+    if (query.fromTime !== undefined) {
+      const from = query.fromTime;
+      entries = entries.filter((e) => e.timestamp >= from);
+    }
+    if (query.toTime !== undefined) {
+      const to = query.toTime;
+      entries = entries.filter((e) => e.timestamp <= to);
+    }
+    if (query.kinds && query.kinds.length > 0) {
+      const allowed = new Set<CreditEntryKind>(query.kinds);
+      entries = entries.filter((e) => allowed.has(e.kind));
+    }
+
+    entries.sort((a, b) => b.timestamp - a.timestamp);
+
+    const offset = Math.max(0, query.offset ?? 0);
+    const limit = Math.max(1, query.limit ?? 100);
+    const page = entries.slice(offset, offset + limit);
+    return {
+      entries: page.map(deepCloneEntry),
+      totalEntries: entries.length,
+      hasMore: offset + limit < entries.length,
+      nextOffset: offset + limit < entries.length ? offset + limit : null,
+    };
+  }
+}
+
+export const creditService = new CreditService();
+
+// ─── free helpers ───────────────────────────────────────────────────────────
+
+function computeSummary(acc: CreditAccount, now: number): AccountCreditSummary {
+  const available = availableOf(acc, now);
+  const lifetime = {
+    issue: 0,
+    apply: 0,
+    transferIn: 0,
+    transferOut: 0,
+    expire: 0,
+  };
+  const consumptionLatencies: number[] = [];
+  for (const entry of acc.entries) {
+    if (entry.kind === 'issue') lifetime.issue += entry.amount;
+    if (entry.kind === 'apply') {
+      lifetime.apply += -entry.amount;
+      const issue = findMatchingIssue(acc.entries, entry);
+      if (issue) {
+        consumptionLatencies.push((entry.timestamp - issue.timestamp) / ONE_DAY_SECS);
+      }
+    }
+    if (entry.kind === 'transfer_in') lifetime.transferIn += entry.amount;
+    if (entry.kind === 'transfer_out') lifetime.transferOut += -entry.amount;
+    if (entry.kind === 'expire') lifetime.expire += -entry.amount;
+  }
+
+  const expiringByTimeBucket = {
+    expires_within_7d: 0,
+    expires_within_30d: 0,
+    no_expiry: 0,
+  };
+  for (const lot of acc.lots) {
+    if (lot.remaining <= 0) continue;
+    if (!lot.expiresAt) {
+      expiringByTimeBucket.no_expiry += lot.remaining;
+      continue;
+    }
+    const days = Math.ceil((lot.expiresAt - now) / ONE_DAY_SECS);
+    if (days <= 7) expiringByTimeBucket.expires_within_7d += lot.remaining;
+    else if (days <= 30) expiringByTimeBucket.expires_within_30d += lot.remaining;
+    else expiringByTimeBucket.no_expiry += lot.remaining;
+  }
+
+  return {
+    accountId: acc.accountId,
+    balance: acc.balance,
+    availableBalance: available,
+    totalIssued: lifetime.issue,
+    totalApplied: lifetime.apply,
+    totalTransferredIn: lifetime.transferIn,
+    totalTransferredOut: lifetime.transferOut,
+    totalExpired: lifetime.expire,
+    expiringByTimeBucket,
+    averageConsumptionDays:
+      consumptionLatencies.length === 0
+        ? 0
+        : consumptionLatencies.reduce((s, n) => s + n, 0) / consumptionLatencies.length,
+  };
+}
+
+function findMatchingIssue(
+  entries: { kind: CreditEntryKind; amount: number; timestamp: number }[],
+  apply: { kind: CreditEntryKind; amount: number; timestamp: number }
+): { kind: CreditEntryKind; amount: number; timestamp: number } | undefined {
+  // Best-effort: the latest `issue` for the same account that occurred before this apply.
+  let candidate: { kind: CreditEntryKind; amount: number; timestamp: number } | undefined;
+  for (const e of entries) {
+    if (e.kind === 'issue' && e.amount > 0 && e.timestamp <= apply.timestamp) {
+      candidate = e;
+    }
+  }
+  return candidate;
+}
+
+export function creditReportToCsv(report: CreditReport): string {
+  const rows: string[] = [];
+  rows.push('# Credit Report');
+  rows.push(`# account_id,${csvEscape(report.accountId)}`);
+  rows.push(`# generated_at,${new Date(report.generatedAt * 1_000).toISOString()}`);
+  rows.push(
+    `# totals,issued=${report.ledgerFlow.issued},applied=${report.ledgerFlow.applied},expired=${report.ledgerFlow.expired}`
+  );
+
+  rows.push('section,entries');
+  rows.push(['entry_id', 'kind', 'amount', 'timestamp', 'iso_time', 'reason', 'counterparty'].join(','));
+  for (const e of report.entries) {
+    rows.push(
+      [
+        e.id,
+        e.kind,
+        e.amount,
+        e.timestamp,
+        new Date(e.timestamp * 1_000).toISOString(),
+        csvEscape(e.reason),
+        csvEscape(e.counterparty ?? ''),
+      ].join(',')
+    );
+  }
+
+  if (report.wallets.length > 0) {
+    rows.push('section,wallets');
+    rows.push(
+      [
+        'wallet_id',
+        'account_id',
+        'subscription_id',
+        'currency',
+        'balance',
+        'total_deposited',
+        'total_withdrawn',
+        'created_at',
+        'updated_at',
+      ].join(',')
+    );
+    for (const w of report.wallets) {
+      rows.push(
+        [
+          w.id,
+          csvEscape(w.accountId),
+          csvEscape(w.subscriptionId),
+          w.currency,
+          w.balance,
+          w.totalDeposited,
+          w.totalWithdrawn,
+          new Date(w.createdAt * 1_000).toISOString(),
+          new Date(w.updatedAt * 1_000).toISOString(),
+        ].join(',')
+      );
+    }
+  }
+
+  if (report.transactions.length > 0) {
+    rows.push('section,wallet_transactions');
+    rows.push(
+      [
+        'tx_id',
+        'wallet_id',
+        'kind',
+        'amount',
+        'balance_after',
+        'invoice_id',
+        'timestamp',
+        'iso_time',
+      ].join(',')
+    );
+    for (const t of report.transactions) {
+      rows.push(
+        [
+          t.id,
+          t.walletId,
+          t.kind,
+          t.amount,
+          t.balanceAfter,
+          t.invoiceId ?? '',
+          t.timestamp,
+          new Date(t.timestamp * 1_000).toISOString(),
+        ].join(',')
+      );
+    }
+  }
+
+  return rows.join('\n');
+}
+
+function csvEscape(value: string): string {
+  if (value.includes(',') || value.includes('"') || value.includes('\n')) {
+    return `"${value.replace(/"/g, '""')}"`;
+  }
+  return value;
+}
+
+export { ONE_DAY_SECS, ONE_HOUR_SECS };
diff --git a/backend/services/billing/creditTypes.ts b/backend/services/billing/creditTypes.ts
new file mode 100644
index 00000000..fca33fa1
--- /dev/null
+++ b/backend/services/billing/creditTypes.ts
@@ -0,0 +1,220 @@
+/**
+ * Credit system types — shared between the backend `CreditService` and any
+ * downstream code that needs to reason about credit balances, audit trails,
+ * analytics or reporting.
+ *
+ * This module prefers the ledger model (lots + transactions + balance) which
+ * matches the on-chain `subtrackr-credit` Soroban contract. The web app uses a
+ * higher-level `CreditNote` projection (DRAFT/ISSUED/PARTIALLY_APPLIED/APPLIED
+ * etc.) — that projection is materialised on demand inside `CreditService` so
+ * there is no separate source of truth.
+ */
+
+// ─── Core ledger model (source of truth) ────────────────────────────────────
+
+export type ExpirationPolicy =
+  | { kind: 'never' }
+  | { kind: 'after_secs'; seconds: number };
+
+export interface CreditLot {
+  /** Monotonically-increasing lot identifier. */
+  id: number;
+  /** Remaining, unconsumed amount of this lot. */
+  remaining: number;
+  /** Unix seconds when the lot was issued. */
+  issuedAt: number;
+  /** Unix seconds when the lot expires. `undefined` means it never expires. */
+  expiresAt?: number;
+}
+
+export type CreditEntryKind =
+  | 'issue'
+  | 'apply'
+  | 'transfer_in'
+  | 'transfer_out'
+  | 'expire'
+  | 'deposit'
+  | 'withdraw';
+
+/** A single immutable ledger entry. `amount` is signed (+/-). */
+export interface CreditEntry {
+  id: number;
+  kind: CreditEntryKind;
+  amount: number;
+  timestamp: number;
+  reason: string;
+  counterparty?: string;
+}
+
+/** Subscriber's complete credit account. */
+export interface CreditAccount {
+  accountId: string;
+  balance: number;
+  /** Available (unexpired) credit. Computed on read. */
+  available: number;
+  lots: CreditLot[];
+  entries: CreditEntry[];
+  expirationPolicy: ExpirationPolicy;
+}
+
+// ─── Prepayment wallet ──────────────────────────────────────────────────────
+
+export type PrepaymentTxKind = 'deposit' | 'withdraw' | 'drawdown';
+
+export interface PrepaymentTransaction {
+  id: number;
+  walletId: number;
+  kind: PrepaymentTxKind;
+  amount: number;
+  balanceAfter: number;
+  invoiceId?: string;
+  timestamp: number;
+}
+
+export interface PrepaymentWallet {
+  id: number;
+  accountId: string;
+  subscriptionId: string;
+  currency: string;
+  balance: number;
+  totalDeposited: number;
+  totalWithdrawn: number;
+  createdAt: number;
+  updatedAt: number;
+}
+
+// ─── Operation inputs / outputs ─────────────────────────────────────────────
+
+export interface IssueCreditInput {
+  accountId: string;
+  /** Admin/system actor that authorises the issuance. */
+  actor: string;
+  amount: number;
+  reason: string;
+  /** Optional explicit expiry; if absent, the account's policy decides. */
+  expiresAt?: number;
+}
+
+export interface ApplyCreditInput {
+  accountId: string;
+  subscriptionId: string;
+  /** The gross amount due on the invoice/charge. */
+  amountDue: number;
+}
+
+export interface ApplyCreditResult {
+  accountId: string;
+  subscriptionId: string;
+  applied: number;
+  remainingDue: number;
+  balanceAfter: number;
+}
+
+export interface TransferCreditInput {
+  fromAccountId: string;
+  toAccountId: string;
+  amount: number;
+  reason: string;
+}
+
+// ─── Analytics ──────────────────────────────────────────────────────────────
+
+export interface AccountCreditSummary {
+  accountId: string;
+  balance: number;
+  availableBalance: number;
+  totalIssued: number;
+  totalApplied: number;
+  totalTransferredIn: number;
+  totalTransferredOut: number;
+  totalExpired: number;
+  /** Sum of remaining amounts across lots that will expire in the future. */
+  expiringByTimeBucket: Record<'expires_within_7d' | 'expires_within_30d' | 'no_expiry', number>;
+  /** Average days from issuance to consumption, across applied lots. */
+  averageConsumptionDays: number;
+}
+
+export interface CreditBucketBreakdown {
+  totalActiveAccounts: number;
+  /**
+   * Total credit that would be outstanding if all past-due lots were
+   * immediately expired (committed-to-the-ledger view, including projected
+   * expiry). For the committed-only view (already-recorded expirations), use
+   * `totalOutstandingLiabilityCommitted`.
+   */
+  totalOutstandingLiability: number;
+  /**
+   * Committed outstanding liability — reflects the ledger as it stands
+   * (past-due lots not yet expired via `expireAccount` still count here).
+   */
+  totalOutstandingLiabilityCommitted: number;
+  totalIssuedAllTime: number;
+  totalAppliedAllTime: number;
+  /** Sum of `expire` ledger entries that have been recorded. */
+  totalExpiredAllTime: number;
+  /**
+   * Sum of past-due-but-not-yet-committed expirable credit. Useful to expose
+   * the "would-be breakage if we ran `expireAll` right now" gap on dashboards.
+   */
+  totalExpiredProjectedAllTime: number;
+  /** Issued / applied / expired amounts grouped by reason. */
+  issuanceByReason: Record<string, number>;
+}
+
+export interface CreditUsageTrendPoint {
+  /** Unix seconds, aligned to start of the bucket. */
+  timestamp: number;
+  issued: number;
+  applied: number;
+  /** Committed `expire` entries that landed in this bucket. */
+  expired: number;
+  /** Past-due lots whose expiry was realised at read-time. */
+  expiredProjected: number;
+  netIssuance: number;
+}
+
+export interface CreditExpiryForecast {
+  accountId: string;
+  amount: number;
+  expiresAt: number;
+  daysRemaining: number;
+}
+
+export interface TopAccount {
+  accountId: string;
+  balance: number;
+  availableBalance: number;
+  rank: number;
+}
+
+// ─── Reporting ──────────────────────────────────────────────────────────────
+
+export type ReportFormat = 'csv' | 'json';
+
+export interface CreditReport {
+  generatedAt: number;
+  accountId: string;
+  summary: AccountCreditSummary;
+  entries: CreditEntry[];
+  wallets: PrepaymentWallet[];
+  transactions: PrepaymentTransaction[];
+  /** Lifetime issuance → application → expiry chain. */
+  ledgerFlow: { issued: number; applied: number; expired: number };
+}
+
+export interface CreditAuditQuery {
+  accountId: string;
+  fromTime?: number;
+  toTime?: number;
+  kinds?: CreditEntryKind[];
+  /** Pagination — caller uses `limit` to bound response size. */
+  limit?: number;
+  offset?: number;
+}
+
+export interface CreditAuditPage {
+  entries: CreditEntry[];
+  totalEntries: number;
+  hasMore: boolean;
+  nextOffset: number | null;
+}
diff --git a/backend/services/billing/errors.ts b/backend/services/billing/errors.ts
index efbeea47..0b95e0f2 100644
--- a/backend/services/billing/errors.ts
+++ b/backend/services/billing/errors.ts
@@ -16,13 +16,16 @@ export const BillingErrorCode = {
   EXPORT_FAILED: 'BILL_EXPORT_FAILED' as ErrorCode,
   OVERAGE_EXCEEDED: 'BILL_OVERAGE_EXCEEDED' as ErrorCode,
   INVALID_PLAN: 'BILL_INVALID_PLAN' as ErrorCode,
+  // Credit-specific codes — kept here so HTTP handlers can map them to
+  // status codes without reaching into the service implementation.
+  CREDIT_INVALID_AMOUNT: 'BILL_CREDIT_INVALID_AMOUNT' as ErrorCode,
+  CREDIT_INSUFFICIENT: 'BILL_CREDIT_INSUFFICIENT' as ErrorCode,
+  CREDIT_SELF_TRANSFER: 'BILL_CREDIT_SELF_TRANSFER' as ErrorCode,
+  CREDIT_EXPIRED: 'BILL_CREDIT_EXPIRED' as ErrorCode,
+  WALLET_NOT_FOUND: 'BILL_WALLET_NOT_FOUND' as ErrorCode,
 } as const;
 
 export class BillingError extends DomainError {
-  constructor(code: ErrorCode, message: string, details?: Record<string, string>) {
-    super(code, message, details);
-  }
-
   static paymentFailed(subscriptionId: string, reason: string): BillingError {
     return new BillingError(
       BillingErrorCode.PAYMENT_FAILED,
@@ -46,4 +49,36 @@ export class BillingError extends DomainError {
       { subscriptionId, stage }
     );
   }
+
+  static creditInvalidAmount(reason: string): BillingError {
+    return new BillingError(
+      BillingErrorCode.CREDIT_INVALID_AMOUNT,
+      `Credit amount invalid: ${reason}`,
+      { reason }
+    );
+  }
+
+  static creditInsufficient(accountId: string, attempted: number, available: number): BillingError {
+    return new BillingError(
+      BillingErrorCode.CREDIT_INSUFFICIENT,
+      `Account ${accountId} has insufficient credit: requested ${attempted}, available ${available}`,
+      { accountId, attempted: String(attempted), available: String(available) }
+    );
+  }
+
+  static creditSelfTransfer(accountId: string): BillingError {
+    return new BillingError(
+      BillingErrorCode.CREDIT_SELF_TRANSFER,
+      `Account ${accountId} cannot transfer credit to itself`,
+      { accountId }
+    );
+  }
+
+  static walletNotFound(walletId: number): BillingError {
+    return new BillingError(
+      BillingErrorCode.WALLET_NOT_FOUND,
+      `Prepayment wallet ${walletId} not found`,
+      { walletId: String(walletId) }
+    );
+  }
 }
diff --git a/backend/services/billing/index.ts b/backend/services/billing/index.ts
index f2a4e51e..e7627b23 100644
--- a/backend/services/billing/index.ts
+++ b/backend/services/billing/index.ts
@@ -49,6 +49,30 @@ export {
   BackendPartnerService,
 } from './partnerService';
 export type { SplitConfiguration, PartnerPayoutSchedule } from '../../../src/types/partner';
+
+// Credit system — see creditService.ts for architectural notes.
+export { CreditService, creditService, creditReportToCsv } from './creditService';
+export type {
+  AccountCreditSummary,
+  ApplyCreditInput,
+  ApplyCreditResult,
+  CreditAccount,
+  CreditAuditPage,
+  CreditAuditQuery,
+  CreditBucketBreakdown,
+  CreditEntry,
+  CreditEntryKind,
+  CreditExpiryForecast,
+  CreditLot,
+  CreditReport,
+  CreditUsageTrendPoint,
+  ExpirationPolicy,
+  IssueCreditInput,
+  PrepaymentTransaction,
+  PrepaymentWallet,
+  TopAccount,
+  TransferCreditInput,
+} from './creditTypes';
 export type {
   IMeteringService,
   IPricingService,
@@ -56,6 +80,7 @@ export type {
   IDunningService,
   IAccountingExportService,
   IPartnerService,
+  ICreditService,
 } from './interfaces';
 export { BillingError, BillingErrorCode } from './errors';
 
diff --git a/backend/services/billing/interfaces.ts b/backend/services/billing/interfaces.ts
index b745d762..67633ec7 100644
--- a/backend/services/billing/interfaces.ts
+++ b/backend/services/billing/interfaces.ts
@@ -21,7 +21,25 @@ import {
   ReconciliationResult,
   TransactionType,
 } from './accountingExportService';
-import { SplitConfiguration, PartnerPayoutSchedule } from '../../../src/types/partner';
+import { SplitConfiguration } from '../../../src/types/partner';
+import type {
+  AccountCreditSummary,
+  ApplyCreditInput,
+  ApplyCreditResult,
+  CreditAccount,
+  CreditAuditPage,
+  CreditAuditQuery,
+  CreditBucketBreakdown,
+  CreditExpiryForecast,
+  CreditReport,
+  CreditUsageTrendPoint,
+  ExpirationPolicy,
+  IssueCreditInput,
+  PrepaymentTransaction,
+  PrepaymentWallet,
+  TopAccount,
+  TransferCreditInput,
+} from './creditTypes';
 
 export interface IMeteringService {
   recordUsage(metric: UsageMetric): Promise<UsageIngestResult>;