SaaS onboarding is a workflow, not a single database insert. It may create a tenant, its first owner, default configuration, billing records, and dedicated resources. Treat the process as an idempotent state machine so a retry resumes safely.
Last updated: September 8, 2026.
CREATE TABLE tenant_onboarding (
request_key VARCHAR(100) PRIMARY KEY,
tenant_id BIGINT NULL,
step VARCHAR(40) NOT NULL,
status VARCHAR(20) NOT NULL,
last_error TEXT NULL,
updated_at TIMESTAMP NOT NULL
);A client-generated or server-issued request_key identifies one signup attempt. If the browser retries after a timeout, the server returns the existing workflow instead of creating another tenant.
Use explicit steps
- Validate the organization, owner, selected plan, and required agreements.
- Create the tenant in a pending state and assign its first owner role.
- Create the billing customer and save only provider identifiers—not card data.
- Apply defaults and provision any tenant-specific database, storage, or domain.
- Run a health check, activate the tenant, and send the welcome message.
Commit small durable steps rather than holding one database transaction open while calling external services. Each step records success before the next begins. A failed billing or provisioning call leaves the tenant pending and gives an administrator enough information to retry it.
Keep onboarding asynchronous
If provisioning can take more than a few seconds, return a workflow ID and show progress. Send the work to a queue using the same safeguards described for tenant-aware background jobs. Workers must be idempotent because queue messages can be delivered more than once.
Test partial failure
Test failures after every step: duplicate submission, identity-provider timeout, billing rejection, database provisioning failure, and welcome-email failure. Confirm that retrying does not create duplicate owners, subscriptions, or infrastructure. Also define cleanup for abandoned pending tenants.
AWS recommends automating all elements of tenant creation even when onboarding is initiated internally rather than through self-service. Its SaaS operations guidance shows tenant, user, billing, and provisioning services as parts of one orchestrated process.
