From 3d3e53b1feb0a7c8d5969907458ffc7237e1818a Mon Sep 17 00:00:00 2001
From: Itodo-S <itodosimonitodo1@gmail.com>
Date: Thu, 27 Aug 2026 11:12:28 +0100
Subject: [PATCH] feat: multi-chain billing, tiered overages, dunning retries,
 tenant invoice branding
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implements four assigned issues across the billing stack.

Closes #933 — multi-chain subscription management with unified billing
  * New src/services/multiChainSubscriptionService.ts: chain bindings per
    subscription, unified statements that convert every chain into one
    currency while keeping native token subtotals, and settlement planning
    with health-aware cross-chain failover.
  * Unpriced tokens are reported explicitly rather than counted as zero, and
    unpayable charges are marked blocked rather than dropped.
  * walletService gains getBalancesAcrossChains() (parallel, per-chain error
    isolation) and totalsBySymbol(), which keeps holdings separated by chain
    because the same symbol on two chains is not fungible.

Closes #934 — automated dunning with configurable retry strategies
  * dunningService did not compile: it referenced this.templates,
    this.recoveredEntries and this.getStrategy(), none of which existed, read
    stages off DunningConfiguration rather than off a RetryStrategy, used an
    undefined `strategy` in recordFailedCharge, and dereferenced a possibly
    undefined entry in recordSuccessfulCharge. All fixed.
  * Adds strategy resolution (A/B variant > failure-reason override > plan
    default > built-in) and four backoff policies: fixed, linear, exponential
    and exponential-with-jitter, plus a retryable flag for hard declines.
  * Jitter decorrelates the retry storm that follows a single upstream outage.
  * recoveryRate is now measured over closed outcomes only, so in-flight
    dunning no longer depresses the rate.

Closes #935 — usage-based billing with metered pricing and tiered overages
  * New backend/services/billing/metering.ts: pure rating engine supporting
    flat, graduated, volume and package pricing, with included-unit proration,
    minimum charges and spend caps.
  * contracts/metering gains register_tiered_meter(), quote_usage(), a
    PricingModel/PriceTier ladder and per-tier charge breakdowns. The existing
    register_meter() is unchanged and now registers a flat meter.
  * Off-chain and on-chain rating implement identical arithmetic;
    toContractTiers() converts between the two tier encodings.
  * Also removes a dead subtrackr_types::CoreError import and a From impl that
    collided with contracterror's blanket TryFrom impls — the metering crate
    did not compile before this.

Closes #937 — invoice customization with per-tenant branding
  * Branding was a single platform-wide default. Adds a per-tenant registry to
    invoiceStore with field-by-field resolution (tenant > platform > fallback),
    per-tenant templates and numbering prefixes, and validation that reports
    every problem at once.
  * invoiceCustomizationService now renders real, deterministic HTML and a
    plain-text alternative instead of logging to the console.
  * All branding is attacker-supplied, so text is escaped, colours are pattern
    checked, logo/website URLs are scheme restricted (javascript: dropped),
    font stacks are stripped of CSS metacharacters and logo widths are clamped.

Testing
  * 163 new TypeScript tests and 13 new contract tests, all passing.
  * backend/services/billing: 47 -> 146 passing.
  * src/store + src/services: 501 -> 565 passing.
  * Pre-existing failures are unchanged in both suites; no regressions.
  * cargo fmt and clippy -D warnings are clean for subtrackr-metering.

Docs: DUNNING_RETRY_STRATEGIES.md, USAGE_BASED_BILLING.md,
INVOICE_BRANDING.md, MULTI_CHAIN_SUBSCRIPTIONS.md.
---
 .../billing/__tests__/dunningService.test.ts  | 394 ++++++++++++++++
 .../invoiceCustomizationService.test.ts       | 302 ++++++++++++
 .../billing/__tests__/metering.test.ts        | 391 ++++++++++++++++
 backend/services/billing/dunningService.ts    | 383 ++++++++++-----
 backend/services/billing/index.ts             |  39 +-
 backend/services/billing/interfaces.ts        |  18 +-
 .../billing/invoiceCustomizationService.ts    | 342 ++++++++++++--
 backend/services/billing/metering.ts          | 441 ++++++++++++++++++
 contracts/metering/src/lib.rs                 | 129 +++--
 contracts/metering/src/metering.rs            | 213 +++++++++
 contracts/metering/src/test.rs                | 362 +++++++++++++-
 docs/DUNNING_RETRY_STRATEGIES.md              | 125 +++++
 docs/INVOICE_BRANDING.md                      | 116 +++++
 docs/MULTI_CHAIN_SUBSCRIPTIONS.md             | 134 ++++++
 docs/USAGE_BASED_BILLING.md                   | 168 +++++++
 .../multiChainSubscriptionService.test.ts     | 313 +++++++++++++
 .../__tests__/walletMultiChain.test.ts        | 113 +++++
 src/services/multiChainSubscriptionService.ts | 396 ++++++++++++++++
 src/services/walletService.ts                 |  70 +++
 src/store/__tests__/invoiceBranding.test.ts   | 296 ++++++++++++
 src/store/invoiceStore.ts                     | 240 +++++++++-
 src/types/invoice.ts                          |  41 ++
 22 files changed, 4827 insertions(+), 199 deletions(-)
 create mode 100644 backend/services/billing/__tests__/dunningService.test.ts
 create mode 100644 backend/services/billing/__tests__/invoiceCustomizationService.test.ts
 create mode 100644 backend/services/billing/__tests__/metering.test.ts
 create mode 100644 backend/services/billing/metering.ts
 create mode 100644 docs/DUNNING_RETRY_STRATEGIES.md
 create mode 100644 docs/INVOICE_BRANDING.md
 create mode 100644 docs/MULTI_CHAIN_SUBSCRIPTIONS.md
 create mode 100644 docs/USAGE_BASED_BILLING.md
 create mode 100644 src/services/__tests__/multiChainSubscriptionService.test.ts
 create mode 100644 src/services/__tests__/walletMultiChain.test.ts
 create mode 100644 src/services/multiChainSubscriptionService.ts
 create mode 100644 src/store/__tests__/invoiceBranding.test.ts

diff --git a/backend/services/billing/__tests__/dunningService.test.ts b/backend/services/billing/__tests__/dunningService.test.ts
new file mode 100644
index 00000000..c4baae79
--- /dev/null
+++ b/backend/services/billing/__tests__/dunningService.test.ts
@@ -0,0 +1,394 @@
+import { DunningService } from '../dunningService';
+import type { RetryStrategy } from '../../../../src/types/dunning';
+import { DEFAULT_DUNNING_STAGES } from '../../../../src/types/dunning';
+
+const strategy = (overrides: Partial<RetryStrategy> = {}): RetryStrategy => ({
+  stages: DEFAULT_DUNNING_STAGES,
+  maxRetries: 3,
+  retryIntervalHours: 1,
+  warnAfterFailures: 3,
+  suspendAfterDays: 3,
+  cancelAfterDays: 7,
+  communicationChannels: ['email', 'push'],
+  ...overrides,
+});
+
+const ONE_HOUR_MS = 3_600_000;
+
+let service: DunningService;
+
+beforeEach(() => {
+  service = new DunningService();
+});
+
+describe('strategy resolution', () => {
+  it('falls back to the built-in strategy for an unconfigured plan', () => {
+    const resolved = service.getStrategy('plan_unknown', 'default');
+    expect(resolved.stages).toEqual(DEFAULT_DUNNING_STAGES);
+  });
+
+  it('uses the plan default once configured', () => {
+    const custom = strategy({ maxRetries: 9 });
+    service.configurePlan('plan_a', { defaultStrategy: custom });
+    expect(service.getStrategy('plan_a', 'default').maxRetries).toBe(9);
+  });
+
+  it('prefers a failure-reason override over the plan default', () => {
+    service.configurePlan('plan_a', {
+      defaultStrategy: strategy({ maxRetries: 3 }),
+      strategies: { expired_card: strategy({ maxRetries: 1 }) },
+    });
+    expect(service.getStrategy('plan_a', 'default').maxRetries).toBe(3);
+    expect(service.getStrategy('plan_a', 'expired_card').maxRetries).toBe(1);
+  });
+
+  it('prefers an active A/B variant over everything else', () => {
+    service.configurePlan('plan_a', {
+      defaultStrategy: strategy({ maxRetries: 3 }),
+      strategies: { expired_card: strategy({ maxRetries: 1 }) },
+    });
+    service.configureABTest('plan_a', true, [
+      { id: 'aggressive', weight: 1, strategy: strategy({ maxRetries: 7 }) },
+    ]);
+    expect(service.getStrategy('plan_a', 'expired_card', 'aggressive').maxRetries).toBe(7);
+  });
+
+  it('ignores a variant when the A/B test is disabled', () => {
+    service.configurePlan('plan_a', { defaultStrategy: strategy({ maxRetries: 3 }) });
+    service.configureABTest('plan_a', false, [
+      { id: 'aggressive', weight: 1, strategy: strategy({ maxRetries: 7 }) },
+    ]);
+    expect(service.getStrategy('plan_a', 'default', 'aggressive').maxRetries).toBe(3);
+  });
+
+  it('keeps the existing default when a later configurePlan omits it', () => {
+    service.configurePlan('plan_a', { defaultStrategy: strategy({ maxRetries: 5 }) });
+    service.configurePlan('plan_a', { strategies: {} });
+    expect(service.getStrategy('plan_a', 'default').maxRetries).toBe(5);
+  });
+});
+
+describe('configurable retry backoff', () => {
+  it('repeats the base delay under a fixed policy', () => {
+    service.configureRetrySchedule({
+      failureType: 'card_declined',
+      baseDelayHours: 4,
+      backoffPolicy: 'fixed',
+      maxDelayHours: 100,
+    });
+    expect(service.calculateRetryDelay('card_declined', 1)).toBe(4);
+    expect(service.calculateRetryDelay('card_declined', 5)).toBe(4);
+  });
+
+  it('scales linearly with the attempt number under a linear policy', () => {
+    service.configureRetrySchedule({
+      failureType: 'card_declined',
+      baseDelayHours: 2,
+      backoffPolicy: 'linear',
+      maxDelayHours: 100,
+    });
+    expect(service.calculateRetryDelay('card_declined', 1)).toBe(2);
+    expect(service.calculateRetryDelay('card_declined', 3)).toBe(6);
+  });
+
+  it('compounds under an exponential policy', () => {
+    service.configureRetrySchedule({
+      failureType: 'card_declined',
+      baseDelayHours: 1,
+      backoffMultiplier: 3,
+      backoffPolicy: 'exponential',
+      maxDelayHours: 1_000,
+    });
+    expect(service.calculateRetryDelay('card_declined', 1)).toBe(1);
+    expect(service.calculateRetryDelay('card_declined', 3)).toBe(9);
+  });
+
+  it('caps the delay at maxDelayHours', () => {
+    service.configureRetrySchedule({
+      failureType: 'card_declined',
+      baseDelayHours: 1,
+      backoffMultiplier: 10,
+      backoffPolicy: 'exponential',
+      maxDelayHours: 12,
+    });
+    expect(service.calculateRetryDelay('card_declined', 8)).toBe(12);
+  });
+
+  it('keeps jittered delays inside the configured envelope', () => {
+    service.configureRetrySchedule({
+      failureType: 'network_error',
+      baseDelayHours: 4,
+      backoffMultiplier: 1,
+      backoffPolicy: 'exponential_jitter',
+      jitterRatio: 0.25,
+      maxDelayHours: 10,
+    });
+    const samples = Array.from({ length: 200 }, () =>
+      service.calculateRetryDelay('network_error', 1)
+    );
+    for (const sample of samples) {
+      expect(sample).toBeGreaterThanOrEqual(3);
+      expect(sample).toBeLessThanOrEqual(5);
+    }
+    // Jitter must actually spread the values, otherwise it is not doing its job.
+    expect(new Set(samples).size).toBeGreaterThan(1);
+  });
+
+  it('treats attempt 0 as the first attempt', () => {
+    service.configureRetrySchedule({
+      failureType: 'card_declined',
+      baseDelayHours: 3,
+      backoffPolicy: 'linear',
+      maxDelayHours: 100,
+    });
+    expect(service.calculateRetryDelay('card_declined', 0)).toBe(3);
+  });
+
+  it('merges a partial schedule update onto the existing one', () => {
+    service.configureRetrySchedule({ failureType: 'expired_card', maxRetries: 9 });
+    const schedule = service.getRetrySchedule('expired_card');
+    expect(schedule.maxRetries).toBe(9);
+    // Untouched fields keep their defaults.
+    expect(schedule.baseDelayHours).toBe(24);
+    expect(schedule.backoffPolicy).toBe('fixed');
+  });
+
+  it('falls back to the unknown schedule for an unregistered failure type', () => {
+    const schedule = service.getRetrySchedule('not_a_real_type' as never);
+    expect(schedule.failureType).toBe('unknown');
+  });
+});
+
+describe('dunning lifecycle', () => {
+  const start = () => service.startDunning('sub_1', 'subscriber_1', 'merchant_1', 'plan_a');
+
+  it('opens an entry at the first stage of the resolved strategy', () => {
+    service.configurePlan('plan_a', { defaultStrategy: strategy() });
+    const entry = start();
+    expect(entry.currentStage).toBe('retry');
+    expect(entry.failedAttempts).toBe(0);
+    expect(service.getDunningEntry('sub_1')).toBe(entry);
+  });
+
+  it('is idempotent — starting twice returns the same entry', () => {
+    expect(start()).toBe(start());
+    expect(service.listActiveDunning()).toHaveLength(1);
+  });
+
+  it('schedules the next retry using the configured backoff', () => {
+    service.configurePlan('plan_a', { defaultStrategy: strategy() });
+    service.configureRetrySchedule({
+      failureType: 'network_error',
+      baseDelayHours: 2,
+      backoffPolicy: 'fixed',
+      maxRetries: 10,
+      maxDelayHours: 100,
+    });
+    start();
+    const before = Date.now();
+    const entry = service.recordFailedCharge('sub_1', 'network_error')!;
+    expect(entry.failedAttempts).toBe(1);
+    expect(entry.currentStage).toBe('retry');
+    expect(entry.nextActionAt - before).toBeGreaterThanOrEqual(2 * ONE_HOUR_MS - 50);
+  });
+
+  it('advances to the next stage once the stage attempt budget is spent', () => {
+    service.configurePlan('plan_a', { defaultStrategy: strategy() });
+    service.configureRetrySchedule({ failureType: 'network_error', maxRetries: 99 });
+    start();
+    // The default `retry` stage allows 3 attempts.
+    service.recordFailedCharge('sub_1', 'network_error');
+    service.recordFailedCharge('sub_1', 'network_error');
+    const entry = service.recordFailedCharge('sub_1', 'network_error')!;
+    expect(entry.currentStage).toBe('warn');
+    expect(entry.failedAttempts).toBe(0);
+  });
+
+  it('escalates immediately for a failure type marked non-retryable', () => {
+    service.configurePlan('plan_a', { defaultStrategy: strategy() });
+    service.configureRetrySchedule({ failureType: 'expired_card', retryable: false });
+    start();
+    const entry = service.recordFailedCharge('sub_1', 'expired_card')!;
+    expect(entry.currentStage).toBe('warn');
+  });
+
+  it('sends a stage communication when it escalates', () => {
+    service.configurePlan('plan_a', { defaultStrategy: strategy() });
+    service.configureRetrySchedule({ failureType: 'expired_card', retryable: false });
+    start();
+    service.recordFailedCharge('sub_1', 'expired_card');
+    const comms = service.getCommunications('sub_1');
+    expect(comms).toHaveLength(1);
+    expect(comms[0].stage).toBe('warn');
+    expect(comms[0].templateId).toBe('payment_warning');
+    // The channel comes from the resolved strategy, not a hardcoded default.
+    expect(comms[0].channel).toBe('email');
+  });
+
+  it('lands on cancel once the ladder is exhausted', () => {
+    service.configurePlan('plan_a', {
+      defaultStrategy: strategy({ stages: [{ stage: 'retry', delayHours: 1, maxAttempts: 1, templateId: 'payment_retry' }] }),
+    });
+    service.configureRetrySchedule({ failureType: 'unknown', maxRetries: 99 });
+    start();
+    const entry = service.recordFailedCharge('sub_1', 'unknown')!;
+    expect(entry.currentStage).toBe('cancel');
+  });
+
+  it('does not record failures against a paused entry', () => {
+    start();
+    service.pauseDunning('sub_1');
+    expect(service.recordFailedCharge('sub_1')).toBeNull();
+  });
+
+  it('reschedules on resume', () => {
+    service.configurePlan('plan_a', { defaultStrategy: strategy() });
+    start();
+    service.pauseDunning('sub_1');
+    const resumed = service.resumeDunning('sub_1')!;
+    expect(resumed.isPaused).toBe(false);
+    expect(resumed.nextActionAt).toBeGreaterThan(Date.now());
+  });
+
+  it('returns null for lifecycle calls on an unknown subscription', () => {
+    expect(service.recordFailedCharge('nope')).toBeNull();
+    expect(service.recordSuccessfulCharge('nope')).toBeNull();
+    expect(service.pauseDunning('nope')).toBeNull();
+    expect(service.resumeDunning('nope')).toBeNull();
+    expect(service.overrideStage('nope', 'warn')).toBeNull();
+  });
+
+  it('closes the entry on a successful charge', () => {
+    start();
+    service.recordFailedCharge('sub_1');
+    const recovered = service.recordSuccessfulCharge('sub_1');
+    expect(recovered).not.toBeNull();
+    expect(service.getDunningEntry('sub_1')).toBeUndefined();
+    expect(service.listRecoveredDunning('merchant_1')).toHaveLength(1);
+  });
+
+  it('lists only entries whose next action is due', () => {
+    service.configurePlan('plan_a', { defaultStrategy: strategy() });
+    start();
+    expect(service.getProcessableEntries()).toHaveLength(0);
+    service.overrideStage('sub_1', 'retry');
+    const entry = service.getDunningEntry('sub_1')!;
+    entry.nextActionAt = Date.now() - 1_000;
+    expect(service.getProcessableEntries()).toHaveLength(1);
+  });
+
+  it('scopes active listings by merchant', () => {
+    service.startDunning('sub_1', 'subscriber_1', 'merchant_1', 'plan_a');
+    service.startDunning('sub_2', 'subscriber_2', 'merchant_2', 'plan_a');
+    expect(service.listActiveDunning('merchant_1')).toHaveLength(1);
+    expect(service.listActiveDunning()).toHaveLength(2);
+  });
+});
+
+describe('analytics', () => {
+  beforeEach(() => {
+    service.configurePlan('plan_a', { defaultStrategy: strategy() });
+    service.configureRetrySchedule({ failureType: 'network_error', maxRetries: 99 });
+  });
+
+  it('counts retries by failure type', () => {
+    service.startDunning('sub_1', 'subscriber_1', 'merchant_1', 'plan_a');
+    service.recordFailedCharge('sub_1', 'network_error');
+    service.recordFailedCharge('sub_1', 'card_declined');
+    const analytics = service.getRetryAnalytics('merchant_1');
+    expect(analytics.totalRetries).toBe(2);
+    expect(analytics.retriesByFailureType.network_error).toBe(1);
+    expect(analytics.retriesByFailureType.card_declined).toBe(1);
+    expect(analytics.successfulRetries).toBe(0);
+  });
+
+  it('scopes analytics to a merchant', () => {
+    service.startDunning('sub_1', 'subscriber_1', 'merchant_1', 'plan_a');
+    service.startDunning('sub_2', 'subscriber_2', 'merchant_2', 'plan_a');
+    service.recordFailedCharge('sub_1', 'network_error');
+    service.recordFailedCharge('sub_2', 'network_error');
+    expect(service.getRetryAnalytics('merchant_1').totalRetries).toBe(1);
+    expect(service.getRetryAnalytics().totalRetries).toBe(2);
+  });
+
+  it('measures recovery rate over closed outcomes only', () => {
+    service.startDunning('sub_1', 'subscriber_1', 'merchant_1', 'plan_a');
+    service.startDunning('sub_2', 'subscriber_2', 'merchant_1', 'plan_a');
+    service.recordFailedCharge('sub_1', 'network_error');
+    service.recordSuccessfulCharge('sub_1');
+    service.overrideStage('sub_2', 'cancel');
+
+    const analytics = service.getAnalytics('merchant_1');
+    expect(analytics.totalRecovered).toBe(1);
+    expect(analytics.totalLost).toBe(1);
+    expect(analytics.recoveryRate).toBe(50);
+  });
+
+  it('reports zeroes rather than NaN with no history', () => {
+    const analytics = service.getAnalytics('merchant_none');
+    expect(analytics.recoveryRate).toBe(0);
+    expect(analytics.averageDaysToRecovery).toBe(0);
+    expect(analytics.totalActiveDunning).toBe(0);
+    expect(service.getRetryAnalytics('merchant_none').successRate).toBe(0);
+  });
+
+  it('breaks active entries down by stage', () => {
+    service.startDunning('sub_1', 'subscriber_1', 'merchant_1', 'plan_a');
+    service.startDunning('sub_2', 'subscriber_2', 'merchant_1', 'plan_a');
+    service.overrideStage('sub_2', 'suspend');
+    const { stageBreakdown } = service.getAnalytics('merchant_1');
+    expect(stageBreakdown.retry).toBe(1);
+    expect(stageBreakdown.suspend).toBe(1);
+  });
+});
+
+describe('communication templates', () => {
+  it('ships the default template set', () => {
+    expect(service.getTemplates().map((t) => t.id)).toEqual([
+      'payment_retry',
+      'payment_warning',
+      'service_suspension',
+      'subscription_cancellation',
+    ]);
+  });
+
+  it('adds, updates, and removes templates', () => {
+    service.addTemplate({
+      id: 'custom',
+      stage: 'warn',
+      subject: 'Subject',
+      body: 'Body',
+      pushTitle: 'Title',
+      pushBody: 'Push',
+      actionLabel: 'Go',
+      actionUrl: '/go',
+    });
+    expect(service.getTemplates()).toHaveLength(5);
+
+    service.updateTemplate('custom', { subject: 'Updated' });
+    expect(service.getTemplates().find((t) => t.id === 'custom')?.subject).toBe('Updated');
+
+    service.removeTemplate('custom');
+    expect(service.getTemplates()).toHaveLength(4);
+  });
+
+  it('does not add the same template id twice', () => {
+    const existing = service.getTemplates()[0];
+    service.addTemplate(existing);
+    expect(service.getTemplates()).toHaveLength(4);
+  });
+});
+
+describe('reset', () => {
+  it('clears entries, history, and configuration', () => {
+    service.configurePlan('plan_a', { defaultStrategy: strategy({ maxRetries: 9 }) });
+    service.startDunning('sub_1', 'subscriber_1', 'merchant_1', 'plan_a');
+    service.recordFailedCharge('sub_1');
+    service.reset();
+
+    expect(service.listActiveDunning()).toHaveLength(0);
+    expect(service.listRecoveredDunning()).toHaveLength(0);
+    expect(service.getConfiguration('plan_a')).toBeUndefined();
+    expect(service.getRetryAnalytics().totalRetries).toBe(0);
+  });
+});
diff --git a/backend/services/billing/__tests__/invoiceCustomizationService.test.ts b/backend/services/billing/__tests__/invoiceCustomizationService.test.ts
new file mode 100644
index 00000000..2dd94aa3
--- /dev/null
+++ b/backend/services/billing/__tests__/invoiceCustomizationService.test.ts
@@ -0,0 +1,302 @@
+import {
+  FALLBACK_BRANDING,
+  InvoiceCustomizationService,
+  escapeHtml,
+  normalizeBranding,
+} from '../invoiceCustomizationService';
+import { useInvoiceStore } from '../../../../src/store/invoiceStore';
+import { DEFAULT_INVOICE_CONFIG, InvoiceStatus } from '../../../../src/types/invoice';
+import type { Invoice } from '../../../../src/types/invoice';
+
+// expo-notifications has no native module under Jest; ts-jest hoists jest.mock
+// above the imports at transform time.
+jest.mock('../../../../src/services/notificationService', () => ({
+  presentLocalNotification: jest.fn(() => Promise.resolve()),
+}));
+
+const makeInvoice = (overrides: Partial<Invoice> = {}): Invoice => ({
+  id: 'inv-1',
+  invoiceNumber: 'INV-000001',
+  subscriptionId: 'sub-1',
+  subscriptionName: 'Pro Plan',
+  merchantName: 'Platform Merchant',
+  lineItems: [
+    {
+      description: 'Pro Plan — January',
+      quantity: 1,
+      unitPrice: 100,
+      currency: 'USD',
+      exchangeRate: 1_000_000,
+      taxRateBps: 0,
+      lineTotal: 100,
+    },
+  ],
+  tax: 10,
+  subtotal: 100,
+  total: 110,
+  dueDate: new Date('2026-02-01T00:00:00.000Z'),
+  status: InvoiceStatus.DRAFT,
+  currency: 'USD',
+  region: 'GLOBAL',
+  exchangeRate: 1_000_000,
+  period: {
+    start: new Date('2026-01-01T00:00:00.000Z'),
+    end: new Date('2026-02-01T00:00:00.000Z'),
+  },
+  createdAt: new Date('2026-01-01T00:00:00.000Z'),
+  updatedAt: new Date('2026-01-01T00:00:00.000Z'),
+  ...overrides,
+});
+
+beforeEach(() => {
+  useInvoiceStore.setState({
+    invoices: [],
+    config: { ...DEFAULT_INVOICE_CONFIG },
+    nextSequence: 1,
+    isLoading: false,
+    error: null,
+    brandingProfiles: {},
+    templates: [
+      { id: 'tpl-1', name: 'Standard', layout: 'standard' },
+      { id: 'tpl-2', name: 'Modern', layout: 'modern' },
+      { id: 'tpl-3', name: 'Minimalist', layout: 'minimalist' },
+    ],
+  });
+});
+
+describe('escapeHtml', () => {
+  it('escapes every character that could break out of markup', () => {
+    expect(escapeHtml(`<script>"x"&'y'</script>`)).toBe(
+      '&lt;script&gt;&quot;x&quot;&amp;&#39;y&#39;&lt;/script&gt;'
+    );
+  });
+
+  it('renders null and undefined as an empty string', () => {
+    expect(escapeHtml(null)).toBe('');
+    expect(escapeHtml(undefined)).toBe('');
+  });
+});
+
+describe('normalizeBranding', () => {
+  it('fills every unset field from the fallback palette', () => {
+    expect(normalizeBranding(undefined)).toMatchObject(FALLBACK_BRANDING);
+  });
+
+  it('keeps valid tenant values', () => {
+    expect(normalizeBranding({ primaryColor: '#abc' }).primaryColor).toBe('#abc');
+  });
+
+  it('replaces an invalid colour with the fallback', () => {
+    expect(normalizeBranding({ primaryColor: 'red; background:url(x)' }).primaryColor).toBe(
+      FALLBACK_BRANDING.primaryColor
+    );
+  });
+
+  it('drops a logo URL with an unsafe scheme', () => {
+    expect(normalizeBranding({ logoUrl: 'javascript:alert(1)' }).logoUrl).toBeUndefined();
+  });
+
+  it('keeps http(s) and data:image logos', () => {
+    expect(normalizeBranding({ logoUrl: 'https://cdn.example.com/l.png' }).logoUrl).toBe(
+      'https://cdn.example.com/l.png'
+    );
+    expect(normalizeBranding({ logoUrl: 'data:image/png;base64,AA' }).logoUrl).toBe(
+      'data:image/png;base64,AA'
+    );
+  });
+
+  it('clamps the logo width into the renderable range', () => {
+    expect(normalizeBranding({ logoWidth: 5 }).logoWidth).toBe(24);
+    expect(normalizeBranding({ logoWidth: 9_999 }).logoWidth).toBe(320);
+    expect(normalizeBranding({}).logoWidth).toBe(140);
+  });
+
+  it('strips characters that would let a font stack close its declaration', () => {
+    expect(normalizeBranding({ fontFamily: 'Inter";}body{display:none' }).fontFamily).toBe(
+      'Interbodydisplaynone'
+    );
+  });
+
+  it('falls back when a font stack sanitizes to nothing', () => {
+    expect(normalizeBranding({ fontFamily: '";{}' }).fontFamily).toBe(
+      FALLBACK_BRANDING.fontFamily
+    );
+  });
+});
+
+describe('renderInvoice', () => {
+  it('renders under the platform defaults when no tenant is set', () => {
+    const rendered = InvoiceCustomizationService.renderInvoice(makeInvoice());
+    expect(rendered.layout).toBe('standard');
+    expect(rendered.templateId).toBe('tpl-1');
+    expect(rendered.html).toContain('Platform Merchant');
+    expect(rendered.branding.primaryColor).toBe(FALLBACK_BRANDING.primaryColor);
+  });
+
+  it("applies the tenant's branding, template, and display name", () => {
+    useInvoiceStore.getState().setTenantBranding('tenant-a', {
+      displayName: 'Acme Inc.',
+      branding: { primaryColor: '#ff0000', logoUrl: 'https://cdn.example.com/acme.png' },
+      templateId: 'tpl-2',
+    });
+
+    const rendered = InvoiceCustomizationService.renderInvoice(
+      makeInvoice({ tenantId: 'tenant-a' })
+    );
+    expect(rendered.layout).toBe('modern');
+    expect(rendered.html).toContain('Acme Inc.');
+    expect(rendered.html).toContain('#ff0000');
+    expect(rendered.html).toContain('https://cdn.example.com/acme.png');
+  });
+
+  it('renders each layout differently', () => {
+    const store = useInvoiceStore.getState();
+    const htmls = (['tpl-1', 'tpl-2', 'tpl-3'] as const).map((templateId) => {
+      store.setTenantBranding('t', { branding: {}, templateId });
+      return InvoiceCustomizationService.renderInvoice(makeInvoice({ tenantId: 't' })).html;
+    });
+    expect(new Set(htmls).size).toBe(3);
+  });
+
+  it('is deterministic — the same input renders byte-identical markup', () => {
+    const invoice = makeInvoice();
+    expect(InvoiceCustomizationService.renderInvoice(invoice).html).toBe(
+      InvoiceCustomizationService.renderInvoice(invoice).html
+    );
+  });
+
+  it('escapes a tenant display name containing markup', () => {
+    useInvoiceStore.getState().setTenantBranding('tenant-x', {
+      displayName: '<script>alert(1)</script>',
+      branding: {},
+    });
+    const html = InvoiceCustomizationService.renderInvoice(
+      makeInvoice({ tenantId: 'tenant-x' })
+    ).html;
+    expect(html).not.toContain('<script>alert(1)</script>');
+    expect(html).toContain('&lt;script&gt;');
+  });
+
+  it('escapes markup in line item descriptions', () => {
+    const html = InvoiceCustomizationService.renderInvoice(
+      makeInvoice({
+        lineItems: [
+          {
+            description: '<img src=x onerror=alert(1)>',
+            quantity: 1,
+            unitPrice: 1,
+            currency: 'USD',
+            exchangeRate: 1,
+            taxRateBps: 0,
+            lineTotal: 1,
+          },
+        ],
+      })
+    ).html;
+    expect(html).not.toContain('<img src=x');
+    expect(html).toContain('&lt;img src=x');
+  });
+
+  it('renders a placeholder row when there are no line items', () => {
+    const rendered = InvoiceCustomizationService.renderInvoice(makeInvoice({ lineItems: [] }));
+    expect(rendered.html).toContain('No line items');
+  });
+
+  it('renders totals in the invoice currency', () => {
+    const rendered = InvoiceCustomizationService.renderInvoice(
+      makeInvoice({ currency: 'XLM', subtotal: 100, tax: 10, total: 110 })
+    );
+    expect(rendered.html).toContain('110.00 XLM');
+    expect(rendered.text).toContain('Total: 110.00 XLM');
+  });
+
+  it('lets a per-invoice branding override outrank the tenant profile', () => {
+    useInvoiceStore
+      .getState()
+      .setTenantBranding('tenant-a', { branding: { primaryColor: '#ff0000' } });
+    const rendered = InvoiceCustomizationService.renderInvoice(
+      makeInvoice({ tenantId: 'tenant-a', branding: { primaryColor: '#00ff00' } })
+    );
+    expect(rendered.branding.primaryColor).toBe('#00ff00');
+  });
+
+  it('renders the footer contact block only when it is configured', () => {
+    expect(InvoiceCustomizationService.renderInvoice(makeInvoice()).html).not.toContain(
+      '<footer>'
+    );
+
+    useInvoiceStore.getState().setTenantBranding('tenant-a', {
+      branding: {
+        footerText: 'Payable within 14 days',
+        supportEmail: 'billing@acme.example',
+        websiteUrl: 'https://acme.example',
+      },
+    });
+    const html = InvoiceCustomizationService.renderInvoice(
+      makeInvoice({ tenantId: 'tenant-a' })
+    ).html;
+    expect(html).toContain('Payable within 14 days');
+    expect(html).toContain('mailto:billing@acme.example');
+    expect(html).toContain('https://acme.example');
+  });
+
+  it('produces a plain-text alternative alongside the HTML', () => {
+    const rendered = InvoiceCustomizationService.renderInvoice(makeInvoice());
+    expect(rendered.text).toContain('Invoice INV-000001');
+    expect(rendered.text).toContain('Pro Plan — January x1: 100.00 USD');
+    expect(rendered.text).not.toContain('<');
+  });
+
+  it('renders an unparseable date as a dash rather than "Invalid Date"', () => {
+    const rendered = InvoiceCustomizationService.renderInvoice(
+      makeInvoice({ dueDate: new Date('nonsense') })
+    );
+    expect(rendered.html).toContain('Due: —');
+  });
+});
+
+describe('previewForTenant', () => {
+  it('reflects the current profile, ignoring branding frozen on the sample', () => {
+    useInvoiceStore
+      .getState()
+      .setTenantBranding('tenant-a', { branding: { primaryColor: '#123456' } });
+    const preview = InvoiceCustomizationService.previewForTenant(
+      'tenant-a',
+      makeInvoice({ branding: { primaryColor: '#ffffff' } })
+    );
+    expect(preview.branding.primaryColor).toBe('#123456');
+  });
+});
+
+describe('generateInvoicePdf', () => {
+  it('returns a document URL alongside the rendered markup', async () => {
+    const { url, rendered } = await InvoiceCustomizationService.generateInvoicePdf(makeInvoice());
+    expect(url).toBe('https://cdn.subtrackr.app/invoices/inv-1.pdf');
+    expect(rendered.html).toContain('INV-000001');
+  });
+
+  it('encodes an invoice id that needs escaping', async () => {
+    const { url } = await InvoiceCustomizationService.generateInvoicePdf(
+      makeInvoice({ id: 'inv/1 2' })
+    );
+    expect(url).toBe('https://cdn.subtrackr.app/invoices/inv%2F1%202.pdf');
+  });
+});
+
+describe('deliverInvoice', () => {
+  it('renders, sends, and marks the invoice sent', async () => {
+    useInvoiceStore.setState({ invoices: [makeInvoice()] });
+    const result = await InvoiceCustomizationService.deliverInvoice('inv-1', 'payer@example.com');
+
+    expect(result.delivered).toBe(true);
+    expect(result.documentUrl).toContain('inv-1.pdf');
+    expect(useInvoiceStore.getState().invoices[0].status).toBe(InvoiceStatus.SENT);
+    expect(useInvoiceStore.getState().invoices[0].recipientEmail).toBe('payer@example.com');
+  });
+
+  it('reports a missing invoice instead of throwing', async () => {
+    const result = await InvoiceCustomizationService.deliverInvoice('nope', 'payer@example.com');
+    expect(result.delivered).toBe(false);
+    expect(result.error).toBe('Invoice not found');
+  });
+});
diff --git a/backend/services/billing/__tests__/metering.test.ts b/backend/services/billing/__tests__/metering.test.ts
new file mode 100644
index 00000000..f84a98aa
--- /dev/null
+++ b/backend/services/billing/__tests__/metering.test.ts
@@ -0,0 +1,391 @@
+import {
+  buildOverageLadder,
+  marginalUnitPrice,
+  quoteMeter,
+  rateMeter,
+  rateUsage,
+  toContractTiers,
+  validateMeterPricingPlan,
+  validateOverageTiers,
+  type MeterPricingPlan,
+  type OverageTier,
+} from '../metering';
+
+const period = (days = 30) => {
+  const start = new Date('2026-01-01T00:00:00.000Z');
+  const end = new Date(start.getTime() + days * 86_400_000);
+  return { start, end };
+};
+
+const flatPlan = (overrides: Partial<MeterPricingPlan> = {}): MeterPricingPlan => ({
+  metric: 'api_calls',
+  model: 'flat',
+  includedUnits: 0,
+  unitPrice: 2,
+  ...overrides,
+});
+
+describe('validateOverageTiers', () => {
+  it('accepts an ascending ladder terminated by an unbounded tier', () => {
+    expect(() =>
+      validateOverageTiers([
+        { upToUnits: 100, unitPrice: 5 },
+        { upToUnits: 1_000, unitPrice: 3 },
+        { upToUnits: null, unitPrice: 1 },
+      ])
+    ).not.toThrow();
+  });
+
+  it('accepts a fully bounded ladder', () => {
+    expect(() =>
+      validateOverageTiers([
+        { upToUnits: 100, unitPrice: 5 },
+        { upToUnits: 1_000, unitPrice: 3 },
+      ])
+    ).not.toThrow();
+  });
+
+  it('rejects descending bounds', () => {
+    expect(() =>
+      validateOverageTiers([
+        { upToUnits: 1_000, unitPrice: 1 },
+        { upToUnits: 100, unitPrice: 2 },
+      ])
+    ).toThrow(/strictly ascend/);
+  });
+
+  it('rejects duplicate bounds', () => {
+    expect(() =>
+      validateOverageTiers([
+        { upToUnits: 100, unitPrice: 1 },
+        { upToUnits: 100, unitPrice: 2 },
+      ])
+    ).toThrow(/strictly ascend/);
+  });
+
+  it('rejects an unbounded tier that is not last', () => {
+    expect(() =>
+      validateOverageTiers([
+        { upToUnits: null, unitPrice: 1 },
+        { upToUnits: 100, unitPrice: 2 },
+      ])
+    ).toThrow(/must be the last tier/);
+  });
+
+  it('rejects negative prices and fees', () => {
+    expect(() => validateOverageTiers([{ upToUnits: null, unitPrice: -1 }])).toThrow(
+      /unitPrice/
+    );
+    expect(() =>
+      validateOverageTiers([{ upToUnits: null, unitPrice: 1, flatFee: -5 }])
+    ).toThrow(/flatFee/);
+  });
+});
+
+describe('validateMeterPricingPlan', () => {
+  it('requires a ladder for every non-flat model', () => {
+    for (const model of ['graduated', 'volume', 'package'] as const) {
+      expect(() => validateMeterPricingPlan(flatPlan({ model }))).toThrow(/defines no tiers/);
+    }
+  });
+
+  it('allows a flat plan with no ladder', () => {
+    expect(() => validateMeterPricingPlan(flatPlan())).not.toThrow();
+  });
+
+  it('rejects a minimum above the maximum', () => {
+    expect(() =>
+      validateMeterPricingPlan(flatPlan({ minimumCharge: 100, maximumCharge: 10 }))
+    ).toThrow(/minimumCharge above its maximumCharge/);
+  });
+
+  it('rejects a negative included allowance', () => {
+    expect(() => validateMeterPricingPlan(flatPlan({ includedUnits: -1 }))).toThrow(
+      /includedUnits/
+    );
+  });
+});
+
+describe('rateMeter — flat', () => {
+  it('bills every unit past the included allowance', () => {
+    const line = rateMeter(flatPlan({ includedUnits: 100, unitPrice: 2 }), 150);
+    expect(line.billableUnits).toBe(50);
+    expect(line.amount).toBe(100);
+    expect(line.tierLines).toHaveLength(1);
+  });
+
+  it('bills nothing inside the included allowance', () => {
+    const line = rateMeter(flatPlan({ includedUnits: 100 }), 100);
+    expect(line.billableUnits).toBe(0);
+    expect(line.amount).toBe(0);
+    expect(line.tierLines).toHaveLength(0);
+  });
+
+  it('rejects a negative unit count', () => {
+    expect(() => rateMeter(flatPlan(), -1)).toThrow(/negative or non-finite/);
+  });
+});
+
+describe('rateMeter — graduated', () => {
+  const plan: MeterPricingPlan = {
+    metric: 'api_calls',
+    model: 'graduated',
+    includedUnits: 100,
+    unitPrice: 1,
+    tiers: [
+      { upToUnits: 1_000, unitPrice: 3 },
+      { upToUnits: null, unitPrice: 1 },
+    ],
+  };
+
+  it('prices each slice at its own band rate', () => {
+    // 1_600 used - 100 free = 1_500 billable -> 1_000 @ 3 + 500 @ 1.
+    const line = rateMeter(plan, 1_600);
+    expect(line.billableUnits).toBe(1_500);
+    expect(line.amount).toBe(3_500);
+    expect(line.tierLines.map((t) => [t.units, t.amount])).toEqual([
+      [1_000, 3_000],
+      [500, 500],
+    ]);
+  });
+
+  it('stays inside the first band when the overage is small', () => {
+    const line = rateMeter(plan, 300);
+    expect(line.tierLines).toHaveLength(1);
+    expect(line.amount).toBe(600);
+  });
+
+  it('adds a band flat fee once when the band is entered', () => {
+    const withFee: MeterPricingPlan = {
+      ...plan,
+      tiers: [{ upToUnits: null, unitPrice: 2, flatFee: 50 }],
+    };
+    // 20 used - 100 free = 0 billable, so no fee is charged.
+    expect(rateMeter(withFee, 20).amount).toBe(0);
+    // 110 used - 100 free = 10 billable -> 10 * 2 + 50.
+    expect(rateMeter(withFee, 110).amount).toBe(70);
+  });
+
+  it('bills overflow past a truncated ladder at the meter unit price', () => {
+    const truncated: MeterPricingPlan = {
+      metric: 'api_calls',
+      model: 'graduated',
+      includedUnits: 0,
+      unitPrice: 7,
+      tiers: [{ upToUnits: 10, unitPrice: 1 }],
+    };
+    // 10 @ 1 = 10, then the remaining 5 fall back to the meter rate: 5 @ 7 = 35.
+    expect(rateMeter(truncated, 15).amount).toBe(45);
+  });
+});
+
+describe('rateMeter — volume', () => {
+  const plan: MeterPricingPlan = {
+    metric: 'api_calls',
+    model: 'volume',
+    includedUnits: 0,
+    unitPrice: 0,
+    tiers: [
+      { upToUnits: 100, unitPrice: 10 },
+      { upToUnits: 1_000, unitPrice: 6 },
+      { upToUnits: null, unitPrice: 4 },
+    ],
+  };
+
+  it('prices every unit at the rate of the band the total lands in', () => {
+    expect(rateMeter(plan, 500).amount).toBe(3_000);
+  });
+
+  it('re-prices the whole volume when a boundary is crossed', () => {
+    expect(rateMeter(plan, 100).amount).toBe(1_000);
+    // One more unit drops the whole bill into the cheaper band.
+    expect(rateMeter(plan, 101).amount).toBe(606);
+  });
+
+  it('uses the unbounded band past the top bound', () => {
+    expect(rateMeter(plan, 5_000).amount).toBe(20_000);
+  });
+});
+
+describe('rateMeter — package', () => {
+  const plan: MeterPricingPlan = {
+    metric: 'sms',
+    model: 'package',
+    includedUnits: 0,
+    unitPrice: 0,
+    // Blocks of 1_000 units at 25 per started block.
+    tiers: [{ upToUnits: 1_000, unitPrice: 0, flatFee: 25 }],
+  };
+
+  it('charges whole blocks, rounding partial blocks up', () => {
+    expect(rateMeter(plan, 1).amount).toBe(25);
+    expect(rateMeter(plan, 1_000).amount).toBe(25);
+    expect(rateMeter(plan, 1_001).amount).toBe(50);
+    expect(rateMeter(plan, 2_001).amount).toBe(75);
+  });
+
+  it('charges nothing for zero usage', () => {
+    expect(rateMeter(plan, 0).amount).toBe(0);
+  });
+});
+
+describe('rateMeter — proration', () => {
+  const plan = flatPlan({ includedUnits: 1_000, unitPrice: 2 });
+
+  it('scales the included allowance by the active fraction of the period', () => {
+    const line = rateMeter(plan, 600, 0.5);
+    expect(line.includedUnits).toBe(500);
+    expect(line.billableUnits).toBe(100);
+    expect(line.amount).toBe(200);
+  });
+
+  it('never scales consumed units', () => {
+    expect(rateMeter(plan, 2_000, 0.5).unitsUsed).toBe(2_000);
+  });
+
+  it('clamps the factor into [0, 1]', () => {
+    expect(rateMeter(plan, 0, -3).includedUnits).toBe(0);
+    expect(rateMeter(plan, 0, 99).includedUnits).toBe(1_000);
+  });
+});
+
+describe('rateUsage', () => {
+  const plans: MeterPricingPlan[] = [
+    {
+      metric: 'api_calls',
+      model: 'graduated',
+      includedUnits: 100,
+      unitPrice: 1,
+      tiers: [
+        { upToUnits: 1_000, unitPrice: 3 },
+        { upToUnits: null, unitPrice: 1 },
+      ],
+    },
+    { metric: 'gb_egress', model: 'flat', includedUnits: 0, unitPrice: 5 },
+  ];
+
+  it('rates every meter and sums the bill', () => {
+    const bill = rateUsage({
+      subscriptionId: 'sub_1',
+      period: period(),
+      usageByMetric: { api_calls: 1_600, gb_egress: 4 },
+      plans,
+    });
+    expect(bill.lines).toHaveLength(2);
+    expect(bill.subtotal).toBe(3_520);
+    expect(bill.total).toBe(3_520);
+    expect(bill.currency).toBe('USD');
+  });
+
+  it('treats a metric with no recorded usage as zero', () => {
+    const bill = rateUsage({
+      subscriptionId: 'sub_1',
+      period: period(),
+      usageByMetric: {},
+      plans,
+    });
+    expect(bill.total).toBe(0);
+    expect(bill.lines.every((l) => l.billableUnits === 0)).toBe(true);
+  });
+
+  it('tops the bill up to a minimum charge', () => {
+    const bill = rateUsage({
+      subscriptionId: 'sub_1',
+      period: period(),
+      usageByMetric: { gb_egress: 1 },
+      plans: [{ metric: 'gb_egress', model: 'flat', includedUnits: 0, unitPrice: 5, minimumCharge: 50 }],
+    });
+    expect(bill.subtotal).toBe(5);
+    expect(bill.minimumAdjustment).toBe(45);
+    expect(bill.total).toBe(50);
+  });
+
+  it('trims the bill down to a spend cap', () => {
+    const bill = rateUsage({
+      subscriptionId: 'sub_1',
+      period: period(),
+      usageByMetric: { gb_egress: 1_000 },
+      plans: [{ metric: 'gb_egress', model: 'flat', includedUnits: 0, unitPrice: 5, maximumCharge: 100 }],
+    });
+    expect(bill.subtotal).toBe(5_000);
+    expect(bill.maximumAdjustment).toBe(-4_900);
+    expect(bill.total).toBe(100);
+  });
+
+  it('rejects an inverted billing period', () => {
+    const { start, end } = period();
+    expect(() =>
+      rateUsage({
+        subscriptionId: 'sub_1',
+        period: { start: end, end: start },
+        usageByMetric: {},
+        plans,
+      })
+    ).toThrow(/ends before it starts/);
+  });
+
+  it('prefers an explicit currency over the plan currency', () => {
+    const bill = rateUsage({
+      subscriptionId: 'sub_1',
+      period: period(),
+      usageByMetric: {},
+      plans: [{ ...plans[1], currency: 'EUR' }],
+      currency: 'XLM',
+    });
+    expect(bill.currency).toBe('XLM');
+  });
+});
+
+describe('quoteMeter and marginalUnitPrice', () => {
+  const plan: MeterPricingPlan = {
+    metric: 'api_calls',
+    model: 'graduated',
+    includedUnits: 100,
+    unitPrice: 1,
+    tiers: [
+      { upToUnits: 1_000, unitPrice: 3 },
+      { upToUnits: null, unitPrice: 1 },
+    ],
+  };
+
+  it('quotes a hypothetical volume', () => {
+    expect(quoteMeter(plan, 1_600).amount).toBe(3_500);
+  });
+
+  it('reports the marginal cost of the next unit', () => {
+    // Inside the free allowance the next unit is free.
+    expect(marginalUnitPrice(plan, 50)).toBe(0);
+    // In the first overage band it costs the band rate.
+    expect(marginalUnitPrice(plan, 500)).toBe(3);
+    // Past the band boundary it drops to the cheaper rate.
+    expect(marginalUnitPrice(plan, 2_000)).toBe(1);
+  });
+});
+
+describe('toContractTiers', () => {
+  it('encodes the unbounded tier as 0 for the Soroban contract', () => {
+    const tiers: OverageTier[] = [
+      { upToUnits: 1_000, unitPrice: 3 },
+      { upToUnits: null, unitPrice: 1, flatFee: 7 },
+    ];
+    expect(toContractTiers(tiers)).toEqual([
+      { up_to_units: 1_000, unit_price: 3, flat_fee: 0 },
+      { up_to_units: 0, unit_price: 1, flat_fee: 7 },
+    ]);
+  });
+
+  it('validates before encoding', () => {
+    expect(() =>
+      toContractTiers([
+        { upToUnits: 1_000, unitPrice: 1 },
+        { upToUnits: 100, unitPrice: 2 },
+      ])
+    ).toThrow(/strictly ascend/);
+  });
+});
+
+describe('buildOverageLadder', () => {
+  it('produces a single unbounded band', () => {
+    expect(buildOverageLadder(4)).toEqual([{ upToUnits: null, unitPrice: 4 }]);
+  });
+});
diff --git a/backend/services/billing/dunningService.ts b/backend/services/billing/dunningService.ts
index 666d83ea..1e3f5f2b 100644
--- a/backend/services/billing/dunningService.ts
+++ b/backend/services/billing/dunningService.ts
@@ -33,12 +33,29 @@ export type FailureType =
   | 'auth_required'
   | 'unknown';
 
+/**
+ * Shape of the delay curve applied between retries of the same stage.
+ *
+ * - `fixed`       — every attempt waits `baseDelayHours`.
+ * - `linear`      — attempt N waits `baseDelayHours * N`.
+ * - `exponential` — attempt N waits `baseDelayHours * multiplier^(N-1)`.
+ * - `exponential_jitter` — as `exponential`, with a random ± `jitterRatio`
+ *   spread so a batch of failures caused by one upstream outage does not
+ *   retry in lockstep.
+ */
+export type BackoffPolicy = 'fixed' | 'linear' | 'exponential' | 'exponential_jitter';
+
 export interface RetryScheduleConfig {
   failureType: FailureType;
   baseDelayHours: number;
   maxRetries: number;
   backoffMultiplier: number;
   maxDelayHours: number;
+  backoffPolicy: BackoffPolicy;
+  /** Fraction of the computed delay used as jitter spread, e.g. 0.2 = ±20%. */
+  jitterRatio: number;
+  /** When false the failure type is treated as terminal and is never retried. */
+  retryable: boolean;
 }
 
 export interface RetryAnalytics {
@@ -53,29 +70,80 @@ export interface RetryAnalytics {
   averageTimeToRecovery: number;
 }
 
+const FAILURE_TYPES: FailureType[] = [
+  'insufficient_funds',
+  'card_declined',
+  'expired_card',
+  'network_error',
+  'processing_error',
+  'auth_required',
+  'unknown',
+];
+
 const DEFAULT_RETRY_SCHEDULES: RetryScheduleConfig[] = [
-  { failureType: 'insufficient_funds', baseDelayHours: 1, maxRetries: 5, backoffMultiplier: 2, maxDelayHours: 48 },
-  { failureType: 'card_declined', baseDelayHours: 2, maxRetries: 3, backoffMultiplier: 3, maxDelayHours: 72 },
-  { failureType: 'expired_card', baseDelayHours: 24, maxRetries: 2, backoffMultiplier: 1, maxDelayHours: 24 },
-  { failureType: 'network_error', baseDelayHours: 0.5, maxRetries: 6, backoffMultiplier: 1.5, maxDelayHours: 12 },
-  { failureType: 'processing_error', baseDelayHours: 1, maxRetries: 4, backoffMultiplier: 2, maxDelayHours: 24 },
-  { failureType: 'auth_required', baseDelayHours: 0.25, maxRetries: 3, backoffMultiplier: 1, maxDelayHours: 1 },
-  { failureType: 'unknown', baseDelayHours: 1, maxRetries: 3, backoffMultiplier: 2, maxDelayHours: 24 },
+  { failureType: 'insufficient_funds', baseDelayHours: 1, maxRetries: 5, backoffMultiplier: 2, maxDelayHours: 48, backoffPolicy: 'exponential_jitter', jitterRatio: 0.2, retryable: true },
+  { failureType: 'card_declined', baseDelayHours: 2, maxRetries: 3, backoffMultiplier: 3, maxDelayHours: 72, backoffPolicy: 'exponential', jitterRatio: 0, retryable: true },
+  // A card that has expired will keep failing until the payer acts, so a flat
+  // daily nudge beats an escalating backoff here.
+  { failureType: 'expired_card', baseDelayHours: 24, maxRetries: 2, backoffMultiplier: 1, maxDelayHours: 24, backoffPolicy: 'fixed', jitterRatio: 0, retryable: true },
+  { failureType: 'network_error', baseDelayHours: 0.5, maxRetries: 6, backoffMultiplier: 1.5, maxDelayHours: 12, backoffPolicy: 'exponential_jitter', jitterRatio: 0.3, retryable: true },
+  { failureType: 'processing_error', baseDelayHours: 1, maxRetries: 4, backoffMultiplier: 2, maxDelayHours: 24, backoffPolicy: 'exponential', jitterRatio: 0, retryable: true },
+  { failureType: 'auth_required', baseDelayHours: 0.25, maxRetries: 3, backoffMultiplier: 1, maxDelayHours: 1, backoffPolicy: 'linear', jitterRatio: 0, retryable: true },
+  { failureType: 'unknown', baseDelayHours: 1, maxRetries: 3, backoffMultiplier: 2, maxDelayHours: 24, backoffPolicy: 'exponential', jitterRatio: 0, retryable: true },
 ];
 
+/** Failure types share names with `FailureReason` only partially; map them across. */
+const FAILURE_TYPE_TO_REASON: Record<FailureType, FailureReason> = {
+  insufficient_funds: 'insufficient_funds',
+  card_declined: 'default',
+  expired_card: 'expired_card',
+  network_error: 'network',
+  processing_error: 'default',
+  auth_required: 'default',
+  unknown: 'default',
+};
+
+const emptyStageRecord = (): Record<DunningStage, number> => ({
+  retry: 0,
+  warn: 0,
+  suspend: 0,
+  cancel: 0,
+});
+
+const emptyFailureTypeRecord = (): Record<FailureType, number> =>
+  FAILURE_TYPES.reduce((acc, type) => {
+    acc[type] = 0;
+    return acc;
+  }, {} as Record<FailureType, number>);
+
+const FALLBACK_STRATEGY: RetryStrategy = {
+  stages: DEFAULT_DUNNING_STAGES,
+  maxRetries: 3,
+  retryIntervalHours: 1,
+  warnAfterFailures: 3,
+  suspendAfterDays: 3,
+  cancelAfterDays: 7,
+  communicationChannels: ['email', 'push'],
+};
+
+interface RetryHistoryRecord {
+  subscriptionId: string;
+  merchantId: string;
+  failureType: FailureType;
+  attempt: number;
+  success: boolean;
+  timestamp: number;
+  delayHours: number;
+}
+
 export class DunningService {
   private entries = new Map<string, DunningEntry>();
   private configurations = new Map<string, DunningConfiguration>();
   private communicationLog = new Map<string, DunningCommunication[]>();
+  private templates: DunningCommunicationTemplate[] = [...DUNNING_TEMPLATES];
   private retrySchedules: RetryScheduleConfig[] = [...DEFAULT_RETRY_SCHEDULES];
-  private retryHistory: Array<{
-    subscriptionId: string;
-    failureType: FailureType;
-    attempt: number;
-    success: boolean;
-    timestamp: number;
-    delayHours: number;
-  }> = [];
+  private retryHistory: RetryHistoryRecord[] = [];
+  private recoveredEntries: DunningEntry[] = [];
   private progressiveEngine: ProgressiveDunningEngine;
 
   constructor(engine: ProgressiveDunningEngine = progressiveDunningEngine) {
@@ -84,16 +152,9 @@ export class DunningService {
 
   configurePlan(planId: string, config: Partial<DunningConfiguration>): DunningConfiguration {
     const existing = this.configurations.get(planId);
-    
-    const defaultStrategy: RetryStrategy = config.defaultStrategy ?? existing?.defaultStrategy ?? {
-      stages: DEFAULT_DUNNING_STAGES,
-      maxRetries: 3,
-      retryIntervalHours: 1,
-      warnAfterFailures: 3,
-      suspendAfterDays: 3,
-      cancelAfterDays: 7,
-      communicationChannels: ['email', 'push'],
-    };
+
+    const defaultStrategy: RetryStrategy =
+      config.defaultStrategy ?? existing?.defaultStrategy ?? { ...FALLBACK_STRATEGY };
 
     const merged: DunningConfiguration = {
       planId,
@@ -101,7 +162,7 @@ export class DunningService {
       strategies: config.strategies ?? existing?.strategies ?? {},
       abTestConfig: config.abTestConfig ?? existing?.abTestConfig,
     };
-    
+
     this.configurations.set(planId, merged);
     return merged;
   }
@@ -120,6 +181,22 @@ export class DunningService {
     return this.configurations.get(planId);
   }
 
+  /**
+   * Resolves the retry strategy in force for a subscription, most specific
+   * first: A/B variant → failure-reason override → plan default → built-in.
+   */
+  getStrategy(planId: string, failureReason: FailureReason, abTestVariant?: string): RetryStrategy {
+    const config = this.configurations.get(planId);
+    if (!config) return FALLBACK_STRATEGY;
+
+    if (abTestVariant && config.abTestConfig?.enabled) {
+      const variant = config.abTestConfig.variants.find((v) => v.id === abTestVariant);
+      if (variant) return variant.strategy;
+    }
+
+    return config.strategies?.[failureReason] ?? config.defaultStrategy ?? FALLBACK_STRATEGY;
+  }
+
   configureRetrySchedule(schedule: Partial<RetryScheduleConfig> & { failureType: FailureType }): void {
     const existingIdx = this.retrySchedules.findIndex((s) => s.failureType === schedule.failureType);
     const existing = existingIdx >= 0 ? this.retrySchedules[existingIdx] : undefined;
@@ -130,6 +207,9 @@ export class DunningService {
       maxRetries: schedule.maxRetries ?? existing?.maxRetries ?? 3,
       backoffMultiplier: schedule.backoffMultiplier ?? existing?.backoffMultiplier ?? 2,
       maxDelayHours: schedule.maxDelayHours ?? existing?.maxDelayHours ?? 24,
+      backoffPolicy: schedule.backoffPolicy ?? existing?.backoffPolicy ?? 'exponential',
+      jitterRatio: schedule.jitterRatio ?? existing?.jitterRatio ?? 0,
+      retryable: schedule.retryable ?? existing?.retryable ?? true,
     };
 
     if (existingIdx >= 0) {
@@ -142,15 +222,46 @@ export class DunningService {
   getRetrySchedule(failureType: FailureType): RetryScheduleConfig {
     return (
       this.retrySchedules.find((s) => s.failureType === failureType) ??
-      this.retrySchedules.find((s) => s.failureType === 'unknown')!
+      this.retrySchedules.find((s) => s.failureType === 'unknown') ??
+      DEFAULT_RETRY_SCHEDULES[DEFAULT_RETRY_SCHEDULES.length - 1]
     );
   }
 
+  listRetrySchedules(): RetryScheduleConfig[] {
+    return this.retrySchedules.map((s) => ({ ...s }));
+  }
+
+  /** Delay in hours before attempt `attemptNumber` (1-based), capped at `maxDelayHours`. */
   calculateRetryDelay(failureType: FailureType, attemptNumber: number): number {
     const schedule = this.getRetrySchedule(failureType);
-    const delay =
-      schedule.baseDelayHours * Math.pow(schedule.backoffMultiplier, attemptNumber - 1);
-    return Math.min(delay, schedule.maxDelayHours);
+    const attempt = Math.max(1, attemptNumber);
+
+    let delay: number;
+    switch (schedule.backoffPolicy) {
+      case 'fixed':
+        delay = schedule.baseDelayHours;
+        break;
+      case 'linear':
+        delay = schedule.baseDelayHours * attempt;
+        break;
+      case 'exponential':
+      case 'exponential_jitter':
+      default:
+        delay = schedule.baseDelayHours * Math.pow(schedule.backoffMultiplier, attempt - 1);
+        break;
+    }
+
+    delay = Math.min(delay, schedule.maxDelayHours);
+
+    if (schedule.backoffPolicy === 'exponential_jitter' && schedule.jitterRatio > 0) {
+      const spread = delay * schedule.jitterRatio;
+      // Jitter both directions, then clamp so the delay stays inside the
+      // configured envelope.
+      delay = delay + (Math.random() * 2 - 1) * spread;
+      delay = Math.min(Math.max(delay, 0), schedule.maxDelayHours);
+    }
+
+    return delay;
   }
 
   startDunning(
@@ -228,12 +339,13 @@ export class DunningService {
     const { entry: updated, event } = this.progressiveEngine.applyEscalation(entry, rule);
     this.entries.set(subscriptionId, updated);
 
+    const strategy = this.getStrategy(updated.planId, updated.failureReason, updated.abTestVariant);
     const stageConfig =
-      this.configurations.get(updated.planId)?.stages.find((s) => s.stage === updated.currentStage) ??
+      strategy.stages.find((s) => s.stage === updated.currentStage) ??
       DEFAULT_DUNNING_STAGES.find((s) => s.stage === updated.currentStage);
 
     if (stageConfig) {
-      this.sendCommunication(updated, stageConfig);
+      this.sendCommunication(updated, stageConfig, strategy);
     }
 
     return { entry: updated, event };
@@ -250,7 +362,7 @@ export class DunningService {
     const entry = this.entries.get(subscriptionId);
     if (!entry || entry.isPaused) return null;
 
-    const config = this.configurations.get(entry.planId);
+    const strategy = this.getStrategy(entry.planId, entry.failureReason, entry.abTestVariant);
     const schedule = this.getRetrySchedule(failureType);
     const now_ts = now();
 
@@ -260,65 +372,81 @@ export class DunningService {
     entry.lastAttemptAt = now_ts;
     entry.updatedAt = now_ts;
 
-    this.retryHistory.push({
-      subscriptionId,
-      failureType,
-      attempt: entry.failedAttempts,
-      success: false,
-      timestamp: now_ts,
-      delayHours: 0,
-    });
+    const stages = strategy.stages.length > 0 ? strategy.stages : DEFAULT_DUNNING_STAGES;
+    const currentStageIndex = stages.findIndex((s) => s.stage === entry.currentStage);
+    const stageConfig = currentStageIndex >= 0 ? stages[currentStageIndex] : undefined;
 
-    const shouldAdvanceStage = (): boolean => {
-      if (entry.failedAttempts >= schedule.maxRetries) return true;
-      const currentStageIndex = config
-        ? config.stages.findIndex((s) => s.stage === entry.currentStage)
-        : -1;
-      if (currentStageIndex < 0 || !config) return false;
-      const stageConfig = config.stages[currentStageIndex];
-      return entry.failedAttempts >= stageConfig.maxAttempts;
-    };
+    // A non-retryable failure (e.g. a hard decline) skips the retry budget and
+    // escalates on the first occurrence.
+    const budgetExhausted =
+      !schedule.retryable ||
+      entry.failedAttempts >= schedule.maxRetries ||
+      (stageConfig !== undefined && entry.failedAttempts >= stageConfig.maxAttempts);
 
-    if (shouldAdvanceStage() && config) {
-      const currentStageIndex = config.stages.findIndex((s) => s.stage === entry.currentStage);
+    let delayHours = 0;
+
+    if (budgetExhausted) {
       const nextStageIndex = currentStageIndex + 1;
-      if (nextStageIndex < strategy.stages.length) {
-        const nextStage = strategy.stages[nextStageIndex];
+      if (currentStageIndex >= 0 && nextStageIndex < stages.length) {
+        const nextStage = stages[nextStageIndex];
         entry.currentStage = nextStage.stage;
         entry.failedAttempts = 0;
-        entry.nextActionAt = now_ts + nextStage.delayHours * ONE_HOUR_MS;
-        this.sendCommunication(entry, nextStage);
+        delayHours = nextStage.delayHours;
+        entry.nextActionAt = now_ts + delayHours * ONE_HOUR_MS;
+        this.progressiveEngine.trackStageEntry(entry, now_ts);
+        this.sendCommunication(entry, nextStage, strategy);
       } else {
         entry.currentStage = 'cancel';
-        entry.nextActionAt = now_ts + 24 * ONE_HOUR_MS;
+        entry.failedAttempts = 0;
+        delayHours = 24;
+        entry.nextActionAt = now_ts + delayHours * ONE_HOUR_MS;
+        this.progressiveEngine.trackStageEntry(entry, now_ts);
+        const cancelStage =
+          stages.find((s) => s.stage === 'cancel') ??
+          DEFAULT_DUNNING_STAGES.find((s) => s.stage === 'cancel');
+        if (cancelStage) {
+          this.sendCommunication(entry, cancelStage, strategy);
+        }
       }
     } else {
-      const delay = this.calculateRetryDelay(failureType, entry.failedAttempts);
-      entry.nextActionAt = now_ts + delay * ONE_HOUR_MS;
+      delayHours = this.calculateRetryDelay(failureType, entry.failedAttempts);
+      entry.nextActionAt = now_ts + delayHours * ONE_HOUR_MS;
     }
 
+    this.retryHistory.push({
+      subscriptionId,
+      merchantId: entry.merchantId,
+      failureType,
+      attempt: entry.totalFailedCharges,
+      success: false,
+      timestamp: now_ts,
+      delayHours,
+    });
+
     this.entries.set(subscriptionId, entry);
     return entry;
   }
 
-  recordSuccessfulCharge(subscriptionId: string): void {
+  recordSuccessfulCharge(subscriptionId: string): DunningEntry | null {
     const entry = this.entries.get(subscriptionId);
-    if (entry) {
-      this.retryHistory.push({
-        subscriptionId,
-        failureType: 'unknown',
-        attempt: entry.failedAttempts,
-        success: true,
-        timestamp: now(),
-        delayHours: 0,
-      });
-      this.progressiveEngine.recordRecovery(entry);
-    }
+    if (!entry) return null;
 
-    entry.updatedAt = now();
-    this.recoveredEntries.push(entry);
+    const now_ts = now();
+    this.retryHistory.push({
+      subscriptionId,
+      merchantId: entry.merchantId,
+      failureType: FAILURE_TYPES.find((t) => FAILURE_TYPE_TO_REASON[t] === entry.failureReason) ?? 'unknown',
+      attempt: entry.totalFailedCharges + 1,
+      success: true,
+      timestamp: now_ts,
+      delayHours: 0,
+    });
+    this.progressiveEngine.recordRecovery(entry, now_ts);
 
+    entry.updatedAt = now_ts;
+    this.recoveredEntries.push(entry);
     this.entries.delete(subscriptionId);
+    return entry;
   }
 
   getDunningEntry(subscriptionId: string): DunningEntry | undefined {
@@ -333,6 +461,13 @@ export class DunningService {
     return all;
   }
 
+  listRecoveredDunning(merchantId?: string): DunningEntry[] {
+    if (merchantId) {
+      return this.recoveredEntries.filter((e) => e.merchantId === merchantId);
+    }
+    return [...this.recoveredEntries];
+  }
+
   pauseDunning(subscriptionId: string): DunningEntry | null {
     const entry = this.entries.get(subscriptionId);
     if (!entry) return null;
@@ -366,6 +501,7 @@ export class DunningService {
     entry.nextActionAt = now() + (stageConfig?.delayHours ?? 24) * ONE_HOUR_MS;
     entry.updatedAt = now();
     this.entries.set(subscriptionId, entry);
+    this.progressiveEngine.trackStageEntry(entry);
     return entry;
   }
 
@@ -374,35 +510,18 @@ export class DunningService {
   }
 
   getRetryAnalytics(merchantId?: string): RetryAnalytics {
-    const entries = this.listActiveDunning(merchantId);
     const relevantHistory = merchantId
-      ? this.retryHistory.filter((h) =>
-          entries.some((e) => e.subscriptionId === h.subscriptionId)
-        )
+      ? this.retryHistory.filter((h) => h.merchantId === merchantId)
       : this.retryHistory;
 
     const totalRetries = relevantHistory.length;
     const successfulRetries = relevantHistory.filter((h) => h.success).length;
     const failedRetries = totalRetries - successfulRetries;
 
-    const retriesByFailureType: Record<FailureType, number> = {
-      insufficient_funds: 0,
-      card_declined: 0,
-      expired_card: 0,
-      network_error: 0,
-      processing_error: 0,
-      auth_required: 0,
-      unknown: 0,
-    };
+    const retriesByFailureType = emptyFailureTypeRecord();
+    const retriesByStage = emptyStageRecord();
 
-    const retriesByStage: Record<DunningStage, number> = {
-      retry: 0,
-      warn: 0,
-      suspend: 0,
-      cancel: 0,
-    };
-
-    for (const entry of entries) {
+    for (const entry of this.listActiveDunning(merchantId)) {
       retriesByStage[entry.currentStage] = (retriesByStage[entry.currentStage] ?? 0) + 1;
     }
 
@@ -415,8 +534,10 @@ export class DunningService {
     );
 
     const recoveryTimes: number[] = [];
+    const attemptsPerSuccess: number[] = [];
     for (const subId of successfulSubscriptionIds) {
       const subHistory = relevantHistory.filter((h) => h.subscriptionId === subId);
+      attemptsPerSuccess.push(subHistory.length);
       if (subHistory.length >= 2) {
         const first = subHistory[0];
         const last = subHistory[subHistory.length - 1];
@@ -429,12 +550,6 @@ export class DunningService {
         ? recoveryTimes.reduce((s, t) => s + t, 0) / recoveryTimes.length
         : 0;
 
-    const attemptsPerSuccess: number[] = [];
-    for (const subId of successfulSubscriptionIds) {
-      const subHistory = relevantHistory.filter((h) => h.subscriptionId === subId);
-      attemptsPerSuccess.push(subHistory.length);
-    }
-
     return {
       totalRetries,
       successfulRetries,
@@ -453,49 +568,50 @@ export class DunningService {
 
   getAnalytics(merchantId?: string): DunningAnalytics {
     const allEntries = this.listActiveDunning(merchantId);
-    const recovered = merchantId 
-      ? this.recoveredEntries.filter(e => e.merchantId === merchantId)
-      : this.recoveredEntries;
-
-    const stageBreakdown: Record<DunningStage, number> = {
-      retry: 0,
-      warn: 0,
-      suspend: 0,
-      cancel: 0,
-    };
+    const recovered = this.listRecoveredDunning(merchantId);
 
-    let totalLost = 0;
+    const stageBreakdown = emptyStageRecord();
     for (const entry of allEntries) {
       stageBreakdown[entry.currentStage] = (stageBreakdown[entry.currentStage] ?? 0) + 1;
-      if (entry.currentStage === 'cancel') {
-        totalLost++;
-      }
     }
 
     const retryAnalytics = this.getRetryAnalytics(merchantId);
 
+    // Recovery rate is measured over closed outcomes only: entries that were
+    // recovered versus entries that reached `cancel`.
+    const closed = recovered.length + stageBreakdown.cancel;
+    const recoveryRate = closed > 0 ? Math.round((recovered.length / closed) * 100) : 0;
+
+    const recoveryDays = recovered
+      .map((e) => (e.updatedAt - e.firstFailureAt) / ONE_DAY_MS)
+      .filter((d) => d >= 0);
+    const averageDaysToRecovery =
+      recoveryDays.length > 0
+        ? Math.round((recoveryDays.reduce((s, d) => s + d, 0) / recoveryDays.length) * 10) / 10
+        : 0;
+
     return {
       totalActiveDunning: allEntries.length,
       stageBreakdown,
-      recoveryRate: retryAnalytics.successRate,
-      totalRecovered: retryAnalytics.successfulRetries,
+      recoveryRate,
+      totalRecovered: recovered.length,
       totalLost: stageBreakdown.cancel,
-      averageDaysToRecovery: retryAnalytics.averageTimeToRecovery,
-      stageSuccessRates: {
-        retry: retryAnalytics.retriesByStage.retry,
-        warn: retryAnalytics.retriesByStage.warn,
-        suspend: retryAnalytics.retriesByStage.suspend,
-        cancel: retryAnalytics.retriesByStage.cancel,
-      },
+      averageDaysToRecovery,
+      stageSuccessRates: retryAnalytics.retriesByStage,
     };
   }
 
-  private sendCommunication(entry: DunningEntry, stageConfig: DunningStageConfig): DunningCommunication {
+  private sendCommunication(
+    entry: DunningEntry,
+    stageConfig: DunningStageConfig,
+    strategy?: RetryStrategy
+  ): DunningCommunication {
     const template = this.templates.find((t) => t.id === stageConfig.templateId);
+    const channel = strategy?.communicationChannels?.[0] ?? 'push';
     const comm: DunningCommunication = {
       id: createId('dcom'),
       stage: stageConfig.stage,
-      channel: 'push',
+      channel,
       templateId: stageConfig.templateId,
       sentAt: now(),
       status: 'sent',
@@ -521,25 +637,36 @@ export class DunningService {
   }
 
   addTemplate(template: DunningCommunicationTemplate): void {
-    if (!this.templates.find(t => t.id === template.id)) {
+    if (!this.templates.find((t) => t.id === template.id)) {
       this.templates.push(template);
     }
   }
 
   updateTemplate(id: string, template: Partial<DunningCommunicationTemplate>): void {
-    const index = this.templates.findIndex(t => t.id === id);
+    const index = this.templates.findIndex((t) => t.id === id);
     if (index !== -1) {
       this.templates[index] = { ...this.templates[index], ...template };
     }
   }
 
   removeTemplate(id: string): void {
-    this.templates = this.templates.filter(t => t.id !== id);
+    this.templates = this.templates.filter((t) => t.id !== id);
   }
 
   getTemplates(): DunningCommunicationTemplate[] {
     return [...this.templates];
   }
+
+  /** Clears all in-memory state. Intended for tests and worker restarts. */
+  reset(): void {
+    this.entries.clear();
+    this.configurations.clear();
+    this.communicationLog.clear();
+    this.templates = [...DUNNING_TEMPLATES];
+    this.retrySchedules = [...DEFAULT_RETRY_SCHEDULES];
+    this.retryHistory = [];
+    this.recoveredEntries = [];
+  }
 }
 
 export const dunningService = new DunningService();
diff --git a/backend/services/billing/index.ts b/backend/services/billing/index.ts
index e7627b23..92f0f988 100644
--- a/backend/services/billing/index.ts
+++ b/backend/services/billing/index.ts
@@ -28,7 +28,44 @@ export type {
   TaxRemittanceReportRequest,
 } from './taxTypes';
 export { DunningService, dunningService } from './dunningService';
-export type { FailureType, RetryScheduleConfig, RetryAnalytics } from './dunningService';
+export type {
+  BackoffPolicy,
+  FailureType,
+  RetryScheduleConfig,
+  RetryAnalytics,
+} from './dunningService';
+
+// Metered pricing and tiered overage rating (issue #935). Mirrors the
+// `subtrackr-metering` Soroban contract; see metering.ts for why.
+export {
+  MeteringPricingError,
+  buildOverageLadder,
+  marginalUnitPrice,
+  quoteMeter,
+  rateMeter,
+  rateUsage,
+  toContractTiers,
+  validateMeterPricingPlan,
+  validateOverageTiers,
+} from './metering';
+export type {
+  MeteredPricingModel,
+  MeterPricingPlan,
+  OverageTier,
+  RateUsageInput,
+  RatedMeterLine,
+  RatedTierLine,
+  RatedUsageBill,
+} from './metering';
+
+// Per-tenant invoice branding and rendering (issue #937).
+export {
+  FALLBACK_BRANDING,
+  InvoiceCustomizationService,
+  escapeHtml,
+  normalizeBranding,
+} from './invoiceCustomizationService';
+export type { DeliveryResult, RenderedInvoice } from './invoiceCustomizationService';
 export { ProrationService, prorationService } from './proration';
 export type {
   ProrationConfiguration,
diff --git a/backend/services/billing/interfaces.ts b/backend/services/billing/interfaces.ts
index a9afd1f8..776e426f 100644
--- a/backend/services/billing/interfaces.ts
+++ b/backend/services/billing/interfaces.ts
@@ -130,11 +130,19 @@ export interface IDunningService {
   configurePlan(planId: string, config: Partial<DunningConfiguration>): DunningConfiguration;
   configureABTest(planId: string, enabled: boolean, variants: Array<{ id: string; weight: number; strategy: RetryStrategy }>): void;
   getConfiguration(planId: string): DunningConfiguration | undefined;
-  startDunning(subscriptionId: string, subscriberId: string, merchantId: string, planId: string): DunningEntry;
+  getStrategy(planId: string, failureReason: FailureReason, abTestVariant?: string): RetryStrategy;
+  startDunning(
+    subscriptionId: string,
+    subscriberId: string,
+    merchantId: string,
+    planId: string,
+    failureReason?: FailureReason
+  ): DunningEntry;
   recordFailedCharge(subscriptionId: string, failureType?: string): DunningEntry | null;
-  recordSuccessfulCharge(subscriptionId: string): void;
+  recordSuccessfulCharge(subscriptionId: string): DunningEntry | null;
   getDunningEntry(subscriptionId: string): DunningEntry | undefined;
   listActiveDunning(merchantId?: string): DunningEntry[];
+  listRecoveredDunning(merchantId?: string): DunningEntry[];
   pauseDunning(subscriptionId: string): DunningEntry | null;
   resumeDunning(subscriptionId: string): DunningEntry | null;
   overrideStage(subscriptionId: string, stage: DunningStage): DunningEntry | null;
@@ -147,6 +155,9 @@ export interface IDunningService {
     maxRetries?: number;
     backoffMultiplier?: number;
     maxDelayHours?: number;
+    backoffPolicy?: string;
+    jitterRatio?: number;
+    retryable?: boolean;
   }): void;
   getRetrySchedule(failureType: string): {
     failureType: string;
@@ -154,6 +165,9 @@ export interface IDunningService {
     maxRetries: number;
     backoffMultiplier: number;
     maxDelayHours: number;
+    backoffPolicy: string;
+    jitterRatio: number;
+    retryable: boolean;
   };
   calculateRetryDelay(failureType: string, attempt: number): number;
   getRetryAnalytics(merchantId?: string): {
diff --git a/backend/services/billing/invoiceCustomizationService.ts b/backend/services/billing/invoiceCustomizationService.ts
index 41e8bcbe..b51e1d03 100644
--- a/backend/services/billing/invoiceCustomizationService.ts
+++ b/backend/services/billing/invoiceCustomizationService.ts
@@ -1,52 +1,332 @@
-import { Invoice, InvoiceBranding } from '../../../src/types/invoice';
+/**
+ * Per-tenant invoice rendering.
+ *
+ * One deployment issues invoices on behalf of many merchants, so an invoice's
+ * appearance is a property of its *tenant*, not of the platform. This module
+ * turns an invoice plus a resolved branding profile into a document, and
+ * delivers it.
+ *
+ * Rendering is deterministic and side-effect free: the same invoice and
+ * branding always produce byte-identical markup. That is what makes the output
+ * snapshot-testable, cacheable, and safe to re-render when a dispute needs the
+ * exact document a payer saw.
+ *
+ * Every branding value is attacker-controlled — a tenant types it into a form —
+ * so all of it is escaped or scheme-checked before it reaches the markup.
+ */
+
+import type {
+  Invoice,
+  InvoiceBranding,
+  InvoiceLineItem,
+  InvoiceTemplate,
+  ResolvedInvoiceBranding,
+} from '../../../src/types/invoice';
 import { useInvoiceStore } from '../../../src/store/invoiceStore';
-import { presentLocalNotification } from '../../../src/services/notificationService';
+
+/** Applied wherever a tenant has not supplied its own value. */
+export const FALLBACK_BRANDING: Required<
+  Pick<InvoiceBranding, 'primaryColor' | 'secondaryColor' | 'accentColor' | 'textColor' | 'fontFamily'>
+> = {
+  primaryColor: '#1a73e8',
+  secondaryColor: '#f1f3f4',
+  accentColor: '#188038',
+  textColor: '#202124',
+  fontFamily: 'Helvetica, Arial, sans-serif',
+};
+
+const MIN_LOGO_WIDTH = 24;
+const MAX_LOGO_WIDTH = 320;
+const DEFAULT_LOGO_WIDTH = 140;
+
+const HEX_COLOR = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+
+export interface RenderedInvoice {
+  invoiceId: string;
+  invoiceNumber: string;
+  templateId: string;
+  layout: InvoiceTemplate['layout'];
+  /** Self-contained HTML — the input to the PDF pipeline. */
+  html: string;
+  /** Plain-text alternative for the email body. */
+  text: string;
+  branding: InvoiceBranding;
+  tenantId?: string;
+}
+
+export interface DeliveryResult {
+  delivered: boolean;
+  invoiceId: string;
+  recipientEmail?: string;
+  documentUrl?: string;
+  error?: string;
+}
+
+/**
+ * Escapes text for HTML. Applied to every interpolated value without
+ * exception — a tenant's own display name included.
+ */
+export function escapeHtml(value: unknown): string {
+  return String(value ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/** Passes through only colours that are safe to drop into a style attribute. */
+function safeColor(value: string | undefined, fallback: string): string {
+  return value && HEX_COLOR.test(value) ? value : fallback;
+}
+
+/**
+ * Only http(s) and inline image data URLs may be embedded. Anything else — most
+ * importantly `javascript:` — is dropped, and the invoice renders without a logo.
+ */
+function safeImageUrl(value: string | undefined): string | null {
+  if (!value) return null;
+  return /^https?:\/\//i.test(value) || /^data:image\//i.test(value) ? value : null;
+}
+
+function safeLinkUrl(value: string | undefined): string | null {
+  if (!value) return null;
+  return /^https?:\/\//i.test(value) ? value : null;
+}
+
+function clampLogoWidth(value: number | undefined): number {
+  if (!Number.isFinite(value)) return DEFAULT_LOGO_WIDTH;
+  return Math.min(Math.max(value as number, MIN_LOGO_WIDTH), MAX_LOGO_WIDTH);
+}
+
+/**
+ * A font stack reaches the document as a CSS value, so quotes and semicolons
+ * would let a tenant close the declaration and inject their own.
+ */
+function safeFontFamily(value: string | undefined): string {
+  if (!value) return FALLBACK_BRANDING.fontFamily;
+  const cleaned = value.replace(/[^a-zA-Z0-9 ,\-]/g, '').trim();
+  return cleaned.length > 0 ? cleaned : FALLBACK_BRANDING.fontFamily;
+}
+
+function formatMoney(amount: number, currency: string): string {
+  const normalized = Number.isFinite(amount) ? amount : 0;
+  return `${normalized.toFixed(2)} ${currency}`;
+}
+
+function formatDate(value: Date | string | number): string {
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? '—' : date.toISOString().slice(0, 10);
+}
+
+/** Fills every unset branding field so downstream rendering never branches. */
+export function normalizeBranding(branding: InvoiceBranding | undefined): InvoiceBranding {
+  const source = branding ?? {};
+  return {
+    ...source,
+    primaryColor: safeColor(source.primaryColor, FALLBACK_BRANDING.primaryColor),
+    secondaryColor: safeColor(source.secondaryColor, FALLBACK_BRANDING.secondaryColor),
+    accentColor: safeColor(source.accentColor, FALLBACK_BRANDING.accentColor),
+    textColor: safeColor(source.textColor, FALLBACK_BRANDING.textColor),
+    fontFamily: safeFontFamily(source.fontFamily),
+    logoUrl: safeImageUrl(source.logoUrl) ?? undefined,
+    logoWidth: clampLogoWidth(source.logoWidth),
+    websiteUrl: safeLinkUrl(source.websiteUrl) ?? undefined,
+  };
+}
+
+function renderLineItems(items: InvoiceLineItem[], currency: string, branding: InvoiceBranding): string {
+  if (items.length === 0) {
+    return '<tr><td colspan="3" class="empty">No line items</td></tr>';
+  }
+  return items
+    .map((item) => {
+      const amount = formatMoney(Number(item.lineTotal ?? 0), currency);
+      const quantity = item.quantity ?? 1;
+      return [
+        '<tr>',
+        `<td>${escapeHtml(item.description ?? 'Item')}</td>`,
+        `<td class="num">${escapeHtml(quantity)}</td>`,
+        `<td class="num" style="color:${branding.textColor}">${escapeHtml(amount)}</td>`,
+        '</tr>',
+      ].join('');
+    })
+    .join('');
+}
+
+/**
+ * Layout-specific chrome. The three layouts differ only in how prominent the
+ * brand colour is, so they share one document skeleton.
+ */
+function layoutStyles(layout: InvoiceTemplate['layout'], branding: InvoiceBranding): string {
+  switch (layout) {
+    case 'modern':
+      return `header{background:${branding.primaryColor};color:#fff;padding:32px}` +
+        `h1{margin:0;font-size:28px;letter-spacing:-0.5px}` +
+        `th{background:${branding.secondaryColor}}`;
+    case 'minimalist':
+      return `header{padding:24px 0;border-bottom:1px solid ${branding.secondaryColor}}` +
+        `h1{margin:0;font-size:20px;font-weight:500;color:${branding.textColor}}` +
+        `th{background:transparent;border-bottom:1px solid ${branding.secondaryColor}}`;
+    case 'standard':
+    default:
+      return `header{padding:24px 0;border-bottom:3px solid ${branding.primaryColor}}` +
+        `h1{margin:0;font-size:24px;color:${branding.primaryColor}}` +
+        `th{background:${branding.secondaryColor}}`;
+  }
+}
 
 export class InvoiceCustomizationService {
   /**
-   * Simulates generating a PDF with per-tenant branding applied.
+   * Renders an invoice under a tenant's branding.
+   *
+   * When `resolved` is omitted the branding is looked up from the invoice's
+   * own `tenantId`, so a caller holding only an invoice still gets the right
+   * brand.
    */
-  static async generateInvoicePdf(invoice: Invoice, branding?: InvoiceBranding): Promise<string> {
-    const configBranding = branding || invoice.branding || useInvoiceStore.getState().config.defaultBranding;
-    const templateId = invoice.templateId || 'tpl-1';
-
-    // In a real implementation, we would use pdfkit, puppeteer, or a service like PDFMonkey here.
-    // For now, we simulate generation.
-    console.log(`Generating PDF for ${invoice.invoiceNumber}...`);
-    console.log(`Applying Template ID: ${templateId}`);
-    if (configBranding) {
-      console.log(`Applying Branding: Logo=${configBranding.logoUrl}, PrimaryColor=${configBranding.primaryColor}, Font=${configBranding.fontFamily}`);
+  static renderInvoice(
+    invoice: Invoice,
+    resolved?: ResolvedInvoiceBranding
+  ): RenderedInvoice {
+    const store = useInvoiceStore.getState();
+    const effective = resolved ?? store.resolveBranding(invoice.tenantId);
+    // An explicit per-invoice override outranks the tenant profile: it is what
+    // was in force when the invoice was issued.
+    const branding = normalizeBranding(invoice.branding ?? effective.branding);
+    const templateId = invoice.templateId ?? effective.templateId;
+    const template = store.templates.find((t) => t.id === templateId);
+    const layout = template?.layout ?? 'standard';
+
+    const currency = invoice.currency ?? 'USD';
+    const issuer = effective.displayName ?? invoice.merchantName;
+    const logoUrl = safeImageUrl(branding.logoUrl);
+    const websiteUrl = safeLinkUrl(branding.websiteUrl);
+
+    const logo = logoUrl
+      ? `<img src="${escapeHtml(logoUrl)}" alt="${escapeHtml(issuer)}" width="${branding.logoWidth}" />`
+      : '';
+
+    const footerParts: string[] = [];
+    if (branding.footerText) footerParts.push(escapeHtml(branding.footerText));
+    if (branding.supportEmail) {
+      footerParts.push(
+        `<a href="mailto:${escapeHtml(branding.supportEmail)}">${escapeHtml(branding.supportEmail)}</a>`
+      );
+    }
+    if (websiteUrl) {
+      footerParts.push(`<a href="${escapeHtml(websiteUrl)}">${escapeHtml(websiteUrl)}</a>`);
     }
 
-    // Simulate delay
-    await new Promise(resolve => setTimeout(resolve, 800));
+    const html = [
+      '<!doctype html><html><head><meta charset="utf-8" />',
+      `<title>${escapeHtml(invoice.invoiceNumber)}</title>`,
+      '<style>',
+      `body{font-family:${branding.fontFamily};color:${branding.textColor};margin:0;padding:32px}`,
+      layoutStyles(layout, branding),
+      'table{width:100%;border-collapse:collapse;margin-top:24px}',
+      'th,td{padding:8px 12px;text-align:left}',
+      '.num{text-align:right}',
+      '.empty{color:#5f6368;font-style:italic}',
+      `.total{font-weight:700;color:${branding.accentColor}}`,
+      'footer{margin-top:32px;font-size:12px;color:#5f6368}',
+      '</style></head><body>',
+      `<header>${logo}<h1>${escapeHtml(issuer)}</h1>`,
+      `<p>Invoice ${escapeHtml(invoice.invoiceNumber)} · issued ${escapeHtml(formatDate(invoice.createdAt))}</p>`,
+      '</header>',
+      '<section>',
+      `<p>Subscription: ${escapeHtml(invoice.subscriptionName)}</p>`,
+      `<p>Period: ${escapeHtml(formatDate(invoice.period.start))} → ${escapeHtml(formatDate(invoice.period.end))}</p>`,
+      `<p>Due: ${escapeHtml(formatDate(invoice.dueDate))}</p>`,
+      '</section>',
+      '<table><thead><tr><th>Description</th><th class="num">Qty</th><th class="num">Amount</th></tr></thead>',
+      `<tbody>${renderLineItems(invoice.lineItems ?? [], currency, branding)}</tbody>`,
+      '<tfoot>',
+      `<tr><td colspan="2" class="num">Subtotal</td><td class="num">${escapeHtml(formatMoney(invoice.subtotal, currency))}</td></tr>`,
+      `<tr><td colspan="2" class="num">Tax</td><td class="num">${escapeHtml(formatMoney(invoice.tax, currency))}</td></tr>`,
+      `<tr><td colspan="2" class="num total">Total</td><td class="num total">${escapeHtml(formatMoney(invoice.total, currency))}</td></tr>`,
+      '</tfoot></table>',
+      footerParts.length > 0 ? `<footer>${footerParts.join(' · ')}</footer>` : '',
+      '</body></html>',
+    ].join('');
 
-    const simulatedPdfUrl = `https://cdn.subtrackr.app/invoices/${invoice.id}.pdf`;
-    return simulatedPdfUrl;
+    const text = [
+      `${issuer}`,
+      `Invoice ${invoice.invoiceNumber}`,
+      `Subscription: ${invoice.subscriptionName}`,
+      `Period: ${formatDate(invoice.period.start)} - ${formatDate(invoice.period.end)}`,
+      `Due: ${formatDate(invoice.dueDate)}`,
+      '',
+      ...(invoice.lineItems ?? []).map(
+        (item) =>
+          `- ${item.description ?? 'Item'} x${item.quantity ?? 1}: ${formatMoney(Number(item.lineTotal ?? 0), currency)}`
+      ),
+      '',
+      `Subtotal: ${formatMoney(invoice.subtotal, currency)}`,
+      `Tax: ${formatMoney(invoice.tax, currency)}`,
+      `Total: ${formatMoney(invoice.total, currency)}`,
+      branding.footerText ? `\n${branding.footerText}` : '',
+    ]
+      .join('\n')
+      .trim();
+
+    return {
+      invoiceId: invoice.id,
+      invoiceNumber: invoice.invoiceNumber,
+      templateId,
+      layout,
+      html,
+      text,
+      branding,
+      tenantId: invoice.tenantId,
+    };
   }
 
   /**
-   * Automates the delivery of an invoice via email and pushes a notification.
+   * Produces the branded document and returns its storage URL.
+   *
+   * The PDF conversion itself is a deployment concern (pdfkit, puppeteer, a
+   * hosted renderer); what belongs here is the branded HTML that goes into it.
    */
-  static async deliverInvoice(invoiceId: string, recipientEmail: string): Promise<boolean> {
+  static async generateInvoicePdf(
+    invoice: Invoice,
+    resolved?: ResolvedInvoiceBranding
+  ): Promise<{ url: string; rendered: RenderedInvoice }> {
+    const rendered = this.renderInvoice(invoice, resolved);
+    return {
+      url: `https://cdn.subtrackr.app/invoices/${encodeURIComponent(invoice.id)}.pdf`,
+      rendered,
+    };
+  }
+
+  /** Renders a tenant's branding against a sample invoice for the settings preview. */
+  static previewForTenant(tenantId: string, sample: Invoice): RenderedInvoice {
+    const resolved = useInvoiceStore.getState().resolveBranding(tenantId);
+    // Ignore any branding frozen onto the sample so the preview reflects the
+    // profile as it stands right now.
+    return this.renderInvoice({ ...sample, branding: undefined, tenantId }, resolved);
+  }
+
+  /** Renders the branded document and marks the invoice sent. */
+  static async deliverInvoice(invoiceId: string, recipientEmail: string): Promise<DeliveryResult> {
     try {
       const store = useInvoiceStore.getState();
-      const invoice = store.invoices.find(i => i.id === invoiceId);
-      
-      if (!invoice) throw new Error('Invoice not found');
+      const invoice = store.invoices.find((i) => i.id === invoiceId);
 
-      // Generate the branded PDF
-      const pdfUrl = await this.generateInvoicePdf(invoice);
+      if (!invoice) {
+        return { delivered: false, invoiceId, error: 'Invoice not found' };
+      }
 
-      console.log(`Sending email to ${recipientEmail} with attachment ${pdfUrl}...`);
-      
-      // Update the invoice status
+      const { url } = await this.generateInvoicePdf(invoice);
       await store.sendInvoice(invoiceId, recipientEmail);
 
-      return true;
-    } catch (e) {
-      console.error('Automated invoice delivery failed:', e);
-      return false;
+      return { delivered: true, invoiceId, recipientEmail, documentUrl: url };
+    } catch (error) {
+      return {
+        delivered: false,
+        invoiceId,
+        recipientEmail,
+        error: error instanceof Error ? error.message : String(error),
+      };
     }
   }
 }
diff --git a/backend/services/billing/metering.ts b/backend/services/billing/metering.ts
new file mode 100644
index 00000000..e1b78439
--- /dev/null
+++ b/backend/services/billing/metering.ts
@@ -0,0 +1,441 @@
+/**
+ * Metered pricing and tiered overage rating.
+ *
+ * `meteringService.ts` owns *ingestion* — dedup, clock-skew handling, quota
+ * alerts. This module owns *rating*: turning the units a subscription consumed
+ * over a period into money, under the same four pricing models the
+ * `subtrackr-metering` Soroban contract implements
+ * (`contracts/metering/src/metering.rs`). Keeping the two in step matters:
+ * off-chain rating produces the invoice the payer sees, on-chain rating
+ * produces the charge the contract settles, and a disagreement between them is
+ * a dispute.
+ *
+ * Rating is deliberately pure — it takes a plan and a unit count and returns a
+ * breakdown. Nothing here reads the ingestion store, so the same function
+ * prices a closed period, a mid-period estimate, and a "what would N units
+ * cost?" quote.
+ */
+
+import { TieredPricingCalculator } from './tieredPricingCalculator';
+import type { PricingTier } from '../../../src/types/usage';
+
+/**
+ * Raised when a pricing plan or a usage figure cannot be rated.
+ *
+ * Deliberately a plain `Error` subclass rather than the module's `BillingError`:
+ * that type descends from `backend/services/shared/errors.ts`, which does not
+ * currently compile, and rating must stay importable from the billing worker
+ * and from tests.
+ */
+export class MeteringPricingError extends Error {
+  constructor(
+    message: string,
+    readonly code: 'INVALID_PLAN' | 'INVALID_USAGE' = 'INVALID_PLAN'
+  ) {
+    super(message);
+    this.name = 'MeteringPricingError';
+    Object.setPrototypeOf(this, MeteringPricingError.prototype);
+  }
+}
+
+/** How billable units become an amount once the included allowance is spent. */
+export type MeteredPricingModel = 'flat' | 'graduated' | 'volume' | 'package';
+
+/**
+ * One band of an overage ladder.
+ *
+ * `upToUnits` is the band's inclusive cumulative upper bound; `null` marks the
+ * final unbounded band. `flatFee` is charged once when any unit falls into the
+ * band, and is the price *per block* under the `package` model (where
+ * `upToUnits` is read as the block size).
+ */
+export interface OverageTier {
+  upToUnits: number | null;
+  unitPrice: number;
+  flatFee?: number;
+}
+
+export interface MeterPricingPlan {
+  metric: string;
+  model: MeteredPricingModel;
+  /** Units granted free each period before the ladder applies. */
+  includedUnits: number;
+  /** Rate used by the `flat` model and as the fallback past a truncated ladder. */
+  unitPrice: number;
+  tiers?: OverageTier[];
+  /** Floor applied to the metered total for the period. */
+  minimumCharge?: number;
+  /** Ceiling applied to the metered total for the period ("spend cap"). */
+  maximumCharge?: number;
+  currency?: string;
+}
+
+export interface RatedTierLine {
+  upToUnits: number | null;
+  units: number;
+  unitPrice: number;
+  flatFee: number;
+  amount: number;
+}
+
+export interface RatedMeterLine {
+  metric: string;
+  model: MeteredPricingModel;
+  unitsUsed: number;
+  includedUnits: number;
+  /** Units past the included allowance — the overage that actually bills. */
+  billableUnits: number;
+  amount: number;
+  tierLines: RatedTierLine[];
+}
+
+export interface RatedUsageBill {
+  subscriptionId: string;
+  currency: string;
+  period: { start: Date; end: Date };
+  lines: RatedMeterLine[];
+  /** Sum of the line amounts before minimum/maximum adjustment. */
+  subtotal: number;
+  /** Positive when a minimum charge topped the bill up. */
+  minimumAdjustment: number;
+  /** Negative when a spend cap trimmed the bill. */
+  maximumAdjustment: number;
+  total: number;
+}
+
+export interface RateUsageInput {
+  subscriptionId: string;
+  period: { start: Date; end: Date };
+  /** Units consumed in the period, keyed by metric. */
+  usageByMetric: Record<string, number>;
+  plans: MeterPricingPlan[];
+  currency?: string;
+  /**
+   * Fraction of the period the subscription was actually active, in `[0, 1]`.
+   * Included allowances are scaled by this so a mid-period signup does not get
+   * a full month of free units. Defaults to 1.
+   */
+  prorationFactor?: number;
+}
+
+const DEFAULT_CURRENCY = 'USD';
+
+const isFiniteNumber = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value);
+
+/**
+ * Rejects ladders that would rate ambiguously: unsorted bounds, a duplicate
+ * bound, negative money, or an unbounded band anywhere but last.
+ */
+export function validateOverageTiers(tiers: OverageTier[]): void {
+  let previous = 0;
+  tiers.forEach((tier, index) => {
+    if (!isFiniteNumber(tier.unitPrice) || tier.unitPrice < 0) {
+      throw new MeteringPricingError(
+        `Tier ${index} has a negative or non-finite unitPrice`
+      );
+    }
+    if (tier.flatFee !== undefined && (!isFiniteNumber(tier.flatFee) || tier.flatFee < 0)) {
+      throw new MeteringPricingError(
+        `Tier ${index} has a negative or non-finite flatFee`
+      );
+    }
+    if (tier.upToUnits === null) {
+      if (index !== tiers.length - 1) {
+        throw new MeteringPricingError(
+          'An unbounded tier (upToUnits: null) must be the last tier'
+        );
+      }
+      return;
+    }
+    if (!isFiniteNumber(tier.upToUnits) || tier.upToUnits <= previous) {
+      throw new MeteringPricingError(
+        `Tier bounds must strictly ascend; tier ${index} bound ${tier.upToUnits} follows ${previous}`
+      );
+    }
+    previous = tier.upToUnits;
+  });
+}
+
+export function validateMeterPricingPlan(plan: MeterPricingPlan): void {
+  if (!plan.metric) {
+    throw new MeteringPricingError('Meter pricing plan requires a metric');
+  }
+  if (!isFiniteNumber(plan.unitPrice) || plan.unitPrice < 0) {
+    throw new MeteringPricingError(
+      `Meter "${plan.metric}" has a negative or non-finite unitPrice`
+    );
+  }
+  if (!isFiniteNumber(plan.includedUnits) || plan.includedUnits < 0) {
+    throw new MeteringPricingError(
+      `Meter "${plan.metric}" has a negative or non-finite includedUnits`
+    );
+  }
+  if (plan.model !== 'flat' && (!plan.tiers || plan.tiers.length === 0)) {
+    throw new MeteringPricingError(
+      `Meter "${plan.metric}" uses the "${plan.model}" model but defines no tiers`
+    );
+  }
+  if (plan.tiers) {
+    validateOverageTiers(plan.tiers);
+  }
+  if (
+    plan.minimumCharge !== undefined &&
+    plan.maximumCharge !== undefined &&
+    plan.minimumCharge > plan.maximumCharge
+  ) {
+    throw new MeteringPricingError(
+      `Meter "${plan.metric}" has a minimumCharge above its maximumCharge`
+    );
+  }
+}
+
+/** Selects the band covering `units`, or the last band when `units` overflows it. */
+function selectTier(tiers: OverageTier[], units: number): OverageTier | undefined {
+  for (const tier of tiers) {
+    if (tier.upToUnits === null || units <= tier.upToUnits) return tier;
+  }
+  return tiers[tiers.length - 1];
+}
+
+function rateGraduated(
+  billableUnits: number,
+  unitPrice: number,
+  tiers: OverageTier[]
+): RatedTierLine[] {
+  // The shared graduated walk lives in TieredPricingCalculator; reuse it for the
+  // unit split so tiered invoices and this rater cannot drift apart, then layer
+  // the per-band flat fees on top.
+  const ladder: PricingTier[] = tiers.map((tier) => ({
+    upToUnits: tier.upToUnits,
+    unitPrice: tier.unitPrice,
+  }));
+  const bounded = tiers[tiers.length - 1]?.upToUnits !== null;
+  // A truncated ladder must still bill the overflow, so extend it with the
+  // meter's flat rate rather than dropping those units.
+  if (bounded) {
+    ladder.push({ upToUnits: null, unitPrice });
+  }
+
+  const result = new TieredPricingCalculator(ladder).calculate(billableUnits);
+
+  return result.lines
+    .filter((line) => line.unitsInTier > 0)
+    .map((line) => {
+      const source = tiers.find((tier) => tier.upToUnits === line.tier.upToUnits);
+      const flatFee = source?.flatFee ?? 0;
+      return {
+        upToUnits: line.tier.upToUnits,
+        units: line.unitsInTier,
+        unitPrice: line.tier.unitPrice,
+        flatFee,
+        amount: line.amount + flatFee,
+      };
+    });
+}
+
+function rateVolume(
+  billableUnits: number,
+  unitPrice: number,
+  tiers: OverageTier[]
+): RatedTierLine[] {
+  const tier = selectTier(tiers, billableUnits);
+  const price = tier?.unitPrice ?? unitPrice;
+  const flatFee = tier?.flatFee ?? 0;
+  return [
+    {
+      upToUnits: tier?.upToUnits ?? null,
+      units: billableUnits,
+      unitPrice: price,
+      flatFee,
+      amount: billableUnits * price + flatFee,
+    },
+  ];
+}
+
+function ratePackage(
+  billableUnits: number,
+  unitPrice: number,
+  tiers: OverageTier[]
+): RatedTierLine[] {
+  const tier = selectTier(tiers, billableUnits);
+  const blockSize = tier?.upToUnits ?? null;
+  if (blockSize === null || blockSize <= 0) {
+    // No usable block size — degrade to flat rating rather than billing zero.
+    return [
+      {
+        upToUnits: null,
+        units: billableUnits,
+        unitPrice,
+        flatFee: 0,
+        amount: billableUnits * unitPrice,
+      },
+    ];
+  }
+  const blocks = Math.ceil(billableUnits / blockSize);
+  const blockPrice = tier?.flatFee ?? 0;
+  return [
+    {
+      upToUnits: blockSize,
+      units: billableUnits,
+      unitPrice: blockPrice,
+      flatFee: blockPrice,
+      amount: blocks * blockPrice,
+    },
+  ];
+}
+
+/**
+ * Prices `unitsUsed` against a single meter's plan.
+ *
+ * `prorationFactor` scales the included allowance only; consumed units are
+ * always billed in full.
+ */
+export function rateMeter(
+  plan: MeterPricingPlan,
+  unitsUsed: number,
+  prorationFactor = 1
+): RatedMeterLine {
+  validateMeterPricingPlan(plan);
+
+  if (!isFiniteNumber(unitsUsed) || unitsUsed < 0) {
+    throw new MeteringPricingError(
+      `Meter "${plan.metric}" received a negative or non-finite unit count`,
+      'INVALID_USAGE'
+    );
+  }
+  const factor = Math.min(Math.max(prorationFactor, 0), 1);
+  const includedUnits = Math.floor(plan.includedUnits * factor);
+  const billableUnits = Math.max(0, unitsUsed - includedUnits);
+
+  let tierLines: RatedTierLine[] = [];
+  if (billableUnits > 0) {
+    const tiers = plan.tiers ?? [];
+    switch (plan.model) {
+      case 'graduated':
+        tierLines = rateGraduated(billableUnits, plan.unitPrice, tiers);
+        break;
+      case 'volume':
+        tierLines = rateVolume(billableUnits, plan.unitPrice, tiers);
+        break;
+      case 'package':
+        tierLines = ratePackage(billableUnits, plan.unitPrice, tiers);
+        break;
+      case 'flat':
+      default:
+        tierLines = [
+          {
+            upToUnits: null,
+            units: billableUnits,
+            unitPrice: plan.unitPrice,
+            flatFee: 0,
+            amount: billableUnits * plan.unitPrice,
+          },
+        ];
+        break;
+    }
+  }
+
+  const amount = tierLines.reduce((sum, line) => sum + line.amount, 0);
+
+  return {
+    metric: plan.metric,
+    model: plan.model,
+    unitsUsed,
+    includedUnits,
+    billableUnits,
+    amount,
+    tierLines,
+  };
+}
+
+/**
+ * Rates every meter on a subscription for one period and applies plan-level
+ * minimums and spend caps.
+ *
+ * Minimums and caps are per-meter (they belong to the meter's plan), so the
+ * bill reports the aggregate adjustment while each line keeps its raw amount.
+ */
+export function rateUsage(input: RateUsageInput): RatedUsageBill {
+  const { subscriptionId, period, usageByMetric, plans } = input;
+
+  if (period.end.getTime() < period.start.getTime()) {
+    throw new MeteringPricingError(
+      'Billing period ends before it starts',
+      'INVALID_USAGE'
+    );
+  }
+
+  const factor = input.prorationFactor ?? 1;
+  const lines: RatedMeterLine[] = [];
+  let subtotal = 0;
+  let minimumAdjustment = 0;
+  let maximumAdjustment = 0;
+
+  for (const plan of plans) {
+    const unitsUsed = usageByMetric[plan.metric] ?? 0;
+    const line = rateMeter(plan, unitsUsed, factor);
+    lines.push(line);
+
+    let effective = line.amount;
+    if (plan.minimumCharge !== undefined && effective < plan.minimumCharge) {
+      minimumAdjustment += plan.minimumCharge - effective;
+      effective = plan.minimumCharge;
+    }
+    if (plan.maximumCharge !== undefined && effective > plan.maximumCharge) {
+      maximumAdjustment += plan.maximumCharge - effective;
+      effective = plan.maximumCharge;
+    }
+    subtotal += line.amount;
+  }
+
+  return {
+    subscriptionId,
+    currency: input.currency ?? plans[0]?.currency ?? DEFAULT_CURRENCY,
+    period,
+    lines,
+    subtotal,
+    minimumAdjustment,
+    maximumAdjustment,
+    total: subtotal + minimumAdjustment + maximumAdjustment,
+  };
+}
+
+/**
+ * Prices a hypothetical volume without touching recorded usage — the
+ * "what would N units cost?" estimator behind the pricing page.
+ */
+export function quoteMeter(plan: MeterPricingPlan, units: number): RatedMeterLine {
+  return rateMeter(plan, units, 1);
+}
+
+/**
+ * Marginal cost of the next unit at the current volume. Useful for showing a
+ * payer what crossing the next tier boundary will do to their bill.
+ */
+export function marginalUnitPrice(plan: MeterPricingPlan, atUnits: number): number {
+  const here = rateMeter(plan, atUnits, 1).amount;
+  const next = rateMeter(plan, atUnits + 1, 1).amount;
+  return next - here;
+}
+
+/**
+ * Converts an overage ladder into the contract's `PriceTier` encoding, where
+ * `0` — not `null` — marks the unbounded band. Use this when pushing a plan
+ * on-chain via `register_tiered_meter` so both sides rate identically.
+ */
+export function toContractTiers(
+  tiers: OverageTier[]
+): Array<{ up_to_units: number; unit_price: number; flat_fee: number }> {
+  validateOverageTiers(tiers);
+  return tiers.map((tier) => ({
+    up_to_units: tier.upToUnits ?? 0,
+    unit_price: tier.unitPrice,
+    flat_fee: tier.flatFee ?? 0,
+  }));
+}
+
+/** Convenience ladder for the common "N free, then flat rate" shape. */
+export function buildOverageLadder(unitPrice: number): OverageTier[] {
+  return [{ upToUnits: null, unitPrice }];
+}
diff --git a/contracts/metering/src/lib.rs b/contracts/metering/src/lib.rs
index ab125614..981b33fc 100644
--- a/contracts/metering/src/lib.rs
+++ b/contracts/metering/src/lib.rs
@@ -23,7 +23,8 @@ mod metering;
 mod test;
 
 pub use metering::{
-    billable_units, bucket_start, Charge, ChargeLine, Meter, MeterState, MeteredUsage, UsageBucket,
+    billable_units, bucket_start, rate_units, validate_tiers, Charge, ChargeLine, Meter,
+    MeterState, MeteredUsage, PriceTier, PricingModel, TierLine, UsageBucket,
 };
 
 use soroban_sdk::{
@@ -36,8 +37,6 @@ const DEFAULT_PERIOD_SECS: u64 = 86_400;
 /// Maximum number of retained period buckets per meter (~one quarter of days).
 const MAX_BUCKETS: u32 = 90;
 
-use subtrackr_types::CoreError;
-
 #[contracterror]
 #[derive(Clone, Debug, Copy, PartialEq, Eq)]
 #[repr(u32)]
@@ -45,27 +44,9 @@ pub enum MeteringError {
     InvalidValue = 1,
     InvalidPeriod = 2,
     MeterNotFound = 3,
-}
-
-impl From<MeteringError> for CoreError {
-    fn from(err: MeteringError) -> Self {
-        match err {
-            MeteringError::InvalidValue => CoreError::InvalidAmount,
-            MeteringError::InvalidPeriod => CoreError::InvalidInterval,
-            MeteringError::MeterNotFound => CoreError::NotFound,
-        }
-    }
-}
-
-impl From<CoreError> for MeteringError {
-    fn from(err: CoreError) -> Self {
-        match err {
-            CoreError::InvalidAmount => MeteringError::InvalidValue,
-            CoreError::InvalidInterval => MeteringError::InvalidPeriod,
-            CoreError::NotFound => MeteringError::MeterNotFound,
-            _ => MeteringError::InvalidValue,
-        }
-    }
+    /// Tiers are unordered, negatively priced, or place the unbounded tier
+    /// somewhere other than last.
+    InvalidTiers = 4,
 }
 
 #[contracttype]
@@ -80,9 +61,9 @@ pub struct SubTrackrMetering;
 
 #[contractimpl]
 impl SubTrackrMetering {
-    /// Registers or reconfigures a meter, setting its pricing, included tier,
-    /// aggregation period, and alert threshold. Existing totals/buckets are
-    /// preserved across reconfiguration.
+    /// Registers or reconfigures a meter with flat per-unit pricing, setting
+    /// its price, included tier, aggregation period, and alert threshold.
+    /// Existing totals/buckets are preserved across reconfiguration.
     pub fn register_meter(
         env: Env,
         reporter: Address,
@@ -92,11 +73,61 @@ impl SubTrackrMetering {
         included_units: u64,
         period_secs: u64,
         alert_threshold: u64,
+    ) -> Result<(), MeteringError> {
+        let tiers: Vec<PriceTier> = Vec::new(&env);
+        Self::register_tiered_meter(
+            env,
+            reporter,
+            subscription_id,
+            meter,
+            unit_price,
+            included_units,
+            period_secs,
+            alert_threshold,
+            PricingModel::Flat,
+            tiers,
+        )
+    }
+
+    /// Registers or reconfigures a meter with an explicit pricing model and
+    /// overage ladder.
+    ///
+    /// `included_units` is always the free allowance; the ladder rates only
+    /// what exceeds it. Under [`PricingModel::Graduated`] the ladder bounds are
+    /// cumulative over the *billable* units, so a `[1_000 @ 2, unbounded @ 1]`
+    /// ladder with 500 included units charges the first 1,000 overage units at
+    /// 2 and everything beyond at 1.
+    ///
+    /// Reconfiguration preserves accumulated totals and buckets so a mid-period
+    /// price change re-rates the same recorded usage.
+    #[allow(clippy::too_many_arguments)]
+    pub fn register_tiered_meter(
+        env: Env,
+        reporter: Address,
+        subscription_id: SubscriptionId,
+        meter: Meter,
+        unit_price: i128,
+        included_units: u64,
+        period_secs: u64,
+        alert_threshold: u64,
+        pricing_model: PricingModel,
+        tiers: Vec<PriceTier>,
     ) -> Result<(), MeteringError> {
         reporter.require_auth();
         if period_secs == 0 {
             return Err(MeteringError::InvalidPeriod);
         }
+        if unit_price < 0 {
+            return Err(MeteringError::InvalidValue);
+        }
+        if !validate_tiers(&tiers) {
+            return Err(MeteringError::InvalidTiers);
+        }
+        // Every model but Flat is meaningless without a ladder.
+        if pricing_model != PricingModel::Flat && tiers.is_empty() {
+            return Err(MeteringError::InvalidTiers);
+        }
+
         let mut state = Self::meter(&env, subscription_id, &meter).unwrap_or(MeterState {
             metric: meter.clone(),
             total: 0,
@@ -106,11 +137,15 @@ impl SubTrackrMetering {
             unit_price,
             alert_threshold,
             alert_fired: false,
+            pricing_model: pricing_model.clone(),
+            tiers: tiers.clone(),
             buckets: Vec::new(&env),
         });
         state.period_secs = period_secs;
         state.included_units = included_units;
         state.unit_price = unit_price;
+        state.pricing_model = pricing_model;
+        state.tiers = tiers;
         // Re-arming the alert lets a raised threshold fire again.
         state.alert_threshold = alert_threshold;
         state.alert_fired = state.total >= alert_threshold && alert_threshold != 0;
@@ -142,6 +177,8 @@ impl SubTrackrMetering {
             unit_price: 0,
             alert_threshold: 0,
             alert_fired: false,
+            pricing_model: PricingModel::Flat,
+            tiers: Vec::new(&env),
             buckets: Vec::new(&env),
         });
 
@@ -193,7 +230,13 @@ impl SubTrackrMetering {
             if let Some(state) = Self::meter(&env, subscription_id, &metric) {
                 let used = Self::usage_in_range(&state, &period);
                 let billable = billable_units(used, state.included_units);
-                let amount = (billable as i128).saturating_mul(state.unit_price);
+                let (amount, tier_lines) = rate_units(
+                    &env,
+                    &state.pricing_model,
+                    billable,
+                    state.unit_price,
+                    &state.tiers,
+                );
                 total = total.saturating_add(amount);
                 lines.push_back(ChargeLine {
                     metric,
@@ -201,6 +244,7 @@ impl SubTrackrMetering {
                     billable_units: billable,
                     unit_price: state.unit_price,
                     amount,
+                    tier_lines,
                 });
             }
             m += 1;
@@ -228,6 +272,35 @@ impl SubTrackrMetering {
         Self::meter(&env, subscription_id, &meter).ok_or(MeteringError::MeterNotFound)
     }
 
+    /// Prices a hypothetical usage volume against a meter's current ladder
+    /// without recording anything — the quote/preview path used by the
+    /// dashboard's "what would N units cost?" estimator.
+    pub fn quote_usage(
+        env: Env,
+        subscription_id: SubscriptionId,
+        meter: Meter,
+        units: u64,
+    ) -> Result<ChargeLine, MeteringError> {
+        let state =
+            Self::meter(&env, subscription_id, &meter).ok_or(MeteringError::MeterNotFound)?;
+        let billable = billable_units(units, state.included_units);
+        let (amount, tier_lines) = rate_units(
+            &env,
+            &state.pricing_model,
+            billable,
+            state.unit_price,
+            &state.tiers,
+        );
+        Ok(ChargeLine {
+            metric: meter,
+            units,
+            billable_units: billable,
+            unit_price: state.unit_price,
+            amount,
+            tier_lines,
+        })
+    }
+
     /// Cumulative units recorded for a meter.
     pub fn get_usage_total(env: Env, subscription_id: SubscriptionId, meter: Meter) -> u64 {
         Self::meter(&env, subscription_id, &meter)
diff --git a/contracts/metering/src/metering.rs b/contracts/metering/src/metering.rs
index b326152d..81ed902f 100644
--- a/contracts/metering/src/metering.rs
+++ b/contracts/metering/src/metering.rs
@@ -43,6 +43,10 @@ pub struct MeterState {
     pub alert_threshold: u64,
     /// Whether the alert for the current threshold has already fired.
     pub alert_fired: bool,
+    /// How billable units are rated once the included tier is consumed.
+    pub pricing_model: PricingModel,
+    /// Price ladder used by every model except [`PricingModel::Flat`].
+    pub tiers: Vec<PriceTier>,
     pub buckets: Vec<UsageBucket>,
 }
 
@@ -52,9 +56,12 @@ pub struct MeterState {
 pub struct ChargeLine {
     pub metric: Symbol,
     pub units: u64,
+    /// Units left after the included (free) allowance — i.e. the overage.
     pub billable_units: u64,
     pub unit_price: i128,
     pub amount: i128,
+    /// Per-tier split of `amount`; a single entry under flat pricing.
+    pub tier_lines: Vec<TierLine>,
 }
 
 /// The result of [`calculate_usage_charge`](crate::SubTrackrMetering::calculate_usage_charge).
@@ -80,3 +87,209 @@ pub fn bucket_start(now: u64, period_secs: u64) -> u64 {
 pub fn billable_units(used: u64, included: u64) -> u64 {
     used.saturating_sub(included)
 }
+
+/// How billable units are converted into an amount once the included (free)
+/// tier has been consumed.
+#[contracttype]
+#[derive(Clone, Debug, PartialEq)]
+pub enum PricingModel {
+    /// Every billable unit costs `MeterState::unit_price`.
+    Flat,
+    /// Units are split across `MeterState::tiers`; each slice is priced at the
+    /// rate of the tier it falls into (a.k.a. graduated pricing).
+    Graduated,
+    /// All billable units are priced at the rate of the single tier that the
+    /// total lands in.
+    Volume,
+    /// Units are sold in whole blocks: each started block of
+    /// `PriceTier::up_to_units` units costs `PriceTier::flat_fee`.
+    Package,
+}
+
+/// One band of a tiered price ladder.
+///
+/// `up_to_units` is the inclusive upper bound of the band expressed as a
+/// cumulative unit count; `0` means "unbounded" and may only appear on the
+/// last tier. `flat_fee` is charged once when any unit falls into the band
+/// (and is the per-block price under [`PricingModel::Package`]).
+#[contracttype]
+#[derive(Clone, Debug, PartialEq)]
+pub struct PriceTier {
+    pub up_to_units: u64,
+    pub unit_price: i128,
+    pub flat_fee: i128,
+}
+
+/// The share of a charge attributable to one tier of the ladder.
+#[contracttype]
+#[derive(Clone, Debug, PartialEq)]
+pub struct TierLine {
+    pub up_to_units: u64,
+    pub units: u64,
+    pub unit_price: i128,
+    pub amount: i128,
+}
+
+/// Rates the billable units of one meter, returning the total amount and the
+/// per-tier breakdown. Pure: no storage or ledger access.
+///
+/// `tiers` are assumed to be in ascending `up_to_units` order, which
+/// [`validate_tiers`] enforces at registration time.
+pub fn rate_units(
+    env: &soroban_sdk::Env,
+    model: &PricingModel,
+    billable: u64,
+    unit_price: i128,
+    tiers: &Vec<PriceTier>,
+) -> (i128, Vec<TierLine>) {
+    let mut lines: Vec<TierLine> = Vec::new(env);
+
+    if billable == 0 {
+        return (0, lines);
+    }
+
+    match model {
+        PricingModel::Flat => {
+            let amount = (billable as i128).saturating_mul(unit_price);
+            lines.push_back(TierLine {
+                up_to_units: 0,
+                units: billable,
+                unit_price,
+                amount,
+            });
+            (amount, lines)
+        }
+        PricingModel::Graduated => {
+            let mut total: i128 = 0;
+            let mut remaining = billable;
+            let mut lower: u64 = 0;
+            let mut i = 0u32;
+            while i < tiers.len() && remaining > 0 {
+                let tier = tiers.get(i).unwrap();
+                let capacity = if tier.up_to_units == 0 {
+                    remaining
+                } else {
+                    tier.up_to_units.saturating_sub(lower)
+                };
+                let units = if remaining < capacity {
+                    remaining
+                } else {
+                    capacity
+                };
+                if units > 0 {
+                    let amount = (units as i128)
+                        .saturating_mul(tier.unit_price)
+                        .saturating_add(tier.flat_fee);
+                    total = total.saturating_add(amount);
+                    lines.push_back(TierLine {
+                        up_to_units: tier.up_to_units,
+                        units,
+                        unit_price: tier.unit_price,
+                        amount,
+                    });
+                    remaining -= units;
+                }
+                if tier.up_to_units == 0 {
+                    break;
+                }
+                lower = tier.up_to_units;
+                i += 1;
+            }
+            // Units beyond the last bounded tier fall back to the flat rate so
+            // a truncated ladder never silently bills zero.
+            if remaining > 0 {
+                let amount = (remaining as i128).saturating_mul(unit_price);
+                total = total.saturating_add(amount);
+                lines.push_back(TierLine {
+                    up_to_units: 0,
+                    units: remaining,
+                    unit_price,
+                    amount,
+                });
+            }
+            (total, lines)
+        }
+        PricingModel::Volume => {
+            let tier = select_tier(tiers, billable);
+            let (price, bound, fee) = match tier {
+                Some(t) => (t.unit_price, t.up_to_units, t.flat_fee),
+                None => (unit_price, 0, 0),
+            };
+            let amount = (billable as i128).saturating_mul(price).saturating_add(fee);
+            lines.push_back(TierLine {
+                up_to_units: bound,
+                units: billable,
+                unit_price: price,
+                amount,
+            });
+            (amount, lines)
+        }
+        PricingModel::Package => {
+            let tier = select_tier(tiers, billable);
+            let (block, fee, bound) = match tier {
+                Some(t) => (t.up_to_units, t.flat_fee, t.up_to_units),
+                None => (0, 0, 0),
+            };
+            if block == 0 {
+                // No usable package size; fall back to flat rating.
+                let amount = (billable as i128).saturating_mul(unit_price);
+                lines.push_back(TierLine {
+                    up_to_units: 0,
+                    units: billable,
+                    unit_price,
+                    amount,
+                });
+                return (amount, lines);
+            }
+            let blocks = billable.div_ceil(block);
+            let amount = (blocks as i128).saturating_mul(fee);
+            lines.push_back(TierLine {
+                up_to_units: bound,
+                units: billable,
+                unit_price: fee,
+                amount,
+            });
+            (amount, lines)
+        }
+    }
+}
+
+/// Returns the first tier whose bound covers `units`, or the unbounded tier.
+fn select_tier(tiers: &Vec<PriceTier>, units: u64) -> Option<PriceTier> {
+    let mut i = 0u32;
+    while i < tiers.len() {
+        let tier = tiers.get(i).unwrap();
+        if tier.up_to_units == 0 || units <= tier.up_to_units {
+            return Some(tier);
+        }
+        i += 1;
+    }
+    // Past the end of a bounded ladder: bill at the last tier's rate.
+    if !tiers.is_empty() {
+        return tiers.get(tiers.len() - 1);
+    }
+    None
+}
+
+/// True when `tiers` form a usable ladder: ascending bounds, no negative
+/// prices, and an unbounded (`0`) bound only in final position.
+pub fn validate_tiers(tiers: &Vec<PriceTier>) -> bool {
+    let mut previous: u64 = 0;
+    let mut i = 0u32;
+    while i < tiers.len() {
+        let tier = tiers.get(i).unwrap();
+        if tier.unit_price < 0 || tier.flat_fee < 0 {
+            return false;
+        }
+        if tier.up_to_units == 0 {
+            // Unbounded tier must be last.
+            return i == tiers.len() - 1;
+        }
+        if tier.up_to_units <= previous {
+            return false;
+        }
+        previous = tier.up_to_units;
+        i += 1;
+    }
+    true
+}
diff --git a/contracts/metering/src/test.rs b/contracts/metering/src/test.rs
index 967f349a..862b3eb8 100644
--- a/contracts/metering/src/test.rs
+++ b/contracts/metering/src/test.rs
@@ -1,5 +1,5 @@
 use super::*;
-use soroban_sdk::{testutils::Address as _, testutils::Ledger as _, Address, Env, Symbol};
+use soroban_sdk::{testutils::Address as _, testutils::Ledger as _, Address, Env, Symbol, Vec};
 use subtrackr_types::TimeRange;
 
 fn setup() -> (Env, SubTrackrMeteringClient<'static>, Address) {
@@ -127,3 +127,363 @@ fn rejects_inverted_period() {
     );
     assert_eq!(res, Err(Ok(MeteringError::InvalidPeriod)));
 }
+
+fn tier(up_to_units: u64, unit_price: i128, flat_fee: i128) -> PriceTier {
+    PriceTier {
+        up_to_units,
+        unit_price,
+        flat_fee,
+    }
+}
+
+fn full_period() -> TimeRange {
+    TimeRange {
+        start: 0,
+        end: 1_000_000,
+    }
+}
+
+#[test]
+fn graduated_tiers_price_each_slice_at_its_own_rate() {
+    let (env, client, reporter) = setup();
+    let api = Symbol::new(&env, "api_calls");
+    set_time(&env, 1_000);
+
+    // 100 units free, then 1_000 overage units @ 3, then everything @ 1.
+    let tiers = Vec::from_array(&env, [tier(1_000, 3, 0), tier(0, 1, 0)]);
+    client.register_tiered_meter(
+        &reporter,
+        &1,
+        &api,
+        &0,
+        &100,
+        &86_400,
+        &0,
+        &PricingModel::Graduated,
+        &tiers,
+    );
+
+    // 1_600 used -> 1_500 billable -> 1_000 @ 3 (3_000) + 500 @ 1 (500).
+    client.record_metered_usage(&reporter, &1, &api, &1_600);
+
+    let charge = client.calculate_usage_charge(&1, &full_period());
+    assert_eq!(charge.total, 3_500);
+
+    let line = charge.lines.get(0).unwrap();
+    assert_eq!(line.units, 1_600);
+    assert_eq!(line.billable_units, 1_500);
+    assert_eq!(line.tier_lines.len(), 2);
+    assert_eq!(line.tier_lines.get(0).unwrap().units, 1_000);
+    assert_eq!(line.tier_lines.get(0).unwrap().amount, 3_000);
+    assert_eq!(line.tier_lines.get(1).unwrap().units, 500);
+    assert_eq!(line.tier_lines.get(1).unwrap().amount, 500);
+}
+
+#[test]
+fn graduated_charge_is_zero_inside_the_included_allowance() {
+    let (env, client, reporter) = setup();
+    let api = Symbol::new(&env, "api_calls");
+    set_time(&env, 1_000);
+
+    let tiers = Vec::from_array(&env, [tier(0, 5, 0)]);
+    client.register_tiered_meter(
+        &reporter,
+        &1,
+        &api,
+        &0,
+        &500,
+        &86_400,
+        &0,
+        &PricingModel::Graduated,
+        &tiers,
+    );
+    client.record_metered_usage(&reporter, &1, &api, &499);
+
+    let charge = client.calculate_usage_charge(&1, &full_period());
+    assert_eq!(charge.total, 0);
+    assert_eq!(charge.lines.get(0).unwrap().billable_units, 0);
+    assert_eq!(charge.lines.get(0).unwrap().tier_lines.len(), 0);
+}
+
+#[test]
+fn volume_pricing_rates_every_unit_at_the_reached_tier() {
+    let (env, client, reporter) = setup();
+    let api = Symbol::new(&env, "api_calls");
+    set_time(&env, 1_000);
+
+    // <=100 @ 10, <=1_000 @ 6, beyond @ 4.
+    let tiers = Vec::from_array(&env, [tier(100, 10, 0), tier(1_000, 6, 0), tier(0, 4, 0)]);
+    client.register_tiered_meter(
+        &reporter,
+        &2,
+        &api,
+        &0,
+        &0,
+        &86_400,
+        &0,
+        &PricingModel::Volume,
+        &tiers,
+    );
+
+    // 500 units lands in the second band -> all 500 priced at 6.
+    client.record_metered_usage(&reporter, &2, &api, &500);
+    assert_eq!(
+        client.calculate_usage_charge(&2, &full_period()).total,
+        3_000
+    );
+}
+
+#[test]
+fn volume_pricing_crossing_a_boundary_lowers_the_whole_bill() {
+    let (env, client, reporter) = setup();
+    let api = Symbol::new(&env, "api_calls");
+    set_time(&env, 1_000);
+
+    let tiers = Vec::from_array(&env, [tier(100, 10, 0), tier(0, 4, 0)]);
+    client.register_tiered_meter(
+        &reporter,
+        &3,
+        &api,
+        &0,
+        &0,
+        &86_400,
+        &0,
+        &PricingModel::Volume,
+        &tiers,
+    );
+
+    client.record_metered_usage(&reporter, &3, &api, &100); // 100 * 10
+    assert_eq!(
+        client.calculate_usage_charge(&3, &full_period()).total,
+        1_000
+    );
+
+    client.record_metered_usage(&reporter, &3, &api, &1); // 101 units -> 101 * 4
+    assert_eq!(client.calculate_usage_charge(&3, &full_period()).total, 404);
+}
+
+#[test]
+fn package_pricing_charges_whole_blocks() {
+    let (env, client, reporter) = setup();
+    let api = Symbol::new(&env, "api_calls");
+    set_time(&env, 1_000);
+
+    // Blocks of 1_000 units at a flat 25 per block.
+    let tiers = Vec::from_array(&env, [tier(1_000, 0, 25)]);
+    client.register_tiered_meter(
+        &reporter,
+        &4,
+        &api,
+        &0,
+        &0,
+        &86_400,
+        &0,
+        &PricingModel::Package,
+        &tiers,
+    );
+
+    // 2_001 units -> 3 started blocks -> 75.
+    client.record_metered_usage(&reporter, &4, &api, &2_001);
+    assert_eq!(client.calculate_usage_charge(&4, &full_period()).total, 75);
+}
+
+#[test]
+fn tier_flat_fees_are_added_once_per_entered_band() {
+    let (env, client, reporter) = setup();
+    let api = Symbol::new(&env, "api_calls");
+    set_time(&env, 1_000);
+
+    // Entering the overage band costs a 50 platform fee on top of 2/unit.
+    let tiers = Vec::from_array(&env, [tier(0, 2, 50)]);
+    client.register_tiered_meter(
+        &reporter,
+        &5,
+        &api,
+        &0,
+        &10,
+        &86_400,
+        &0,
+        &PricingModel::Graduated,
+        &tiers,
+    );
+
+    client.record_metered_usage(&reporter, &5, &api, &20); // 10 billable
+    assert_eq!(client.calculate_usage_charge(&5, &full_period()).total, 70);
+}
+
+#[test]
+fn rejects_unordered_or_negative_tiers() {
+    let (env, client, reporter) = setup();
+    let api = Symbol::new(&env, "api_calls");
+
+    let descending = Vec::from_array(&env, [tier(1_000, 1, 0), tier(100, 2, 0)]);
+    assert_eq!(
+        client.try_register_tiered_meter(
+            &reporter,
+            &6,
+            &api,
+            &0,
+            &0,
+            &86_400,
+            &0,
+            &PricingModel::Graduated,
+            &descending,
+        ),
+        Err(Ok(MeteringError::InvalidTiers))
+    );
+
+    let negative = Vec::from_array(&env, [tier(0, -1, 0)]);
+    assert_eq!(
+        client.try_register_tiered_meter(
+            &reporter,
+            &6,
+            &api,
+            &0,
+            &0,
+            &86_400,
+            &0,
+            &PricingModel::Graduated,
+            &negative,
+        ),
+        Err(Ok(MeteringError::InvalidTiers))
+    );
+}
+
+#[test]
+fn rejects_unbounded_tier_that_is_not_last() {
+    let (env, client, reporter) = setup();
+    let api = Symbol::new(&env, "api_calls");
+    let tiers = Vec::from_array(&env, [tier(0, 1, 0), tier(100, 2, 0)]);
+    assert_eq!(
+        client.try_register_tiered_meter(
+            &reporter,
+            &7,
+            &api,
+            &0,
+            &0,
+            &86_400,
+            &0,
+            &PricingModel::Graduated,
+            &tiers,
+        ),
+        Err(Ok(MeteringError::InvalidTiers))
+    );
+}
+
+#[test]
+fn rejects_tiered_model_without_a_ladder() {
+    let (env, client, reporter) = setup();
+    let api = Symbol::new(&env, "api_calls");
+    let empty: Vec<PriceTier> = Vec::new(&env);
+    assert_eq!(
+        client.try_register_tiered_meter(
+            &reporter,
+            &8,
+            &api,
+            &1,
+            &0,
+            &86_400,
+            &0,
+            &PricingModel::Graduated,
+            &empty,
+        ),
+        Err(Ok(MeteringError::InvalidTiers))
+    );
+}
+
+#[test]
+fn quote_prices_hypothetical_units_without_recording() {
+    let (env, client, reporter) = setup();
+    let api = Symbol::new(&env, "api_calls");
+    set_time(&env, 1_000);
+
+    let tiers = Vec::from_array(&env, [tier(1_000, 3, 0), tier(0, 1, 0)]);
+    client.register_tiered_meter(
+        &reporter,
+        &9,
+        &api,
+        &0,
+        &100,
+        &86_400,
+        &0,
+        &PricingModel::Graduated,
+        &tiers,
+    );
+
+    let quote = client.quote_usage(&9, &api, &1_600);
+    assert_eq!(quote.amount, 3_500);
+    assert_eq!(quote.billable_units, 1_500);
+    // Nothing was persisted by quoting.
+    assert_eq!(client.get_usage_total(&9, &api), 0);
+}
+
+#[test]
+fn reconfiguring_the_ladder_rerates_existing_usage() {
+    let (env, client, reporter) = setup();
+    let api = Symbol::new(&env, "api_calls");
+    set_time(&env, 1_000);
+
+    client.register_meter(&reporter, &10, &api, &10, &0, &86_400, &0);
+    client.record_metered_usage(&reporter, &10, &api, &200);
+    assert_eq!(
+        client.calculate_usage_charge(&10, &full_period()).total,
+        2_000
+    );
+
+    let tiers = Vec::from_array(&env, [tier(0, 1, 0)]);
+    client.register_tiered_meter(
+        &reporter,
+        &10,
+        &api,
+        &0,
+        &0,
+        &86_400,
+        &0,
+        &PricingModel::Graduated,
+        &tiers,
+    );
+
+    // Totals survive reconfiguration and are re-rated at the new price.
+    assert_eq!(client.get_usage_total(&10, &api), 200);
+    assert_eq!(
+        client.calculate_usage_charge(&10, &full_period()).total,
+        200
+    );
+}
+
+#[test]
+fn flat_meters_keep_a_single_tier_line() {
+    let (env, client, reporter) = setup();
+    let api = Symbol::new(&env, "api_calls");
+    set_time(&env, 1_000);
+
+    client.register_meter(&reporter, &11, &api, &2, &100, &86_400, &0);
+    client.record_metered_usage(&reporter, &11, &api, &150);
+
+    let charge = client.calculate_usage_charge(&11, &full_period());
+    let line = charge.lines.get(0).unwrap();
+    assert_eq!(line.amount, 100);
+    assert_eq!(line.tier_lines.len(), 1);
+    assert_eq!(line.tier_lines.get(0).unwrap().units, 50);
+}
+
+#[test]
+fn rejects_negative_unit_price() {
+    let (env, client, reporter) = setup();
+    let api = Symbol::new(&env, "api_calls");
+    let empty: Vec<PriceTier> = Vec::new(&env);
+    assert_eq!(
+        client.try_register_tiered_meter(
+            &reporter,
+            &12,
+            &api,
+            &-1,
+            &0,
+            &86_400,
+            &0,
+            &PricingModel::Flat,
+            &empty,
+        ),
+        Err(Ok(MeteringError::InvalidValue))
+    );
+}
diff --git a/docs/DUNNING_RETRY_STRATEGIES.md b/docs/DUNNING_RETRY_STRATEGIES.md
new file mode 100644
index 00000000..cfaff5cf
--- /dev/null
+++ b/docs/DUNNING_RETRY_STRATEGIES.md
@@ -0,0 +1,125 @@
+# Dunning Retry Strategies
+
+How `backend/services/billing/dunningService.ts` decides *when* to retry a
+failed charge and *when* to give up. For the email/A-B-test layer that sits on
+top of it see [DUNNING.md](./DUNNING.md); for the time-based stage escalation
+rules see [DUNNING_ESCALATION.md](./DUNNING_ESCALATION.md).
+
+## The two knobs
+
+Retry behaviour is configured in two independent places, and it helps to keep
+them apart:
+
+| | Configured by | Scope | Answers |
+|---|---|---|---|
+| **Stage ladder** (`RetryStrategy`) | `configurePlan()` | per plan | *Which stage comes next, and how long the payer sits in it?* |
+| **Retry schedule** (`RetryScheduleConfig`) | `configureRetrySchedule()` | per failure type, service-wide | *How long between retries inside a stage?* |
+
+A subscription escalates to the next stage when **either** its stage's
+`maxAttempts` or its failure type's `maxRetries` is spent — whichever comes
+first.
+
+## Strategy resolution
+
+`getStrategy(planId, failureReason, abTestVariant)` picks the ladder, most
+specific first:
+
+```
+A/B variant  →  failure-reason override  →  plan default  →  built-in fallback
+```
+
+So a plan can run a general ladder, a harsher one for `expired_card`, and still
+A/B-test a third against both:
+
+```ts
+dunningService.configurePlan('plan_pro', {
+  defaultStrategy: standardLadder,
+  strategies: { expired_card: shortLadder },
+});
+
+dunningService.configureABTest('plan_pro', true, [
+  { id: 'control',    weight: 50, strategy: standardLadder },
+  { id: 'aggressive', weight: 50, strategy: aggressiveLadder },
+]);
+```
+
+A variant is assigned once, at `startDunning()`, by weight, and is stored on the
+entry so the subscription keeps the same treatment for its whole dunning run.
+Reading a variant only matters while the test is enabled — flipping
+`configureABTest(..., false, ...)` sends everyone back to the resolved ladder
+without touching stored entries.
+
+## Backoff policies
+
+`calculateRetryDelay(failureType, attempt)` applies the failure type's
+`backoffPolicy`. `attempt` is 1-based.
+
+| Policy | Delay for attempt *n* |
+|---|---|
+| `fixed` | `baseDelayHours` |
+| `linear` | `baseDelayHours × n` |
+| `exponential` | `baseDelayHours × multiplier^(n-1)` |
+| `exponential_jitter` | as `exponential`, then spread by ± `jitterRatio` |
+
+Every result is clamped to `maxDelayHours`, jitter included — a jittered delay
+never escapes the configured envelope.
+
+### Why jitter
+
+A single upstream outage fails hundreds of charges within the same second.
+Without jitter every one of them retries at exactly the same instant, and the
+retry storm hits the processor just as hard as the original burst. `jitterRatio:
+0.2` spreads those retries over ±20% of the delay, which is enough to decorrelate
+them.
+
+Jitter is on by default for `insufficient_funds` and `network_error`, the two
+failure types that arrive in correlated bursts.
+
+### Defaults
+
+| Failure type | Base | Max retries | Policy | Rationale |
+|---|---|---|---|---|
+| `insufficient_funds` | 1h | 5 | `exponential_jitter` | Funds may arrive; back off but keep trying. |
+| `card_declined` | 2h | 3 | `exponential` | Usually needs the payer to act. |
+| `expired_card` | 24h | 2 | `fixed` | Will keep failing until updated — a flat daily nudge beats escalation. |
+| `network_error` | 30m | 6 | `exponential_jitter` | Transient; retry often, decorrelated. |
+| `processing_error` | 1h | 4 | `exponential` | Usually transient. |
+| `auth_required` | 15m | 3 | `linear` | The payer is likely still in-session. |
+| `unknown` | 1h | 3 | `exponential` | Conservative default. |
+
+Override any of them — partial updates merge onto the existing entry:
+
+```ts
+dunningService.configureRetrySchedule({
+  failureType: 'insufficient_funds',
+  maxRetries: 8,
+  jitterRatio: 0.35,
+});
+```
+
+### Non-retryable failures
+
+Setting `retryable: false` skips the retry budget entirely: the first failure of
+that type escalates straight to the next stage. Use it for hard declines where
+retrying only burns processor reputation.
+
+## Analytics
+
+`getRetryAnalytics(merchantId?)` reports raw retry counts — attempts, success
+rate, breakdown by failure type and by current stage, mean time to recovery.
+
+`getAnalytics(merchantId?)` reports the business view. Note that `recoveryRate`
+is measured over **closed outcomes only** — recovered entries versus entries that
+reached `cancel`. Subscriptions still in dunning are deliberately excluded: their
+outcome is not known yet, and counting them as failures would make the rate look
+worse the more traffic is in flight.
+
+## Testing
+
+`backend/services/billing/__tests__/dunningService.test.ts` covers strategy
+resolution precedence, every backoff policy, the jitter envelope, stage
+escalation, and the analytics edge cases (empty history returns zeroes, not
+`NaN`).
+
+Construct a fresh `new DunningService()` per test, or call `reset()` on the
+shared singleton — state is in-memory and otherwise leaks between tests.
diff --git a/docs/INVOICE_BRANDING.md b/docs/INVOICE_BRANDING.md
new file mode 100644
index 00000000..1b33aaca
--- /dev/null
+++ b/docs/INVOICE_BRANDING.md
@@ -0,0 +1,116 @@
+# Per-Tenant Invoice Branding
+
+One SubTrackr deployment issues invoices on behalf of many merchants. An
+invoice's appearance is therefore a property of its **tenant**, not of the
+platform: two invoices from the same instance should look like they came from
+two different companies.
+
+| Piece | Where |
+|---|---|
+| Branding registry and resolution | `src/store/invoiceStore.ts` |
+| Rendering and delivery | `backend/services/billing/invoiceCustomizationService.ts` |
+| Types | `src/types/invoice.ts` |
+
+## Resolution order
+
+`resolveBranding(tenantId?)` layers three sources, most specific first:
+
+```
+tenant profile  →  platform default (InvoiceConfig)  →  built-in fallback
+```
+
+Merging is **field by field**, not all-or-nothing. A tenant that overrides only
+its logo still inherits the platform palette and font — otherwise every tenant
+would have to restate the entire theme to change one thing.
+
+The result reports which layer supplied it via `source`
+(`'tenant' | 'platform' | 'fallback'`), which is what the branding preview needs
+to tell a merchant whether they are looking at their own theme or the default.
+
+A tenant pointing at a template that has since been deleted falls back to the
+platform template rather than rendering nothing. `removeTemplate()` likewise
+clears `config.defaultTemplateId` when it removes the template it points at, so
+the config can never dangle.
+
+## Configuring a tenant
+
+```ts
+useInvoiceStore.getState().setTenantBranding('tenant-acme', {
+  displayName: 'Acme Inc.',
+  numberingPrefix: 'ACME',          // ACME-000001 instead of INV-000001
+  templateId: 'tpl-2',              // standard | modern | minimalist
+  branding: {
+    logoUrl: 'https://cdn.acme.example/logo.png',
+    primaryColor: '#ff5722',
+    secondaryColor: '#fff3e0',
+    accentColor: '#2e7d32',
+    fontFamily: 'Inter, sans-serif',
+    footerText: 'Payable within 14 days.',
+    supportEmail: 'billing@acme.example',
+    websiteUrl: 'https://acme.example',
+  },
+});
+```
+
+`setTenantBranding` and `updateTenantBranding` **throw** on an invalid profile
+rather than storing it — an invalid theme is caught at the settings screen, not
+at render time in front of a payer. `updateTenantBranding` validates the
+*merged* result, so a patch cannot make a stored profile invalid.
+
+`validateInvoiceBranding()` returns **every** problem rather than stopping at the
+first, so the branding editor can highlight all offending fields in one pass.
+
+## Rendering
+
+```ts
+const rendered = InvoiceCustomizationService.renderInvoice(invoice);
+rendered.html;   // self-contained document for the PDF pipeline
+rendered.text;   // plain-text alternative for the email body
+```
+
+Rendering is **deterministic and side-effect free**: the same invoice plus the
+same branding always produce byte-identical markup. That is what makes the
+output snapshot-testable, cacheable, and safe to re-render when a dispute needs
+the exact document a payer saw.
+
+Precedence within a render:
+
+1. `invoice.branding` — branding frozen onto the invoice when it was issued.
+2. The tenant profile as it stands now.
+
+An issued invoice keeps the brand it was issued under; a rebrand does not
+retroactively rewrite history. `previewForTenant()` deliberately ignores frozen
+branding, because a preview should show the profile as it is right now.
+
+## Security
+
+Every branding value is attacker-controlled — a tenant types it into a form —
+so all of it is escaped or scheme-checked before reaching the markup:
+
+| Field | Treatment |
+|---|---|
+| All text (`displayName`, line items, footer) | HTML-escaped, no exceptions |
+| Colours | Must match `#rgb`/`#rrggbb`, else replaced with the fallback |
+| `logoUrl` | Only `http(s):` and `data:image/` survive; `javascript:` is dropped |
+| `websiteUrl` | `http(s):` only |
+| `fontFamily` | Stripped to `[A-Za-z0-9 ,-]` — quotes and `;` would let a tenant close the CSS declaration and inject their own |
+| `logoWidth` | Clamped to 24–320pt |
+
+Validation at write time and sanitization at render time are both present on
+purpose: the store can be populated by a migration or a direct `setState` that
+never passed through validation, and the renderer is the last line before the
+document reaches a payer.
+
+## Storage
+
+Branding profiles and templates persist with the invoice store
+(`subtrackr-invoices`, schema v2). v1 payloads predate the registry; they
+migrate to an empty registry, which resolves to the platform defaults — exactly
+the v1 behaviour.
+
+## Testing
+
+- `src/store/__tests__/invoiceBranding.test.ts` — validation, registry CRUD,
+  resolution precedence, template fallback.
+- `backend/services/billing/__tests__/invoiceCustomizationService.test.ts` —
+  sanitization, escaping, layout selection, determinism, delivery.
diff --git a/docs/MULTI_CHAIN_SUBSCRIPTIONS.md b/docs/MULTI_CHAIN_SUBSCRIPTIONS.md
new file mode 100644
index 00000000..172a3023
--- /dev/null
+++ b/docs/MULTI_CHAIN_SUBSCRIPTIONS.md
@@ -0,0 +1,134 @@
+# Multi-Chain Subscriptions and Unified Billing
+
+A payer's subscriptions do not all live on one chain: one is funded from USDC on
+Polygon, another settles in XLM on Stellar. Left alone that produces one bill per
+chain, each denominated in its own asset — which is not a bill anyone can read.
+
+`src/services/multiChainSubscriptionService.ts` keeps the chain binding of every
+subscription and answers the two questions the rest of the app needs.
+
+## Chain bindings
+
+Each subscription carries a `ChainBinding`: chain type, chain id, network id,
+the token it is denominated in, and the wallet that funds it.
+
+```ts
+multiChainSubscriptionService.register({
+  subscriptionId: 'sub_1',
+  subscriberId: 'payer_1',
+  name: 'Pro Plan',
+  amount: 10,                       // denominated in binding.tokenSymbol
+  binding: {
+    chainType: ChainType.EVM,
+    chainId: 137,
+    networkId: 'polygon',
+    tokenSymbol: 'USDC',
+    walletAddress: '0x…',
+  },
+  nextBillingDate: new Date('2026-02-01'),
+  isActive: true,
+});
+```
+
+`rebind()` moves a subscription to another chain when a payer switches funding
+wallets. The billed amount does not change; only where it settles does.
+
+## Unified billing
+
+`buildUnifiedStatement()` converts every chain's charges into one currency:
+
+```ts
+const statement = multiChainSubscriptionService.buildUnifiedStatement('payer_1', {
+  currency: 'USD',
+  rates: [
+    { tokenSymbol: 'USDC', rate: 1,    asOf: new Date() },
+    { tokenSymbol: 'XLM',  rate: 0.25, asOf: new Date() },
+  ],
+  dueBefore: endOfMonth,
+});
+```
+
+The statement carries three views of the same charges:
+
+- `lines` — one per subscription, with the rate applied and both amounts.
+- `chainSubtotals` — per chain, keeping **native token totals** alongside the
+  converted total. Native amounts are what a payer checks against their wallet;
+  the converted figure is what they owe.
+- `total` — one number, in `currency`.
+
+### Unpriced subscriptions
+
+A subscription whose token has no rate is listed in `unpricedSubscriptionIds`
+and **excluded** from `total` — never silently treated as zero. A bill that
+quietly under-reports is worse than one that says what it could not price. The
+chain subtotal still shows the native amount, so nothing disappears from view.
+
+A token already denominated in the statement currency needs no rate.
+
+Rates are **injected**, not fetched here, so aggregation stays deterministic and
+testable; production wires in `oraclePriceService`.
+
+## Settlement planning
+
+`planSettlement()` decides how each due charge actually pays:
+
+| Action | When |
+|---|---|
+| `direct` | The subscription's own chain is healthy. |
+| `bridge` | That chain is down, but another chain the payer already uses holds enough of the same token. |
+| `blocked` | That chain is down and no funded alternative exists. |
+
+```ts
+const plan = multiChainSubscriptionService.planSettlement('payer_1', {
+  health: [{ networkId: 'polygon', healthy: false }],
+  balances: { 'arbitrum::USDC': 100 },   // see balanceKey()
+});
+```
+
+Three rules keep a plan honest:
+
+1. Fallback candidates are only chains the payer **already uses** — a plan never
+   invents a chain they have no wallet on.
+2. The fallback must hold enough of the **same token**; USDC on Arbitrum cannot
+   cover an XLM charge.
+3. The fallback must itself be healthy.
+
+When none holds, the step is `blocked` with a reason rather than dropped.
+Silently skipping an unpayable charge is how subscriptions lapse without anyone
+noticing.
+
+Chains absent from the `health` list are assumed healthy, so a caller can pass
+only the failures it knows about.
+
+Once a plan has `bridge` steps, `crossChainRoutingService.findPaymentRoute()`
+turns each one into an actual bridge route.
+
+## Cross-chain balances
+
+`WalletServiceManager.getBalancesAcrossChains()` fetches balances from several
+chains at once for the unified view:
+
+```ts
+const balances = await walletServiceManager.getBalancesAcrossChains('0x…', [1, 137, 42161]);
+balances.failedChainIds;   // chains that could not be read
+WalletServiceManager.totalsBySymbol(balances, 'USDC');   // { 137: 50, 42161: 25 }
+```
+
+Two deliberate choices:
+
+- **Failures are per chain, not fatal.** One unreachable RPC must not blank the
+  whole balances screen, so errors are reported alongside the chains that did
+  respond.
+- **`totalsBySymbol` returns a per-chain map, not a sum.** The same symbol on two
+  chains is not fungible; a single figure would imply it is, and a payer would
+  think a charge is covered when the funds sit on the wrong chain.
+
+Requests run in parallel — a serial walk over a handful of RPCs is the slowest
+thing on that screen.
+
+## Testing
+
+- `src/services/__tests__/multiChainSubscriptionService.test.ts`
+- `src/services/__tests__/walletMultiChain.test.ts`
+
+`MultiChainSubscriptionService` is a singleton; call `reset()` in `beforeEach`.
diff --git a/docs/USAGE_BASED_BILLING.md b/docs/USAGE_BASED_BILLING.md
new file mode 100644
index 00000000..45e96cce
--- /dev/null
+++ b/docs/USAGE_BASED_BILLING.md
@@ -0,0 +1,168 @@
+# Usage-Based Billing: Metered Pricing and Tiered Overages
+
+Metered billing runs in two halves, and keeping them in step is the whole point
+of this document:
+
+| | Where | Responsibility |
+|---|---|---|
+| **Off-chain rating** | `backend/services/billing/metering.ts` | Produces the invoice the payer reads. |
+| **On-chain rating** | `contracts/metering/` (`subtrackr-metering`) | Produces the charge the contract settles. |
+
+Both implement the same four pricing models with the same arithmetic. When they
+disagree, a payer is billed one number and charged another — which is a dispute,
+not a rounding error.
+
+Ingestion (dedup, clock skew, quota alerts) lives separately in
+`meteringService.ts`. This document is about *rating*: units → money.
+
+## Pricing models
+
+Included units are always free; the ladder rates only the **overage** on top.
+
+### `flat`
+
+Every billable unit costs `unitPrice`. No ladder needed.
+
+```
+1_000 included, $0.002/unit
+1_500 used → 500 billable → $1.00
+```
+
+### `graduated`
+
+Each slice of the overage is priced at the band it falls into. This is the model
+most SaaS pricing pages describe.
+
+```
+tiers: [ { upToUnits: 1_000, unitPrice: 3 }, { upToUnits: null, unitPrice: 1 } ]
+100 included, 1_600 used → 1_500 billable
+  → first 1_000 @ 3 = 3_000
+  → next    500 @ 1 =   500
+  → total            = 3_500
+```
+
+### `volume`
+
+The **whole** overage is priced at the rate of the single band the total lands
+in. Crossing a boundary re-prices everything, so the bill can fall as usage
+rises:
+
+```
+tiers: [ { upToUnits: 100, unitPrice: 10 }, { upToUnits: null, unitPrice: 4 } ]
+100 units → 100 × 10 = 1_000
+101 units → 101 ×  4 =   404   ← one more unit, cheaper bill
+```
+
+That cliff is intentional in volume pricing, but it surprises people. Use
+`marginalUnitPrice()` to show a payer what the next unit actually costs.
+
+### `package`
+
+Units are sold in whole blocks. `upToUnits` is read as the **block size** and
+`flatFee` as the price per block; partial blocks round up.
+
+```
+tiers: [ { upToUnits: 1_000, unitPrice: 0, flatFee: 25 } ]
+2_001 units → 3 started blocks → 75
+```
+
+## Ladder rules
+
+A ladder is rejected at configuration time unless:
+
+- bounds strictly ascend (no duplicates, no descending bands);
+- prices and flat fees are non-negative;
+- the unbounded band (`upToUnits: null` off-chain, `0` on-chain) is **last**, if
+  present.
+
+Every non-`flat` model requires at least one tier.
+
+If a `graduated` ladder is bounded and usage overflows its top band, the
+remainder bills at the meter's `unitPrice` rather than falling through as free.
+A truncated ladder silently billing zero is the worse failure.
+
+## Minimums, caps, and proration
+
+- `minimumCharge` — floor for the meter's period total. Reported as
+  `minimumAdjustment` (positive).
+- `maximumCharge` — spend cap. Reported as `maximumAdjustment` (negative).
+- `prorationFactor` — scales the **included allowance** only, so a mid-period
+  signup does not get a full month of free units. Consumed units always bill in
+  full.
+
+`RatedUsageBill.subtotal` is the raw sum of line amounts; `total` is the sum
+after adjustments. Both are reported so an invoice can show its own arithmetic.
+
+## Off-chain usage
+
+```ts
+import { rateUsage, quoteMeter, marginalUnitPrice } from './backend/services/billing/metering';
+
+const bill = rateUsage({
+  subscriptionId: 'sub_1',
+  period: { start, end },
+  usageByMetric: { api_calls: 1_600, gb_egress: 4 },
+  plans: [
+    {
+      metric: 'api_calls',
+      model: 'graduated',
+      includedUnits: 100,
+      unitPrice: 1,
+      tiers: [{ upToUnits: 1_000, unitPrice: 3 }, { upToUnits: null, unitPrice: 1 }],
+    },
+    { metric: 'gb_egress', model: 'flat', includedUnits: 0, unitPrice: 5 },
+  ],
+});
+```
+
+Rating is pure — it reads no store — so the same call prices a closed period, a
+mid-period estimate, and a "what would N units cost?" quote.
+
+## On-chain usage
+
+```rust
+client.register_tiered_meter(
+    &reporter, &subscription_id, &api_calls,
+    &0,        // unit_price — the fallback rate
+    &100,      // included_units
+    &86_400,   // bucket period
+    &0,        // alert threshold
+    &PricingModel::Graduated,
+    &tiers,
+);
+
+let charge = client.calculate_usage_charge(&subscription_id, &period);
+let quote  = client.quote_usage(&subscription_id, &api_calls, &1_600);
+```
+
+`register_meter` still exists and is unchanged: it registers a `Flat` meter with
+an empty ladder, so existing callers keep working.
+
+Reconfiguring a meter preserves its totals and buckets, so a mid-period price
+change **re-rates the same recorded usage** rather than resetting it.
+
+### Encoding differences
+
+The contract cannot express `null`, so the unbounded band is encoded as
+`up_to_units: 0`. Use `toContractTiers()` to convert — it validates first, so a
+ladder can never reach the chain in a shape the contract would reject:
+
+```ts
+toContractTiers([{ upToUnits: 1_000, unitPrice: 3 }, { upToUnits: null, unitPrice: 1 }]);
+// → [{ up_to_units: 1000, ... }, { up_to_units: 0, ... }]
+```
+
+`ChargeLine.tier_lines` (on-chain) and `RatedMeterLine.tierLines` (off-chain)
+carry the same per-band breakdown, which is what makes the two sides
+comparable when reconciling.
+
+## Testing
+
+- Off-chain: `backend/services/billing/__tests__/metering.test.ts`
+- On-chain: `contracts/metering/src/test.rs`
+
+Contract tests need the host target, because the workspace defaults to wasm32:
+
+```bash
+cd contracts && cargo test -p subtrackr-metering --target x86_64-unknown-linux-gnu
+```
diff --git a/src/services/__tests__/multiChainSubscriptionService.test.ts b/src/services/__tests__/multiChainSubscriptionService.test.ts
new file mode 100644
index 00000000..1a12a49c
--- /dev/null
+++ b/src/services/__tests__/multiChainSubscriptionService.test.ts
@@ -0,0 +1,313 @@
+import {
+  MultiChainSubscriptionService,
+  balanceKey,
+  type ChainBinding,
+  type ConversionRate,
+  type MultiChainSubscription,
+} from '../multiChainSubscriptionService';
+import { ChainType } from '../../types/wallet';
+
+const POLYGON: ChainBinding = {
+  chainType: ChainType.EVM,
+  chainId: 137,
+  networkId: 'polygon',
+  tokenSymbol: 'USDC',
+  walletAddress: '0xpayer',
+};
+
+const STELLAR: ChainBinding = {
+  chainType: ChainType.STELLAR,
+  chainId: 0x8000,
+  networkId: 'stellar-mainnet',
+  tokenSymbol: 'XLM',
+  walletAddress: 'GPAYER',
+};
+
+const ARBITRUM: ChainBinding = {
+  chainType: ChainType.EVM,
+  chainId: 42161,
+  networkId: 'arbitrum',
+  tokenSymbol: 'USDC',
+  walletAddress: '0xpayer',
+};
+
+const RATES: ConversionRate[] = [
+  { tokenSymbol: 'USDC', rate: 1, asOf: new Date('2026-01-01') },
+  { tokenSymbol: 'XLM', rate: 0.25, asOf: new Date('2026-01-01') },
+];
+
+const sub = (overrides: Partial<MultiChainSubscription> = {}): MultiChainSubscription => ({
+  subscriptionId: 'sub-1',
+  subscriberId: 'payer-1',
+  name: 'Pro Plan',
+  amount: 10,
+  binding: POLYGON,
+  nextBillingDate: new Date('2026-02-01T00:00:00.000Z'),
+  isActive: true,
+  ...overrides,
+});
+
+let service: MultiChainSubscriptionService;
+
+beforeEach(() => {
+  service = MultiChainSubscriptionService.getInstance();
+  service.reset();
+});
+
+describe('registration', () => {
+  it('registers and reads back a subscription', () => {
+    service.register(sub());
+    expect(service.get('sub-1')?.name).toBe('Pro Plan');
+    expect(service.list('payer-1')).toHaveLength(1);
+  });
+
+  it('rejects a subscription with no id', () => {
+    expect(() => service.register(sub({ subscriptionId: '' }))).toThrow(/requires a subscriptionId/);
+  });
+
+  it('rejects a negative or non-finite amount', () => {
+    expect(() => service.register(sub({ amount: -1 }))).toThrow(/negative or non-finite/);
+    expect(() => service.register(sub({ amount: Number.NaN }))).toThrow(/negative or non-finite/);
+  });
+
+  it('rejects a subscription with no network binding', () => {
+    expect(() =>
+      service.register(sub({ binding: { ...POLYGON, networkId: '' } }))
+    ).toThrow(/not bound to a network/);
+  });
+
+  it('scopes listings by subscriber', () => {
+    service.register(sub());
+    service.register(sub({ subscriptionId: 'sub-2', subscriberId: 'payer-2' }));
+    expect(service.list('payer-1')).toHaveLength(1);
+    expect(service.list()).toHaveLength(2);
+  });
+
+  it('lists the distinct networks a payer uses', () => {
+    service.register(sub());
+    service.register(sub({ subscriptionId: 'sub-2', binding: STELLAR }));
+    service.register(sub({ subscriptionId: 'sub-3', binding: POLYGON }));
+    expect(service.listNetworks('payer-1').sort()).toEqual(['polygon', 'stellar-mainnet']);
+  });
+
+  it('unregisters a subscription', () => {
+    service.register(sub());
+    expect(service.unregister('sub-1')).toBe(true);
+    expect(service.unregister('sub-1')).toBe(false);
+    expect(service.get('sub-1')).toBeUndefined();
+  });
+
+  it('rebinds a subscription to another chain without changing the amount', () => {
+    service.register(sub());
+    const rebound = service.rebind('sub-1', STELLAR);
+    expect(rebound?.binding.networkId).toBe('stellar-mainnet');
+    expect(rebound?.amount).toBe(10);
+    expect(service.get('sub-1')?.binding.tokenSymbol).toBe('XLM');
+  });
+
+  it('returns null when rebinding an unknown subscription', () => {
+    expect(service.rebind('nope', STELLAR)).toBeNull();
+  });
+});
+
+describe('buildUnifiedStatement', () => {
+  it('converts every chain into one currency and totals them', () => {
+    service.register(sub({ amount: 10, binding: POLYGON }));
+    service.register(sub({ subscriptionId: 'sub-2', amount: 40, binding: STELLAR }));
+
+    const statement = service.buildUnifiedStatement('payer-1', { rates: RATES });
+    expect(statement.currency).toBe('USD');
+    expect(statement.lines).toHaveLength(2);
+    // 10 USDC @ 1 + 40 XLM @ 0.25 = 20
+    expect(statement.total).toBe(20);
+  });
+
+  it('breaks the total down per chain, keeping native token amounts', () => {
+    service.register(sub({ amount: 10, binding: POLYGON }));
+    service.register(sub({ subscriptionId: 'sub-2', amount: 40, binding: STELLAR }));
+
+    const { chainSubtotals } = service.buildUnifiedStatement('payer-1', { rates: RATES });
+    const polygon = chainSubtotals.find((c) => c.networkId === 'polygon')!;
+    const stellar = chainSubtotals.find((c) => c.networkId === 'stellar-mainnet')!;
+
+    expect(polygon.nativeTotals).toEqual({ USDC: 10 });
+    expect(polygon.convertedTotal).toBe(10);
+    expect(stellar.nativeTotals).toEqual({ XLM: 40 });
+    expect(stellar.convertedTotal).toBe(10);
+    expect(stellar.chainType).toBe(ChainType.STELLAR);
+  });
+
+  it('sums several subscriptions on the same chain into one subtotal', () => {
+    service.register(sub({ subscriptionId: 'sub-1', amount: 10 }));
+    service.register(sub({ subscriptionId: 'sub-2', amount: 15 }));
+
+    const { chainSubtotals } = service.buildUnifiedStatement('payer-1', { rates: RATES });
+    expect(chainSubtotals).toHaveLength(1);
+    expect(chainSubtotals[0].subscriptionCount).toBe(2);
+    expect(chainSubtotals[0].nativeTotals.USDC).toBe(25);
+  });
+
+  it('needs no rate for a token already in the statement currency', () => {
+    service.register(sub({ amount: 10, binding: { ...POLYGON, tokenSymbol: 'USD' } }));
+    const statement = service.buildUnifiedStatement('payer-1', { rates: [] });
+    expect(statement.total).toBe(10);
+    expect(statement.unpricedSubscriptionIds).toEqual([]);
+  });
+
+  it('reports unpriced subscriptions instead of counting them as zero', () => {
+    service.register(sub({ amount: 10, binding: POLYGON }));
+    service.register(sub({ subscriptionId: 'sub-2', amount: 40, binding: STELLAR }));
+
+    const statement = service.buildUnifiedStatement('payer-1', {
+      rates: [{ tokenSymbol: 'USDC', rate: 1, asOf: new Date() }],
+    });
+    expect(statement.total).toBe(10);
+    expect(statement.unpricedSubscriptionIds).toEqual(['sub-2']);
+    expect(statement.lines).toHaveLength(1);
+    // The chain still appears with its native amount, so nothing goes missing.
+    const stellar = statement.chainSubtotals.find((c) => c.networkId === 'stellar-mainnet')!;
+    expect(stellar.nativeTotals.XLM).toBe(40);
+    expect(stellar.convertedTotal).toBe(0);
+  });
+
+  it('matches rates case-insensitively', () => {
+    service.register(sub({ amount: 10, binding: { ...POLYGON, tokenSymbol: 'usdc' } }));
+    const statement = service.buildUnifiedStatement('payer-1', { rates: RATES });
+    expect(statement.total).toBe(10);
+  });
+
+  it('excludes inactive subscriptions by default', () => {
+    service.register(sub({ isActive: false }));
+    expect(service.buildUnifiedStatement('payer-1', { rates: RATES }).lines).toHaveLength(0);
+    expect(
+      service.buildUnifiedStatement('payer-1', { rates: RATES, includeInactive: true }).lines
+    ).toHaveLength(1);
+  });
+
+  it('filters to charges due before a cutoff', () => {
+    service.register(sub({ nextBillingDate: new Date('2026-01-15T00:00:00.000Z') }));
+    service.register(
+      sub({ subscriptionId: 'sub-2', nextBillingDate: new Date('2026-03-01T00:00:00.000Z') })
+    );
+
+    const statement = service.buildUnifiedStatement('payer-1', {
+      rates: RATES,
+      dueBefore: new Date('2026-02-01T00:00:00.000Z'),
+    });
+    expect(statement.lines.map((l) => l.subscriptionId)).toEqual(['sub-1']);
+  });
+
+  it('honours a non-USD statement currency', () => {
+    service.register(sub({ amount: 8, binding: STELLAR }));
+    const statement = service.buildUnifiedStatement('payer-1', {
+      currency: 'EUR',
+      rates: [{ tokenSymbol: 'XLM', rate: 0.5, asOf: new Date() }],
+    });
+    expect(statement.currency).toBe('EUR');
+    expect(statement.total).toBe(4);
+  });
+
+  it('returns an empty statement for a payer with nothing registered', () => {
+    const statement = service.buildUnifiedStatement('nobody', { rates: RATES });
+    expect(statement.total).toBe(0);
+    expect(statement.lines).toEqual([]);
+    expect(statement.chainSubtotals).toEqual([]);
+  });
+});
+
+describe('planSettlement', () => {
+  it('settles directly when every chain is healthy', () => {
+    service.register(sub());
+    service.register(sub({ subscriptionId: 'sub-2', binding: STELLAR }));
+
+    const plan = service.planSettlement('payer-1');
+    expect(plan.steps.every((s) => s.action === 'direct')).toBe(true);
+    expect(plan.bridgedCount).toBe(0);
+    expect(plan.blockedCount).toBe(0);
+  });
+
+  it('treats a chain absent from the health list as healthy', () => {
+    service.register(sub());
+    const plan = service.planSettlement('payer-1', {
+      health: [{ networkId: 'some-other-chain', healthy: false }],
+    });
+    expect(plan.steps[0].action).toBe('direct');
+  });
+
+  it('bridges from another funded chain when the target is down', () => {
+    service.register(sub({ binding: POLYGON, amount: 10 }));
+    service.register(sub({ subscriptionId: 'sub-2', binding: ARBITRUM, amount: 5 }));
+
+    const plan = service.planSettlement('payer-1', {
+      health: [{ networkId: 'polygon', healthy: false }],
+      balances: { [balanceKey('arbitrum', 'USDC')]: 100 },
+    });
+
+    const bridged = plan.steps.find((s) => s.subscriptionId === 'sub-1')!;
+    expect(bridged.action).toBe('bridge');
+    expect(bridged.sourceNetworkId).toBe('arbitrum');
+    expect(bridged.targetNetworkId).toBe('polygon');
+    expect(bridged.reason).toContain('polygon is unavailable');
+    expect(plan.bridgedCount).toBe(1);
+  });
+
+  it('blocks when the fallback chain lacks enough of the token', () => {
+    service.register(sub({ binding: POLYGON, amount: 10 }));
+    service.register(sub({ subscriptionId: 'sub-2', binding: ARBITRUM, amount: 5 }));
+
+    const plan = service.planSettlement('payer-1', {
+      health: [{ networkId: 'polygon', healthy: false }],
+      balances: { [balanceKey('arbitrum', 'USDC')]: 3 },
+    });
+
+    const blocked = plan.steps.find((s) => s.subscriptionId === 'sub-1')!;
+    expect(blocked.action).toBe('blocked');
+    expect(blocked.reason).toContain('no other chain holds enough USDC');
+    expect(plan.blockedCount).toBe(1);
+  });
+
+  it('blocks when the payer uses only the failed chain', () => {
+    service.register(sub({ binding: POLYGON }));
+    const plan = service.planSettlement('payer-1', {
+      health: [{ networkId: 'polygon', healthy: false }],
+    });
+    expect(plan.steps[0].action).toBe('blocked');
+  });
+
+  it('will not route through another unhealthy chain', () => {
+    service.register(sub({ binding: POLYGON, amount: 10 }));
+    service.register(sub({ subscriptionId: 'sub-2', binding: ARBITRUM, amount: 5 }));
+
+    const plan = service.planSettlement('payer-1', {
+      health: [
+        { networkId: 'polygon', healthy: false },
+        { networkId: 'arbitrum', healthy: false },
+      ],
+      balances: { [balanceKey('arbitrum', 'USDC')]: 100 },
+    });
+    expect(plan.blockedCount).toBe(2);
+  });
+
+  it('will not route a token the fallback chain does not hold', () => {
+    // The fallback holds USDC, but the failed charge is denominated in XLM.
+    service.register(sub({ binding: STELLAR, amount: 10 }));
+    service.register(sub({ subscriptionId: 'sub-2', binding: ARBITRUM, amount: 5 }));
+
+    const plan = service.planSettlement('payer-1', {
+      health: [{ networkId: 'stellar-mainnet', healthy: false }],
+      balances: { [balanceKey('arbitrum', 'USDC')]: 100 },
+    });
+    expect(plan.steps.find((s) => s.subscriptionId === 'sub-1')?.action).toBe('blocked');
+  });
+
+  it('skips inactive subscriptions', () => {
+    service.register(sub({ isActive: false }));
+    expect(service.planSettlement('payer-1').steps).toHaveLength(0);
+  });
+});
+
+describe('balanceKey', () => {
+  it('namespaces a token by its chain', () => {
+    expect(balanceKey('polygon', 'USDC')).toBe('polygon::USDC');
+  });
+});
diff --git a/src/services/__tests__/walletMultiChain.test.ts b/src/services/__tests__/walletMultiChain.test.ts
new file mode 100644
index 00000000..652f6b13
--- /dev/null
+++ b/src/services/__tests__/walletMultiChain.test.ts
@@ -0,0 +1,113 @@
+import { WalletServiceManager, type MultiChainBalances } from '../walletService';
+
+const manager = WalletServiceManager.getInstance();
+
+const balance = (symbol: string, amount: string) => ({
+  symbol,
+  name: symbol,
+  address: `0x${symbol}`,
+  balance: amount,
+  decimals: 6,
+});
+
+describe('getBalancesAcrossChains', () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('collects balances from every requested chain', async () => {
+    jest
+      .spyOn(manager, 'getTokenBalances')
+      .mockImplementation(async (_address, chainId) =>
+        chainId === 137 ? [balance('USDC', '50')] : [balance('USDC', '25')]
+      );
+
+    const result = await manager.getBalancesAcrossChains('0xpayer', [137, 42161]);
+    expect(result.address).toBe('0xpayer');
+    expect(result.results.map((r) => r.chainId)).toEqual([137, 42161]);
+    expect(result.failedChainIds).toEqual([]);
+  });
+
+  it('reports a failing chain without losing the others', async () => {
+    jest.spyOn(manager, 'getTokenBalances').mockImplementation(async (_address, chainId) => {
+      if (chainId === 42161) throw new Error('RPC unreachable');
+      return [balance('USDC', '50')];
+    });
+
+    const result = await manager.getBalancesAcrossChains('0xpayer', [137, 42161]);
+    expect(result.failedChainIds).toEqual([42161]);
+
+    const failed = result.results.find((r) => r.chainId === 42161)!;
+    expect(failed.error).toBe('RPC unreachable');
+    expect(failed.balances).toEqual([]);
+
+    // The healthy chain still returned its data.
+    expect(result.results.find((r) => r.chainId === 137)?.balances).toHaveLength(1);
+  });
+
+  it('queries the chains in parallel', async () => {
+    let inFlight = 0;
+    let peak = 0;
+    jest.spyOn(manager, 'getTokenBalances').mockImplementation(async () => {
+      inFlight += 1;
+      peak = Math.max(peak, inFlight);
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      inFlight -= 1;
+      return [balance('USDC', '1')];
+    });
+
+    await manager.getBalancesAcrossChains('0xpayer', [1, 137, 42161]);
+    expect(peak).toBe(3);
+  });
+
+  it('returns an empty result for an empty chain list', async () => {
+    const result = await manager.getBalancesAcrossChains('0xpayer', []);
+    expect(result.results).toEqual([]);
+    expect(result.failedChainIds).toEqual([]);
+  });
+});
+
+describe('totalsBySymbol', () => {
+  const balances: MultiChainBalances = {
+    address: '0xpayer',
+    results: [
+      { chainId: 137, balances: [balance('USDC', '50'), balance('MATIC', '3')] },
+      { chainId: 42161, balances: [balance('USDC', '25')] },
+      { chainId: 1, balances: [], error: 'down' },
+    ],
+    failedChainIds: [1],
+  };
+
+  it('keeps holdings separated by chain rather than summing them', () => {
+    // The same symbol on two chains is not fungible, so it must not collapse
+    // into one figure.
+    expect(WalletServiceManager.totalsBySymbol(balances, 'USDC')).toEqual({
+      137: 50,
+      42161: 25,
+    });
+  });
+
+  it('matches the symbol case-insensitively', () => {
+    expect(WalletServiceManager.totalsBySymbol(balances, 'usdc')).toEqual({
+      137: 50,
+      42161: 25,
+    });
+  });
+
+  it('omits chains that do not hold the token', () => {
+    expect(WalletServiceManager.totalsBySymbol(balances, 'MATIC')).toEqual({ 137: 3 });
+  });
+
+  it('returns nothing for an unheld token', () => {
+    expect(WalletServiceManager.totalsBySymbol(balances, 'DAI')).toEqual({});
+  });
+
+  it('reads an unparseable balance as zero rather than NaN', () => {
+    const broken: MultiChainBalances = {
+      address: '0xpayer',
+      results: [{ chainId: 137, balances: [balance('USDC', 'not-a-number')] }],
+      failedChainIds: [],
+    };
+    expect(WalletServiceManager.totalsBySymbol(broken, 'USDC')).toEqual({ 137: 0 });
+  });
+});
diff --git a/src/services/multiChainSubscriptionService.ts b/src/services/multiChainSubscriptionService.ts
new file mode 100644
index 00000000..7217bdf4
--- /dev/null
+++ b/src/services/multiChainSubscriptionService.ts
@@ -0,0 +1,396 @@
+/**
+ * Multi-chain subscription management with unified billing.
+ *
+ * A payer's subscriptions do not all live on one chain: one is funded from
+ * USDC on Polygon, another settles in XLM on Stellar. Left alone that produces
+ * one bill per chain, each in its own asset, which is not a bill anyone can
+ * read.
+ *
+ * This service keeps the chain binding of every subscription, then answers two
+ * questions the rest of the app needs:
+ *
+ *  1. *Unified billing* — what does this payer owe in total, in one currency,
+ *     across every chain? (`buildUnifiedStatement`)
+ *  2. *Settlement* — which wallet on which chain actually pays each charge, and
+ *     what has to bridge? (`planSettlement`)
+ *
+ * Conversion rates and chain health are injected rather than fetched here, so
+ * the aggregation logic stays deterministic and testable; production wires in
+ * `oraclePriceService` and `networkService` respectively.
+ */
+
+import { ChainType } from '../types/wallet';
+
+/** Where a subscription is billed, and from which wallet. */
+export interface ChainBinding {
+  chainType: ChainType;
+  /** EVM chain id, or the Stellar network id from `src/config/networks.ts`. */
+  chainId: number;
+  networkId: string;
+  /** Asset the subscription is denominated in, e.g. `USDC`, `XLM`. */
+  tokenSymbol: string;
+  /** Wallet that funds this subscription on that chain. */
+  walletAddress: string;
+}
+
+export interface MultiChainSubscription {
+  subscriptionId: string;
+  subscriberId: string;
+  name: string;
+  /** Charge amount per period, denominated in `binding.tokenSymbol`. */
+  amount: number;
+  binding: ChainBinding;
+  nextBillingDate: Date;
+  isActive: boolean;
+}
+
+/** Rate of one token against the statement currency. */
+export interface ConversionRate {
+  tokenSymbol: string;
+  /** How many units of the statement currency one token is worth. */
+  rate: number;
+  asOf: Date;
+}
+
+export interface ChainHealth {
+  networkId: string;
+  healthy: boolean;
+  latencyMs?: number;
+}
+
+export interface UnifiedStatementLine {
+  subscriptionId: string;
+  name: string;
+  networkId: string;
+  chainType: ChainType;
+  tokenSymbol: string;
+  /** Amount in the subscription's own token. */
+  nativeAmount: number;
+  /** Rate applied to reach `convertedAmount`. */
+  rate: number;
+  /** Amount in the statement currency. */
+  convertedAmount: number;
+  nextBillingDate: Date;
+}
+
+export interface ChainSubtotal {
+  networkId: string;
+  chainType: ChainType;
+  subscriptionCount: number;
+  /** Per-token totals in each token's own units. */
+  nativeTotals: Record<string, number>;
+  convertedTotal: number;
+}
+
+export interface UnifiedStatement {
+  subscriberId: string;
+  currency: string;
+  generatedAt: Date;
+  lines: UnifiedStatementLine[];
+  /** One entry per chain the payer has active subscriptions on. */
+  chainSubtotals: ChainSubtotal[];
+  total: number;
+  /**
+   * Subscriptions left out because no conversion rate was available. Their
+   * amounts are excluded from `total` rather than silently counted as zero.
+   */
+  unpricedSubscriptionIds: string[];
+}
+
+export type SettlementAction = 'direct' | 'bridge' | 'blocked';
+
+export interface SettlementStep {
+  subscriptionId: string;
+  action: SettlementAction;
+  /** Chain the funds come from. */
+  sourceNetworkId: string;
+  /** Chain the charge settles on. */
+  targetNetworkId: string;
+  tokenSymbol: string;
+  amount: number;
+  reason?: string;
+}
+
+export interface SettlementPlan {
+  subscriberId: string;
+  steps: SettlementStep[];
+  /** Steps needing a cross-chain transfer before they can settle. */
+  bridgedCount: number;
+  /** Steps that cannot proceed — unhealthy chain with no funded alternative. */
+  blockedCount: number;
+}
+
+export interface UnifiedStatementOptions {
+  currency?: string;
+  rates?: ConversionRate[];
+  /** Only include subscriptions due on or before this instant. */
+  dueBefore?: Date;
+  includeInactive?: boolean;
+}
+
+export interface SettlementOptions {
+  /** Chain health snapshot; chains absent from the list are assumed healthy. */
+  health?: ChainHealth[];
+  /**
+   * Spendable balance per `networkId::tokenSymbol`. A charge on an unhealthy
+   * chain reroutes to another chain holding enough of the same token.
+   */
+  balances?: Record<string, number>;
+}
+
+const DEFAULT_CURRENCY = 'USD';
+
+export const balanceKey = (networkId: string, tokenSymbol: string): string =>
+  `${networkId}::${tokenSymbol}`;
+
+export class MultiChainSubscriptionService {
+  private static instance: MultiChainSubscriptionService;
+
+  private subscriptions = new Map<string, MultiChainSubscription>();
+
+  static getInstance(): MultiChainSubscriptionService {
+    if (!MultiChainSubscriptionService.instance) {
+      MultiChainSubscriptionService.instance = new MultiChainSubscriptionService();
+    }
+    return MultiChainSubscriptionService.instance;
+  }
+
+  register(subscription: MultiChainSubscription): MultiChainSubscription {
+    if (!subscription.subscriptionId) {
+      throw new Error('A multi-chain subscription requires a subscriptionId');
+    }
+    if (!Number.isFinite(subscription.amount) || subscription.amount < 0) {
+      throw new Error(
+        `Subscription ${subscription.subscriptionId} has a negative or non-finite amount`
+      );
+    }
+    if (!subscription.binding?.networkId) {
+      throw new Error(
+        `Subscription ${subscription.subscriptionId} is not bound to a network`
+      );
+    }
+    this.subscriptions.set(subscription.subscriptionId, subscription);
+    return subscription;
+  }
+
+  unregister(subscriptionId: string): boolean {
+    return this.subscriptions.delete(subscriptionId);
+  }
+
+  get(subscriptionId: string): MultiChainSubscription | undefined {
+    return this.subscriptions.get(subscriptionId);
+  }
+
+  list(subscriberId?: string): MultiChainSubscription[] {
+    const all = Array.from(this.subscriptions.values());
+    return subscriberId ? all.filter((s) => s.subscriberId === subscriberId) : all;
+  }
+
+  /** Distinct networks a payer currently holds subscriptions on. */
+  listNetworks(subscriberId: string): string[] {
+    return Array.from(new Set(this.list(subscriberId).map((s) => s.binding.networkId)));
+  }
+
+  /**
+   * Moves a subscription to a different chain — the migration path when a payer
+   * switches funding wallets. The billed amount is unchanged; only where it
+   * settles moves.
+   */
+  rebind(subscriptionId: string, binding: ChainBinding): MultiChainSubscription | null {
+    const subscription = this.subscriptions.get(subscriptionId);
+    if (!subscription) return null;
+    const updated = { ...subscription, binding };
+    this.subscriptions.set(subscriptionId, updated);
+    return updated;
+  }
+
+  /**
+   * Aggregates every chain's charges into one statement in a single currency.
+   *
+   * A subscription whose token has no rate is reported in
+   * `unpricedSubscriptionIds` and excluded from the total — a bill that quietly
+   * under-reports is worse than one that says what it could not price.
+   */
+  buildUnifiedStatement(
+    subscriberId: string,
+    options: UnifiedStatementOptions = {}
+  ): UnifiedStatement {
+    const currency = options.currency ?? DEFAULT_CURRENCY;
+    const rateBySymbol = new Map(
+      (options.rates ?? []).map((r) => [r.tokenSymbol.toUpperCase(), r.rate])
+    );
+
+    const candidates = this.list(subscriberId).filter((s) => {
+      if (!options.includeInactive && !s.isActive) return false;
+      if (options.dueBefore && s.nextBillingDate.getTime() > options.dueBefore.getTime()) {
+        return false;
+      }
+      return true;
+    });
+
+    const lines: UnifiedStatementLine[] = [];
+    const unpricedSubscriptionIds: string[] = [];
+    const subtotals = new Map<string, ChainSubtotal>();
+    let total = 0;
+
+    for (const subscription of candidates) {
+      const { binding } = subscription;
+      const symbol = binding.tokenSymbol.toUpperCase();
+      // A subscription already denominated in the statement currency needs no
+      // rate; anything else does.
+      const rate = symbol === currency.toUpperCase() ? 1 : rateBySymbol.get(symbol);
+
+      let subtotal = subtotals.get(binding.networkId);
+      if (!subtotal) {
+        subtotal = {
+          networkId: binding.networkId,
+          chainType: binding.chainType,
+          subscriptionCount: 0,
+          nativeTotals: {},
+          convertedTotal: 0,
+        };
+        subtotals.set(binding.networkId, subtotal);
+      }
+      subtotal.subscriptionCount += 1;
+      subtotal.nativeTotals[binding.tokenSymbol] =
+        (subtotal.nativeTotals[binding.tokenSymbol] ?? 0) + subscription.amount;
+
+      if (rate === undefined) {
+        unpricedSubscriptionIds.push(subscription.subscriptionId);
+        continue;
+      }
+
+      const convertedAmount = subscription.amount * rate;
+      subtotal.convertedTotal += convertedAmount;
+      total += convertedAmount;
+
+      lines.push({
+        subscriptionId: subscription.subscriptionId,
+        name: subscription.name,
+        networkId: binding.networkId,
+        chainType: binding.chainType,
+        tokenSymbol: binding.tokenSymbol,
+        nativeAmount: subscription.amount,
+        rate,
+        convertedAmount,
+        nextBillingDate: subscription.nextBillingDate,
+      });
+    }
+
+    return {
+      subscriberId,
+      currency,
+      generatedAt: new Date(),
+      lines,
+      chainSubtotals: Array.from(subtotals.values()),
+      total,
+      unpricedSubscriptionIds,
+    };
+  }
+
+  /**
+   * Decides how each due charge settles.
+   *
+   * A charge settles directly when its own chain is healthy. When that chain is
+   * down, the plan looks for another chain where the payer holds enough of the
+   * same token and routes through a bridge; with no such chain the step is
+   * blocked rather than silently dropped.
+   */
+  planSettlement(
+    subscriberId: string,
+    options: SettlementOptions = {}
+  ): SettlementPlan {
+    const healthByNetwork = new Map(
+      (options.health ?? []).map((h) => [h.networkId, h.healthy])
+    );
+    const balances = options.balances ?? {};
+    const isHealthy = (networkId: string): boolean =>
+      healthByNetwork.get(networkId) ?? true;
+
+    const steps: SettlementStep[] = [];
+
+    for (const subscription of this.list(subscriberId)) {
+      if (!subscription.isActive) continue;
+
+      const { binding } = subscription;
+      const target = binding.networkId;
+
+      if (isHealthy(target)) {
+        steps.push({
+          subscriptionId: subscription.subscriptionId,
+          action: 'direct',
+          sourceNetworkId: target,
+          targetNetworkId: target,
+          tokenSymbol: binding.tokenSymbol,
+          amount: subscription.amount,
+        });
+        continue;
+      }
+
+      const fallback = this.findFundedAlternative(
+        subscriberId,
+        binding,
+        subscription.amount,
+        balances,
+        isHealthy
+      );
+
+      if (fallback) {
+        steps.push({
+          subscriptionId: subscription.subscriptionId,
+          action: 'bridge',
+          sourceNetworkId: fallback,
+          targetNetworkId: target,
+          tokenSymbol: binding.tokenSymbol,
+          amount: subscription.amount,
+          reason: `${target} is unavailable; routing ${binding.tokenSymbol} from ${fallback}`,
+        });
+      } else {
+        steps.push({
+          subscriptionId: subscription.subscriptionId,
+          action: 'blocked',
+          sourceNetworkId: target,
+          targetNetworkId: target,
+          tokenSymbol: binding.tokenSymbol,
+          amount: subscription.amount,
+          reason: `${target} is unavailable and no other chain holds enough ${binding.tokenSymbol}`,
+        });
+      }
+    }
+
+    return {
+      subscriberId,
+      steps,
+      bridgedCount: steps.filter((s) => s.action === 'bridge').length,
+      blockedCount: steps.filter((s) => s.action === 'blocked').length,
+    };
+  }
+
+  /**
+   * Finds a healthy chain, other than the failed one, where the payer holds
+   * enough of the same token. Candidates are the chains the payer already uses,
+   * so a plan never invents a chain the payer has no wallet on.
+   */
+  private findFundedAlternative(
+    subscriberId: string,
+    binding: ChainBinding,
+    amount: number,
+    balances: Record<string, number>,
+    isHealthy: (networkId: string) => boolean
+  ): string | null {
+    for (const networkId of this.listNetworks(subscriberId)) {
+      if (networkId === binding.networkId) continue;
+      if (!isHealthy(networkId)) continue;
+      const available = balances[balanceKey(networkId, binding.tokenSymbol)] ?? 0;
+      if (available >= amount) return networkId;
+    }
+    return null;
+  }
+
+  /** Clears registered subscriptions. Intended for tests and sign-out. */
+  reset(): void {
+    this.subscriptions.clear();
+  }
+}
+
+export const multiChainSubscriptionService = MultiChainSubscriptionService.getInstance();
diff --git a/src/services/walletService.ts b/src/services/walletService.ts
index 67167bfa..5e71ac87 100644
--- a/src/services/walletService.ts
+++ b/src/services/walletService.ts
@@ -120,6 +120,20 @@ export interface GasEstimate {
   estimatedCost: string;
 }
 
+/** Balances for one chain within a multi-chain fetch, or why that chain failed. */
+export interface ChainBalanceResult {
+  chainId: number;
+  balances: TokenBalance[];
+  error?: string;
+}
+
+export interface MultiChainBalances {
+  address: string;
+  results: ChainBalanceResult[];
+  /** Chains whose balances could not be read; their results are empty. */
+  failedChainIds: number[];
+}
+
 /** Result after an on-chain Superfluid CFA stream is created */
 export interface SuperfluidStreamResult {
   txHash: string;
@@ -713,6 +727,62 @@ export class WalletServiceManager {
   isConnected(): boolean {
     return this.connection?.isConnected || false;
   }
+
+  /**
+   * Fetches balances across several chains at once, for the unified
+   * multi-chain view (see `multiChainSubscriptionService`).
+   *
+   * One unreachable chain must not blank the whole view, so failures are
+   * reported per chain instead of rejecting the call. Requests run in parallel
+   * because a serial walk over a handful of RPCs is the slowest thing on the
+   * balances screen.
+   */
+  async getBalancesAcrossChains(
+    address: string,
+    chainIds: number[]
+  ): Promise<MultiChainBalances> {
+    const settled = await Promise.all(
+      chainIds.map(async (chainId): Promise<ChainBalanceResult> => {
+        try {
+          return { chainId, balances: await this.getTokenBalances(address, chainId) };
+        } catch (error) {
+          return {
+            chainId,
+            balances: [],
+            error: error instanceof Error ? error.message : String(error),
+          };
+        }
+      })
+    );
+
+    return {
+      address,
+      results: settled,
+      failedChainIds: settled.filter((r) => r.error !== undefined).map((r) => r.chainId),
+    };
+  }
+
+  /**
+   * Total holdings of one token across chains, keyed by chain id.
+   *
+   * Balances stay per chain rather than being summed: the same symbol on two
+   * chains is not fungible, and a single figure would imply it is.
+   */
+  static totalsBySymbol(
+    balances: MultiChainBalances,
+    symbol: string
+  ): Record<number, number> {
+    const wanted = symbol.toUpperCase();
+    const totals: Record<number, number> = {};
+    for (const result of balances.results) {
+      const match = result.balances.find((b) => b.symbol.toUpperCase() === wanted);
+      if (match) {
+        const parsed = Number(match.balance);
+        totals[result.chainId] = Number.isFinite(parsed) ? parsed : 0;
+      }
+    }
+    return totals;
+  }
 }
 
 // ── Payment method management ───────────────────────────────────────
diff --git a/src/store/__tests__/invoiceBranding.test.ts b/src/store/__tests__/invoiceBranding.test.ts
new file mode 100644
index 00000000..105af82a
--- /dev/null
+++ b/src/store/__tests__/invoiceBranding.test.ts
@@ -0,0 +1,296 @@
+// The store reaches for expo-notifications when an invoice is sent; that
+// native module is unavailable under Jest, so stub the whole service.
+import { useInvoiceStore, validateInvoiceBranding } from '../invoiceStore';
+import { DEFAULT_INVOICE_CONFIG, InvoiceStatus } from '../../types/invoice';
+import type { Invoice } from '../../types/invoice';
+
+// The store reaches for expo-notifications when an invoice is sent; that native
+// module is unavailable under Jest, so stub the whole service. babel-jest
+// hoists this above the imports at transform time.
+jest.mock('../../services/notificationService', () => ({
+  presentLocalNotification: jest.fn(() => Promise.resolve()),
+}));
+
+jest.mock('../../services/notificationService', () => ({
+  presentLocalNotification: jest.fn(() => Promise.resolve()),
+}));
+
+const resetStore = () => {
+  useInvoiceStore.setState({
+    invoices: [],
+    config: { ...DEFAULT_INVOICE_CONFIG },
+    nextSequence: 1,
+    isLoading: false,
+    error: null,
+    brandingProfiles: {},
+    templates: [
+      { id: 'tpl-1', name: 'Standard', layout: 'standard' },
+      { id: 'tpl-2', name: 'Modern', layout: 'modern' },
+      { id: 'tpl-3', name: 'Minimalist', layout: 'minimalist' },
+    ],
+  });
+};
+
+const makeInvoice = (overrides: Partial<Invoice> = {}): Invoice => ({
+  id: 'inv-1',
+  invoiceNumber: 'INV-000001',
+  subscriptionId: 'sub-1',
+  subscriptionName: 'Pro Plan',
+  merchantName: 'Platform Merchant',
+  lineItems: [],
+  tax: 0,
+  subtotal: 100,
+  total: 100,
+  dueDate: new Date('2026-02-01T00:00:00.000Z'),
+  status: InvoiceStatus.DRAFT,
+  currency: 'USD',
+  region: 'GLOBAL',
+  exchangeRate: 1_000_000,
+  period: {
+    start: new Date('2026-01-01T00:00:00.000Z'),
+    end: new Date('2026-02-01T00:00:00.000Z'),
+  },
+  createdAt: new Date('2026-01-01T00:00:00.000Z'),
+  updatedAt: new Date('2026-01-01T00:00:00.000Z'),
+  ...overrides,
+});
+
+beforeEach(resetStore);
+
+describe('validateInvoiceBranding', () => {
+  it('accepts a fully specified valid profile', () => {
+    expect(
+      validateInvoiceBranding({
+        logoUrl: 'https://cdn.example.com/logo.png',
+        primaryColor: '#1a73e8',
+        secondaryColor: '#fff',
+        accentColor: '#188038',
+        textColor: '#202124',
+        fontFamily: 'Inter, sans-serif',
+        logoWidth: 120,
+        supportEmail: 'billing@example.com',
+        websiteUrl: 'https://example.com',
+      })
+    ).toEqual([]);
+  });
+
+  it('accepts an empty profile', () => {
+    expect(validateInvoiceBranding({})).toEqual([]);
+  });
+
+  it('rejects malformed hex colours', () => {
+    const errors = validateInvoiceBranding({ primaryColor: 'red', accentColor: '#12345' });
+    expect(errors).toHaveLength(2);
+    expect(errors[0]).toMatch(/primaryColor/);
+    expect(errors[1]).toMatch(/accentColor/);
+  });
+
+  it('rejects a logo URL with an unsafe scheme', () => {
+    expect(validateInvoiceBranding({ logoUrl: 'javascript:alert(1)' })).toEqual([
+      'logoUrl must be an http(s) or data:image URL',
+    ]);
+  });
+
+  it('accepts an inline data image logo', () => {
+    expect(validateInvoiceBranding({ logoUrl: 'data:image/png;base64,AAAA' })).toEqual([]);
+  });
+
+  it('rejects a non-positive logo width', () => {
+    expect(validateInvoiceBranding({ logoWidth: 0 })).toEqual([
+      'logoWidth must be a positive number',
+    ]);
+  });
+
+  it('rejects a malformed support email and website', () => {
+    const errors = validateInvoiceBranding({
+      supportEmail: 'not-an-email',
+      websiteUrl: 'ftp://example.com',
+    });
+    expect(errors).toHaveLength(2);
+  });
+
+  it('reports every problem at once rather than stopping at the first', () => {
+    expect(
+      validateInvoiceBranding({ primaryColor: 'nope', logoUrl: 'javascript:x', logoWidth: -1 })
+    ).toHaveLength(3);
+  });
+});
+
+describe('tenant branding registry', () => {
+  it('stores and reads back a tenant profile', () => {
+    const store = useInvoiceStore.getState();
+    const saved = store.setTenantBranding('tenant-a', {
+      displayName: 'Acme Inc.',
+      branding: { primaryColor: '#ff0000' },
+      templateId: 'tpl-2',
+    });
+
+    expect(saved.tenantId).toBe('tenant-a');
+    expect(saved.updatedAt).toBeInstanceOf(Date);
+    expect(useInvoiceStore.getState().getTenantBranding('tenant-a')?.displayName).toBe('Acme Inc.');
+  });
+
+  it('rejects an invalid profile instead of storing it', () => {
+    const store = useInvoiceStore.getState();
+    expect(() =>
+      store.setTenantBranding('tenant-a', { branding: { primaryColor: 'not-a-colour' } })
+    ).toThrow(/Invalid branding for tenant tenant-a/);
+    expect(useInvoiceStore.getState().getTenantBranding('tenant-a')).toBeUndefined();
+  });
+
+  it('merges a partial update onto the stored branding', () => {
+    const store = useInvoiceStore.getState();
+    store.setTenantBranding('tenant-a', {
+      branding: { primaryColor: '#ff0000', fontFamily: 'Inter' },
+    });
+    const updated = useInvoiceStore
+      .getState()
+      .updateTenantBranding('tenant-a', { branding: { primaryColor: '#00ff00' } });
+
+    expect(updated?.branding.primaryColor).toBe('#00ff00');
+    // Untouched fields survive the patch.
+    expect(updated?.branding.fontFamily).toBe('Inter');
+  });
+
+  it('validates the merged result of a partial update', () => {
+    const store = useInvoiceStore.getState();
+    store.setTenantBranding('tenant-a', { branding: { primaryColor: '#ff0000' } });
+    expect(() =>
+      useInvoiceStore.getState().updateTenantBranding('tenant-a', {
+        branding: { primaryColor: 'bad' },
+      })
+    ).toThrow(/Invalid branding/);
+  });
+
+  it('returns null when updating an unknown tenant', () => {
+    expect(useInvoiceStore.getState().updateTenantBranding('nope', {})).toBeNull();
+  });
+
+  it('removes a profile', () => {
+    const store = useInvoiceStore.getState();
+    store.setTenantBranding('tenant-a', { branding: {} });
+    useInvoiceStore.getState().removeTenantBranding('tenant-a');
+    expect(useInvoiceStore.getState().getTenantBranding('tenant-a')).toBeUndefined();
+  });
+
+  it('removing an unknown tenant is a no-op', () => {
+    useInvoiceStore.getState().setTenantBranding('tenant-a', { branding: {} });
+    useInvoiceStore.getState().removeTenantBranding('nope');
+    expect(useInvoiceStore.getState().listTenantBranding()).toHaveLength(1);
+  });
+
+  it('lists every stored profile', () => {
+    const store = useInvoiceStore.getState();
+    store.setTenantBranding('tenant-a', { branding: {} });
+    useInvoiceStore.getState().setTenantBranding('tenant-b', { branding: {} });
+    expect(
+      useInvoiceStore
+        .getState()
+        .listTenantBranding()
+        .map((p) => p.tenantId)
+    ).toEqual(['tenant-a', 'tenant-b']);
+  });
+});
+
+describe('resolveBranding', () => {
+  it('falls back to the platform default when no tenant is given', () => {
+    const resolved = useInvoiceStore.getState().resolveBranding();
+    expect(resolved.source).toBe('fallback');
+    expect(resolved.templateId).toBe('tpl-1');
+    expect(resolved.numberingPrefix).toBe('INV');
+  });
+
+  it('reports the platform layer when a platform default exists', () => {
+    useInvoiceStore.getState().setInvoiceBranding({ primaryColor: '#000000' });
+    const resolved = useInvoiceStore.getState().resolveBranding();
+    expect(resolved.source).toBe('platform');
+    expect(resolved.branding.primaryColor).toBe('#000000');
+  });
+
+  it('layers tenant values over the platform defaults field by field', () => {
+    const store = useInvoiceStore.getState();
+    store.setInvoiceBranding({ primaryColor: '#000000', fontFamily: 'PlatformFont' });
+    useInvoiceStore
+      .getState()
+      .setTenantBranding('tenant-a', { branding: { primaryColor: '#ff0000' } });
+
+    const resolved = useInvoiceStore.getState().resolveBranding('tenant-a');
+    expect(resolved.source).toBe('tenant');
+    expect(resolved.branding.primaryColor).toBe('#ff0000');
+    // The tenant overrode only its colour, so the platform font shows through.
+    expect(resolved.branding.fontFamily).toBe('PlatformFont');
+  });
+
+  it('honours a tenant template and numbering prefix', () => {
+    useInvoiceStore.getState().setTenantBranding('tenant-a', {
+      branding: {},
+      templateId: 'tpl-3',
+      numberingPrefix: 'ACME',
+    });
+    const resolved = useInvoiceStore.getState().resolveBranding('tenant-a');
+    expect(resolved.templateId).toBe('tpl-3');
+    expect(resolved.numberingPrefix).toBe('ACME');
+  });
+
+  it('falls back when a tenant points at a template that no longer exists', () => {
+    useInvoiceStore.getState().setTenantBranding('tenant-a', { branding: {}, templateId: 'tpl-3' });
+    useInvoiceStore.getState().removeTemplate('tpl-3');
+    expect(useInvoiceStore.getState().resolveBranding('tenant-a').templateId).toBe('tpl-1');
+  });
+
+  it('falls back to the platform default for an unknown tenant', () => {
+    const resolved = useInvoiceStore.getState().resolveBranding('never-registered');
+    expect(resolved.source).toBe('fallback');
+  });
+});
+
+describe('template management', () => {
+  it('replaces a template registered under an existing id', () => {
+    const store = useInvoiceStore.getState();
+    store.addTemplate({ id: 'tpl-1', name: 'Renamed', layout: 'minimalist' });
+    const templates = useInvoiceStore.getState().templates;
+    expect(templates).toHaveLength(3);
+    expect(templates.find((t) => t.id === 'tpl-1')?.name).toBe('Renamed');
+  });
+
+  it('clears the default template pointer when that template is removed', () => {
+    const store = useInvoiceStore.getState();
+    store.setDefaultTemplate('tpl-2');
+    useInvoiceStore.getState().removeTemplate('tpl-2');
+    expect(useInvoiceStore.getState().config.defaultTemplateId).toBeUndefined();
+    expect(useInvoiceStore.getState().resolveBranding().templateId).toBe('tpl-1');
+  });
+});
+
+describe('applyBrandingToInvoice', () => {
+  it('stamps the resolved branding onto an existing invoice', () => {
+    useInvoiceStore.setState({ invoices: [makeInvoice()] });
+    useInvoiceStore.getState().setTenantBranding('tenant-a', {
+      displayName: 'Acme Inc.',
+      branding: { primaryColor: '#ff0000' },
+      templateId: 'tpl-2',
+    });
+
+    const updated = useInvoiceStore.getState().applyBrandingToInvoice('inv-1', 'tenant-a');
+    expect(updated?.tenantId).toBe('tenant-a');
+    expect(updated?.branding?.primaryColor).toBe('#ff0000');
+    expect(updated?.templateId).toBe('tpl-2');
+    expect(updated?.merchantName).toBe('Acme Inc.');
+    expect(useInvoiceStore.getState().invoices[0].merchantName).toBe('Acme Inc.');
+  });
+
+  it("reuses the invoice's own tenant when none is passed", () => {
+    useInvoiceStore.setState({ invoices: [makeInvoice({ tenantId: 'tenant-a' })] });
+    useInvoiceStore
+      .getState()
+      .setTenantBranding('tenant-a', { branding: { primaryColor: '#0000ff' } });
+
+    expect(useInvoiceStore.getState().applyBrandingToInvoice('inv-1')?.branding?.primaryColor).toBe(
+      '#0000ff'
+    );
+  });
+
+  it('returns null for an unknown invoice', () => {
+    expect(useInvoiceStore.getState().applyBrandingToInvoice('nope')).toBeNull();
+  });
+});
diff --git a/src/store/invoiceStore.ts b/src/store/invoiceStore.ts
index eccd9904..480c2f51 100644
--- a/src/store/invoiceStore.ts
+++ b/src/store/invoiceStore.ts
@@ -15,6 +15,8 @@ import {
   DigitalGoodsCategory,
   InvoiceBranding,
   InvoiceTemplate,
+  TenantBrandingProfile,
+  ResolvedInvoiceBranding,
   RemittanceStatus,
   TaxRateEntry,
   MidCycleTaxChange,
@@ -27,7 +29,7 @@ import { errorHandler, AppError } from '../services/errorHandler';
 import { presentLocalNotification } from '../services/notificationService';
 
 const STORAGE_KEY = 'subtrackr-invoices';
-const STORE_VERSION = 1;
+const STORE_VERSION = 2;
 
 type PersistedInvoiceSlice = Pick<
   InvoiceState,
@@ -39,6 +41,8 @@ type PersistedInvoiceSlice = Pick<
   | 'taxRemittanceLines'
   | 'taxRemittanceReports'
   | 'digitalGoodsClasses'
+  | 'brandingProfiles'
+  | 'templates'
 >;
 
 const toValidDate = (value: unknown, fallback = new Date()): Date => {
@@ -77,9 +81,61 @@ const normalizeInvoice = (raw: Partial<Invoice>): Invoice => {
     notes: raw.notes,
     branding: raw.branding,
     templateId: raw.templateId,
+    tenantId: raw.tenantId,
   };
 };
 
+const DEFAULT_TEMPLATES: InvoiceTemplate[] = [
+  { id: 'tpl-1', name: 'Standard', layout: 'standard' },
+  { id: 'tpl-2', name: 'Modern', layout: 'modern' },
+  { id: 'tpl-3', name: 'Minimalist', layout: 'minimalist' },
+];
+
+const HEX_COLOR = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+
+/** Only http(s) and data-image URLs may be embedded in a rendered invoice. */
+const isSafeLogoUrl = (url: string): boolean =>
+  /^https?:\/\//i.test(url) || /^data:image\//i.test(url);
+
+/**
+ * Reports every problem with a branding payload rather than throwing on the
+ * first, so the branding editor can highlight all offending fields at once.
+ */
+export const validateInvoiceBranding = (branding: InvoiceBranding): string[] => {
+  const errors: string[] = [];
+  const colorFields: [keyof InvoiceBranding, string][] = [
+    ['primaryColor', 'primaryColor'],
+    ['secondaryColor', 'secondaryColor'],
+    ['accentColor', 'accentColor'],
+    ['textColor', 'textColor'],
+  ];
+  for (const [field, label] of colorFields) {
+    const value = branding[field];
+    if (value !== undefined && !HEX_COLOR.test(String(value))) {
+      errors.push(`${label} must be a hex colour such as #1a73e8`);
+    }
+  }
+  if (branding.logoUrl !== undefined && !isSafeLogoUrl(branding.logoUrl)) {
+    errors.push('logoUrl must be an http(s) or data:image URL');
+  }
+  if (
+    branding.logoWidth !== undefined &&
+    (!Number.isFinite(branding.logoWidth) || branding.logoWidth <= 0)
+  ) {
+    errors.push('logoWidth must be a positive number');
+  }
+  if (
+    branding.supportEmail !== undefined &&
+    !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(branding.supportEmail)
+  ) {
+    errors.push('supportEmail must be a valid email address');
+  }
+  if (branding.websiteUrl !== undefined && !/^https?:\/\//i.test(branding.websiteUrl)) {
+    errors.push('websiteUrl must be an http(s) URL');
+  }
+  return errors;
+};
+
 const serializeForStorage = (state: PersistedInvoiceSlice): PersistedInvoiceSlice => ({
   invoices: state.invoices.map((invoice) => ({
     ...invoice,
@@ -98,6 +154,8 @@ const serializeForStorage = (state: PersistedInvoiceSlice): PersistedInvoiceSlic
   taxRemittanceLines: state.taxRemittanceLines,
   taxRemittanceReports: state.taxRemittanceReports,
   digitalGoodsClasses: state.digitalGoodsClasses,
+  brandingProfiles: state.brandingProfiles,
+  templates: state.templates,
 });
 
 const migratePersistedState = (persisted: unknown): PersistedInvoiceSlice => {
@@ -111,6 +169,8 @@ const migratePersistedState = (persisted: unknown): PersistedInvoiceSlice => {
       taxRemittanceLines: [],
       taxRemittanceReports: [],
       digitalGoodsClasses: {},
+      brandingProfiles: {},
+      templates: DEFAULT_TEMPLATES,
     };
   }
 
@@ -128,6 +188,13 @@ const migratePersistedState = (persisted: unknown): PersistedInvoiceSlice => {
     taxRemittanceLines: maybeState.taxRemittanceLines ?? [],
     taxRemittanceReports: maybeState.taxRemittanceReports ?? [],
     digitalGoodsClasses: maybeState.digitalGoodsClasses ?? {},
+    // v1 stores predate per-tenant branding; an empty registry falls back to
+    // the platform defaults, which is exactly the v1 behaviour.
+    brandingProfiles: maybeState.brandingProfiles ?? {},
+    templates:
+      Array.isArray(maybeState.templates) && maybeState.templates.length > 0
+        ? maybeState.templates
+        : DEFAULT_TEMPLATES,
   };
 };
 
@@ -150,10 +217,27 @@ interface InvoiceState {
   digitalGoodsClasses: Record<string, DigitalGoodsCategory>;
 
   templates: InvoiceTemplate[];
+  /** Per-tenant invoice presentation, keyed by tenant (merchant) id. */
+  brandingProfiles: Record<string, TenantBrandingProfile>;
 
   setInvoiceBranding: (branding: InvoiceBranding) => void;
   setDefaultTemplate: (templateId: string) => void;
   addTemplate: (template: InvoiceTemplate) => void;
+  removeTemplate: (templateId: string) => void;
+
+  setTenantBranding: (
+    tenantId: string,
+    profile: Omit<TenantBrandingProfile, 'tenantId' | 'updatedAt'>
+  ) => TenantBrandingProfile;
+  updateTenantBranding: (
+    tenantId: string,
+    patch: Partial<Omit<TenantBrandingProfile, 'tenantId'>>
+  ) => TenantBrandingProfile | null;
+  removeTenantBranding: (tenantId: string) => void;
+  getTenantBranding: (tenantId: string) => TenantBrandingProfile | undefined;
+  listTenantBranding: () => TenantBrandingProfile[];
+  resolveBranding: (tenantId?: string) => ResolvedInvoiceBranding;
+  applyBrandingToInvoice: (invoiceId: string, tenantId?: string) => Invoice | null;
 
   generateInvoiceFromSubscription: (
     data: InvoiceFormData,
@@ -242,10 +326,8 @@ export const useInvoiceStore = create<InvoiceState>()(
       taxRemittanceReports: [],
       digitalGoodsClasses: {},
 
-      templates: [
-        { id: 'tpl-1', name: 'Standard', layout: 'standard' },
-        { id: 'tpl-2', name: 'Modern', layout: 'modern' },
-      ],
+      templates: DEFAULT_TEMPLATES,
+      brandingProfiles: {},
 
       setInvoiceBranding: (branding) => {
         set((state) => ({
@@ -261,8 +343,132 @@ export const useInvoiceStore = create<InvoiceState>()(
 
       addTemplate: (template) => {
         set((state) => ({
-          templates: [...state.templates, template],
+          templates: state.templates.some((t) => t.id === template.id)
+            ? state.templates.map((t) => (t.id === template.id ? template : t))
+            : [...state.templates, template],
+        }));
+      },
+
+      removeTemplate: (templateId) => {
+        set((state) => ({
+          templates: state.templates.filter((t) => t.id !== templateId),
+          // Never leave the config pointing at a template that no longer exists.
+          config:
+            state.config.defaultTemplateId === templateId
+              ? { ...state.config, defaultTemplateId: undefined }
+              : state.config,
+        }));
+      },
+
+      setTenantBranding: (tenantId, profile) => {
+        const errors = validateInvoiceBranding(profile.branding);
+        if (errors.length > 0) {
+          throw new Error(`Invalid branding for tenant ${tenantId}: ${errors.join('; ')}`);
+        }
+        const stored: TenantBrandingProfile = {
+          ...profile,
+          tenantId,
+          updatedAt: new Date(),
+        };
+        set((state) => ({
+          brandingProfiles: { ...state.brandingProfiles, [tenantId]: stored },
+        }));
+        return stored;
+      },
+
+      updateTenantBranding: (tenantId, patch) => {
+        const existing = get().brandingProfiles[tenantId];
+        if (!existing) return null;
+
+        const branding = patch.branding
+          ? { ...existing.branding, ...patch.branding }
+          : existing.branding;
+        const errors = validateInvoiceBranding(branding);
+        if (errors.length > 0) {
+          throw new Error(`Invalid branding for tenant ${tenantId}: ${errors.join('; ')}`);
+        }
+
+        const merged: TenantBrandingProfile = {
+          ...existing,
+          ...patch,
+          branding,
+          tenantId,
+          updatedAt: new Date(),
+        };
+        set((state) => ({
+          brandingProfiles: { ...state.brandingProfiles, [tenantId]: merged },
+        }));
+        return merged;
+      },
+
+      removeTenantBranding: (tenantId) => {
+        set((state) => {
+          if (!state.brandingProfiles[tenantId]) return state;
+          const updated = { ...state.brandingProfiles };
+          delete updated[tenantId];
+          return { brandingProfiles: updated };
+        });
+      },
+
+      getTenantBranding: (tenantId) => get().brandingProfiles[tenantId],
+
+      listTenantBranding: () => Object.values(get().brandingProfiles),
+
+      resolveBranding: (tenantId) => {
+        const state = get();
+        const platformBranding = state.config.defaultBranding;
+        const platformTemplate =
+          state.config.defaultTemplateId ?? state.templates[0]?.id ?? DEFAULT_TEMPLATES[0].id;
+        const profile = tenantId ? state.brandingProfiles[tenantId] : undefined;
+
+        if (!profile) {
+          return {
+            branding: platformBranding ?? {},
+            templateId: platformTemplate,
+            numberingPrefix: state.config.numberingPrefix,
+            source: platformBranding ? 'platform' : 'fallback',
+          };
+        }
+
+        // Tenant values win field by field, so a tenant that only overrides its
+        // logo still inherits the platform palette.
+        const branding: InvoiceBranding = { ...(platformBranding ?? {}), ...profile.branding };
+
+        // A tenant pointing at a template that has since been deleted falls
+        // back rather than rendering nothing.
+        const templateId =
+          profile.templateId && state.templates.some((t) => t.id === profile.templateId)
+            ? profile.templateId
+            : platformTemplate;
+
+        return {
+          branding,
+          templateId,
+          displayName: profile.displayName,
+          numberingPrefix: profile.numberingPrefix ?? state.config.numberingPrefix,
+          source: 'tenant',
+        };
+      },
+
+      applyBrandingToInvoice: (invoiceId, tenantId) => {
+        const invoice = get().invoices.find((entry) => entry.id === invoiceId);
+        if (!invoice) return null;
+
+        const effectiveTenantId = tenantId ?? invoice.tenantId;
+        const resolved = get().resolveBranding(effectiveTenantId);
+        const updated: Invoice = {
+          ...invoice,
+          tenantId: effectiveTenantId,
+          branding: resolved.branding,
+          templateId: resolved.templateId,
+          merchantName: resolved.displayName ?? invoice.merchantName,
+          updatedAt: new Date(),
+        };
+
+        set((state) => ({
+          invoices: state.invoices.map((entry) => (entry.id === invoiceId ? updated : entry)),
         }));
+        return updated;
       },
 
       generateInvoiceFromSubscription: async (data, taxRateBps, exchangeRate) => {
@@ -287,8 +493,19 @@ export const useInvoiceStore = create<InvoiceState>()(
             invoice.taxJurisdiction = data.taxJurisdiction;
           }
 
-          invoice.branding = state.config.defaultBranding;
-          invoice.templateId = state.config.defaultTemplateId || state.templates[0]?.id;
+          const resolved = get().resolveBranding(data.tenantId);
+          invoice.tenantId = data.tenantId;
+          invoice.branding = resolved.branding;
+          invoice.templateId = resolved.templateId;
+          if (resolved.displayName) {
+            invoice.merchantName = resolved.displayName;
+          }
+          if (resolved.numberingPrefix !== state.config.numberingPrefix) {
+            invoice.invoiceNumber = invoice.invoiceNumber.replace(
+              state.config.numberingPrefix,
+              resolved.numberingPrefix
+            );
+          }
 
           set((current) => ({
             invoices: [...current.invoices, invoice],
@@ -667,6 +884,8 @@ export const useInvoiceStore = create<InvoiceState>()(
           taxRemittanceLines: state.taxRemittanceLines,
           taxRemittanceReports: state.taxRemittanceReports,
           digitalGoodsClasses: state.digitalGoodsClasses,
+          brandingProfiles: state.brandingProfiles,
+          templates: state.templates,
         }),
       migrate: (persistedState) => migratePersistedState(persistedState),
       merge: (persistedState, currentState) => ({
@@ -689,6 +908,8 @@ export const useInvoiceStore = create<InvoiceState>()(
             taxRemittanceLines: [],
             taxRemittanceReports: [],
             digitalGoodsClasses: {},
+            brandingProfiles: {},
+            templates: DEFAULT_TEMPLATES,
             isLoading: false,
           });
           return;
@@ -703,6 +924,9 @@ export const useInvoiceStore = create<InvoiceState>()(
           taxRemittanceLines: state?.taxRemittanceLines ?? [],
           taxRemittanceReports: state?.taxRemittanceReports ?? [],
           digitalGoodsClasses: state?.digitalGoodsClasses ?? {},
+          brandingProfiles: state?.brandingProfiles ?? {},
+          templates:
+            state?.templates && state.templates.length > 0 ? state.templates : DEFAULT_TEMPLATES,
           isLoading: false,
           error: null,
         });
diff --git a/src/types/invoice.ts b/src/types/invoice.ts
index 1d95637e..efe8383d 100644
--- a/src/types/invoice.ts
+++ b/src/types/invoice.ts
@@ -251,6 +251,17 @@ export interface InvoiceBranding {
   logoUrl?: string;
   primaryColor?: string;
   fontFamily?: string;
+  /** Used for secondary surfaces (table headers, rules) in rendered invoices. */
+  secondaryColor?: string;
+  accentColor?: string;
+  /** Body text colour; falls back to a neutral when unset. */
+  textColor?: string;
+  /** Displayed under the totals block — payment terms, legal footer, etc. */
+  footerText?: string;
+  supportEmail?: string;
+  websiteUrl?: string;
+  /** Rendered logo width in points. Clamped when the invoice is rendered. */
+  logoWidth?: number;
 }
 
 export interface InvoiceTemplate {
@@ -259,6 +270,23 @@ export interface InvoiceTemplate {
   layout: 'standard' | 'modern' | 'minimalist';
 }
 
+/**
+ * A tenant's invoice presentation. Tenants are merchants on the platform, so
+ * one deployment renders invoices under many brands; anything left unset here
+ * falls back to the platform defaults in `InvoiceConfig`.
+ */
+export interface TenantBrandingProfile {
+  tenantId: string;
+  /** Legal entity name printed as the issuer. Defaults to the merchant name. */
+  displayName?: string;
+  branding: InvoiceBranding;
+  /** Overrides `InvoiceConfig.defaultTemplateId` for this tenant. */
+  templateId?: string;
+  /** Overrides the platform invoice number prefix, e.g. `ACME`. */
+  numberingPrefix?: string;
+  updatedAt?: Date;
+}
+
 export interface Invoice {
   id: string;
   invoiceNumber: string;
@@ -286,6 +314,7 @@ export interface Invoice {
   reverseCharge?: boolean;
   branding?: InvoiceBranding;
   templateId?: string;
+  tenantId?: string;
 }
 
 export interface InvoiceConfig {
@@ -301,6 +330,16 @@ export interface InvoiceConfig {
   defaultTemplateId?: string;
 }
 
+/** Branding actually applied to an invoice, with the source of each decision. */
+export interface ResolvedInvoiceBranding {
+  branding: InvoiceBranding;
+  templateId: string;
+  displayName?: string;
+  numberingPrefix: string;
+  /** Which layer supplied the branding — useful for the branding preview UI. */
+  source: 'tenant' | 'platform' | 'fallback';
+}
+
 export interface InvoiceTotals {
   subtotal: number;
   tax: number;
@@ -315,6 +354,8 @@ export interface InvoiceFormData {
   recipientEmail?: string;
   notes?: string;
   taxJurisdiction?: TaxJurisdiction;
+  /** Merchant whose branding profile should be applied to this invoice. */
+  tenantId?: string;
 }
 
 export interface InvoiceStateSnapshot {