Skip to main content
Xalicon

FinTech

Multi-tenant billing and entitlements for a growing SaaS platform

Retrofitting organisations, entitlements and usage-based billing into a product originally built for individual users.

  • Next.js
  • TypeScript
  • Node.js
  • PostgreSQL
  • Stripe
  • Terraform
  • AWS
  • ClickHouse
Start a similar projectAll case studies

Sample case study — illustrative, not a delivered client engagement

Meridian Analytics is an invented company used to demonstrate our case-study format and our approach to this kind of work. The technical detail reflects how we would genuinely deliver it; the client name is fictional and the figures under Results are design targets rather than measured outcomes.

Client

Meridian Analytics

Illustrative B2B SaaS company moving upmarket into enterprise deals

Industry
FinTech
Year
2025

The business challenge

The product had grown from a single-user tool into something teams were buying, but the data model still assumed one user equalled one account. Customers were sharing credentials, billing was handled manually through invoices, and every enterprise conversation surfaced the same blockers: no single sign-on, no audit trail, no way to manage seats. Engineering estimated a rewrite; leadership needed an incremental path that did not pause the roadmap.

Objectives

  • Introduce organisations and roles without disrupting existing accounts
  • Move from manual invoicing to self-service subscription billing
  • Support usage-based pricing alongside seat-based plans
  • Deliver the enterprise features blocking larger deals
  • Make per-tenant cost and usage visible to the business

Discovery and strategy

What we did before writing code

  • Audited every query and permission check that assumed a single-user account
  • Modelled the intended pricing with finance, including proration and overage edge cases
  • Reviewed the last twelve months of enterprise deals to identify recurring blockers
  • Measured infrastructure cost per active account to establish a margin baseline
  • Agreed an incremental migration sequence with a rollback point at each stage

Solution

What we built

  • Organisation layer

    Organisations, memberships, roles and invitations introduced behind a compatibility layer, with every existing account migrated into a single-member organisation transparently.

  • Entitlement service

    Plan entitlements modelled in the platform itself rather than read from the payment provider, so access decisions never depend on a webhook having arrived.

  • Usage metering

    An append-only usage event stream aggregated on a schedule, surfaced to customers in-product and reconciled before every invoice.

  • Subscription lifecycle

    Self-service checkout, trials, upgrades with proration, downgrades, cancellation and dunning, reconciled continuously against the payment provider.

  • Enterprise readiness

    SAML single sign-on, SCIM provisioning, audit logging and data export, delivered as a package to unblock procurement.

  • Cost attribution

    Infrastructure and usage costs attributed per tenant, giving finance real unit economics for the first time.

Architecture

How it fits together

Tenancy and billing architecture

A shared-schema tenancy model with row-level enforcement, and a billing domain owned by the platform rather than delegated to the payment provider.

  1. ApplicationTenant-scoped requests with organisation context resolved at the edge
  2. IdentitySAML SSO, SCIM provisioning and role management
  3. EntitlementsAuthoritative plan and feature access owned by the platform
  4. MeteringAppend-only usage events with scheduled aggregation
  5. Billing integrationStripe Billing with continuous reconciliation
  6. AnalyticsClickHouse for usage, cost and margin reporting

Design approach

Decisions in the interface

  • Designed an organisation switcher that stayed unobtrusive for the majority of customers with a single organisation
  • Made plan limits and current usage visible in-product before they are hit, rather than at the point of failure
  • Built an admin console for support staff that avoids the need for direct database access
  • Wrote upgrade and downgrade flows to state the financial consequence plainly before confirmation

Development process

How the work ran

  • Migration executed in five reversible stages, each independently deployable
  • Automated tests asserting tenant isolation on every data access path, run on every pull request
  • Billing logic verified against a recorded set of real provider webhook sequences, including out-of-order delivery
  • Shadow-mode reconciliation run for six weeks before invoicing moved to the new system
  • Infrastructure defined in Terraform with per-tenant cost tagging from the outset

Technology stack

What it runs on

  • Next.js
  • TypeScript
  • Node.js
  • PostgreSQL
  • Stripe
  • Terraform
  • AWS
  • ClickHouse

Challenges resolved

What went wrong, and what we did

Every project has these. A case study that omits them is a brochure.

  • Webhook delivery cannot be trusted

    Provider webhooks arrived out of order and occasionally not at all. Entitlements were made authoritative within the platform, with a scheduled reconciliation job that repairs drift and reports discrepancies rather than failing silently.

  • Migrating live accounts without disruption

    Existing users could not be asked to re-authenticate or reconfigure. A compatibility layer resolved legacy account identifiers to organisation context, allowing migration to proceed without any customer-visible change.

  • Usage aggregation at volume

    Aggregating raw events on demand was too slow at scale. Incremental pre-aggregation in ClickHouse with a reconciliation pass reduced in-product usage queries to well under a second.

Results

Objectives and design targets

Because this is a sample case study, these are the objectives and design targets agreed in scope — not measured business results.

  • Manual invoicing

    Target: fully self-service

    Illustrative objective from the engagement scope

  • Enterprise blockers

    SSO, SCIM and audit logging delivered

    Scope items defined during discovery

  • Unit economics

    Per-tenant cost visibility

    Design target, not a measured business result

Client feedback

In their words

Placeholder quote

This quote is sample content shown to demonstrate the layout. It is not attributable to a real person or organisation and will be replaced only with a genuine, approved testimonial.

  • “Sample content for design demonstration. This quote is illustrative and is not attributable to a real client.”
    Sample Client ContactVP Engineering (illustrative)

Related services

The practices behind this work

More work

Other case studies

All case studies

Similar situation?

Start a project like this one

Tell us where you are. We will tell you how we would approach it and what we would want to understand first.

Start Your ProjectTalk to us first

Prefer email? contact@xalicon.co