From Idea to First Paying Customer: A Delivery Roadmap for a Multi-Tenant Laravel SaaS: 05 of 08

A working-backwards plan for taking a multi-tenant Laravel SaaS from idea to first paying customer: success criteria, build order, plan limits, idempotent billing webhooks, tenant-aware logs and safe deploys.

From Idea to First Paying Customer: A Delivery Roadmap for a Multi-Tenant Laravel SaaS: 05 of 08
Photo by Alvaro Reyes / Unsplash

Imagine a team that starts a multi-tenant SaaS the way most teams do. Week one is login and registration. Weeks two to six are settings screens, an admin dashboard and a design system. Nobody has yet used the product to do the one job it exists for, and the data model has no idea that companies are supposed to be separated from each other.

The code in the previous articles (tenant isolation, Actions, Data objects, Events) is only half of the project. The other half is the order in which you build it and the evidence you collect before you charge anyone. This article is that plan, written backwards from the day a stranger pays.

Start From the Day a Stranger Pays

Before a plan, an outcome. For a first release I would write it as one paragraph: a person signs up, creates a company, invites a colleague, does the core job, reaches the limit of the free plan, and pays. Every task that doesn't serve that sentence waits.

Then turn it into success criteria you can check. A first set might read:

  • A new company can complete the core job without help from you.
  • No test, script or manual check can show one company another company's data.
  • A plan limit is enforced in one place and the app explains it when it's hit.
  • A payment, a cancellation and a failed charge each change what the company can do.
  • You can answer "what happened to company X yesterday?" from your logs.

Write the constraints and assumptions next to them: team size, budget, the one payment provider you'll use, the roles you think you need. The assumptions are the useful part. Each one is something you will find out is wrong, and it is cheaper to find out while it is still a line in a document.

Build the Walls Before the Rooms

The order matters, and tenancy goes first. Adding a company column to thirty tables after launch is one of the most expensive migrations a SaaS can face, and a missed table is a data leak. A workable build order:

  1. Companies, membership and roles, with the tenant context and the fail-closed scope, and the leak tests that go with them.
  2. One end-to-end slice of the core job, built with the Action, Data object and controller conventions you will keep.
  3. The background pieces that slice needs (events, listeners and jobs), each running inside a tenant context.
  4. Plans and limits.
  5. Billing.
  6. Everything else, ordered by what the first customers ask for.

The reasoning is simple. Walls are hard to retrofit and rooms are easy to add. Billing needs plans, and plans need something worth limiting.

One Slice, All the Way Down

The second step deserves its own section, because it does the most to reduce risk. A vertical slice goes from the migration to a screen and a test: the table with its company_id, the model with its trait, the Data object, the Action, the thin controller, a view, a test that tries to leak. Then deploy it before you start the second feature.

That last part feels premature, and it isn't. A slice in a real environment surfaces the problems that don't live in the code: the queue worker that isn't running, the scheduler that isn't scheduled, the mailer with no credentials, the storage disk with the wrong permissions. You want to meet those with one feature in play, not twelve.

The cost is that the first slice is slow. You are building the conventions and the pipeline at once. Later slices are fast because the first one paid for the pattern.

Plans, Limits and Billing

Limits tend to leak into the code as scattered if ($company->plan === 'free') checks. Put them behind one class that the Actions call:

final class PlanLimits
{
    public function assertCanAddMember(Company $company): void
    {
        $limit = $company->plan->maxMembers();

        if ($company->members()->count() >= $limit) {
            throw PlanLimitReached::for('members', $limit);
        }
    }
}

The class assumes plan is an enum cast with a maxMembers() method. The point is the single door. When pricing changes, one file changes, and the exception gives every caller a consistent way to explain the limit.

Billing is where mistakes cost money. A few rules help, whichever provider you pick:

  • Treat the provider as the source of truth for subscription state, and keep a local copy that the app reads. Never call the provider on each request to decide what a company can do.
  • Verify the signature on every webhook before reading the body. How depends on the provider.
  • Store every event with the provider's event id before doing anything else, and respond quickly. Do the real work in a queue.
  • Assume events arrive twice and out of order.
public function __invoke(Request $request): Response
{
    abort_unless($this->signature->isValid($request), 401);

    $payload = $request->json()->all();

    $event = BillingEvent::firstOrCreate(
        ['provider_event_id' => $payload['id']],
        ['type' => $payload['type'], 'payload' => $payload, 'received_at' => now()],
    );

    if ($event->wasRecentlyCreated) {
        ProcessBillingEvent::dispatch($event->id);
    }

    return response()->noContent();
}

signature is a provider-specific verifier you write once. Back the provider_event_id column with a unique index, because firstOrCreate on its own is not atomic. If two deliveries race, one fails on the index and the provider's retry finds the row already stored. For out-of-order events, have the processing job compare the event's timestamp with the last one applied to that subscription and skip anything older.

Testing the Parts That Cost Money

You can't test everything, so aim at what is expensive when it breaks:

  • Isolation. The leak tests from the first article, plus a guard that every table with a company_id uses the trait.
  • Limits. Under the limit, exactly at it, and over it.
  • Webhooks. The same event delivered twice produces one effect, and an old event doesn't overwrite a newer state.
  • The golden path. One browser-level smoke test from sign-up to the core job.

Most of the rest can live as Action tests, which are fast, with a thin layer of HTTP tests for authorization and validation. That is the shape the previous articles set up on purpose.

Deploying Without Waking Anyone Up

During a deploy, old and new code run side by side for a moment. Migrations have to survive that. The usual discipline is to expand first (add a nullable column, deploy code that writes both), then backfill, then switch reads, then tighten the constraint in a later release. Backfills on tenant data are best done as one chunked job per company, for the same reasons as the nightly job in the first article.

Two habits prevent most surprises. Restart queue workers on every deploy, since queue workers keep the booted application in memory and won't notice new code on their own (php artisan queue:restart does it). And keep the previous release available, so rollback is a switch and not a rebuild. That only works if the migrations are backward compatible, which is why the expand step comes first.

Seeing Per Tenant

The last criterion on the list was answering "what happened to company X yesterday?". Laravel's Context makes this a one-liner. Add it where the tenant is resolved:

Context::add('company_id', $company->id);

Per the docs, context is appended to the log entries written during the request and is also captured when a job is dispatched and restored while the job runs. Every log line, from the web and from the queue, now carries the company. This does not replace the explicit tenant context for queries. It only makes the logs searchable. Send the same id to your error tracker, and a support question becomes a filter instead of an investigation.

Conclusion

The team in the opening spent six weeks on rooms with no walls and no customer. The plan here reverses it: define the day someone pays, build the walls, ship one slice end to end, then add limits and billing in the order that money depends on them.

What to leave out is as much a part of the plan. Single sign-on, usage-based pricing and per-company databases all have a point where they become worth building. That point is a customer asking for it, not a hunch. Until then, you can write the first paragraph of this article for your own product and check which of its sentences you can already prove.