Fixing the Self-Employed Onboarding Gap

Release v1.0.290 | Core Functionality | High Severity

MTD ITSA isn't just for landlords. Sole traders, freelancers, and anyone with self-employment income above the threshold is equally subject to the mandate — yet until this release, our onboarding wizard treated every new user as a landlord. This post explains what was wrong, why it mattered, and what we've fixed.

---

What Was Broken

When a new organisation was created on the platform, the onboarding wizard in src/app/onboarding/page.tsx had one path: the landlord path. It presented steps like connect your letting agent and import your properties — steps that are completely irrelevant to a freelancer or sole trader who has never owned a rental property.

The database schema was already correct. The organisations table has a taxpayerType column that accepts landlord, self_employed, or both. The problem was that nothing in the wizard ever set that column, and nothing ever read it to decide which steps to show. The MTD checklist router (mtdStatus) dutifully returned landlord-specific steps for every organisation, because it had no other instructions.

The practical result: a self-employed user who signed up would see a checklist of landlord tasks, skip past them in confusion, and have to find the Self-Employment dashboard entirely on their own — if they found it at all.

---

Why This Is a High-Severity Issue

Self-employed individuals — sole traders, contractors, consultants, gig workers — represent a substantial share of the MTD ITSA mandate. HMRC's own estimates place the self-employed cohort as a significant proportion of the 4+ million taxpayers who will be required to use MTD ITSA. Presenting these users with a broken, irrelevant onboarding journey is not a minor UX issue. It is a mission-critical failure that prevents a core user segment from successfully setting up their account.

Beyond the user experience impact, the missing taxpayerType write-back meant that downstream logic — dashboard rendering, obligation period configuration, submission routing — could not correctly distinguish SE users from landlords even after onboarding completed.

---

What We Fixed in v1.0.290

1. Taxpayer type is now captured at the start of onboarding.

The wizard now includes a clear, early step asking users to identify themselves as a landlord, self-employed, or both. The answer is written to organisations.taxpayerType immediately, making it available to every subsequent step and to all downstream systems.

2. The wizard branches on taxpayer type.

Once taxpayerType is set, the wizard routes users down the appropriate path:

• Landlord — existing flow, unchanged.
• Self-Employed — a new path covering SE income source connection, business transaction import, expense categorisation, and quarterly obligation setup.
• Both — a combined path that covers both sets of obligations without unnecessary repetition.

3. The mtdStatus router is now taxpayer-type aware.

The checklist step definitions returned by the mtdStatus router are now filtered and ordered based on taxpayerType. An SE user will never see connect_letting_agent or import_properties in their checklist. A landlord will never see SE-specific steps.

---

What This Means for Existing Users

If you signed up before v1.0.290 as a self-employed taxpayer, your taxpayerType may not have been set correctly. On your next login, the platform will prompt you to confirm your taxpayer type so it can configure your account properly. This is a one-time step and takes under a minute.

---

Looking Ahead

This release brings self-employed taxpayers to full parity with landlords at the onboarding stage. Future releases will continue to build out SE-specific functionality, including richer expense category mapping for common self-employment scenarios (construction, professional services, creative industries) and multi-source SE income support for taxpayers with more than one self-employment business.

If you are a sole trader or freelancer preparing for MTD ITSA, v1.0.290 is the release that makes the platform work correctly for you from day one.