Multi-Tenant Shipping: Architecture for SaaS Platforms

Building a shipping platform that effectively serves multiple merchants from a single codebase requires meticulous planning and architecture. Getting the details right is essential to avoid potential pitfalls such as data leakage between tenants, mixed carrier credentials, or one large tenant monopolizing shared resources, which can lead to rate limits being hit.

Tenant Isolation: The Three Layers

1. Database Isolation

Ensuring that each tenant's data remains isolated is crucial for maintaining privacy and security. The simplest way to achieve this is by including a WHERE organizationId = ? clause in every database query. This approach ensures that only the data pertinent to a specific tenant is accessed. To automate this process, you can use tools like Prisma middleware or a custom query wrapper to inject the tenant filter seamlessly.

Additionally, implementing Row-Level Security (RLS) in databases like PostgreSQL provides a secondary layer of protection. Even if there is a bug in your application code, RLS ensures that the database itself will not return data from another tenant, thus safeguarding against potential data breaches.

2. Carrier Credential Isolation

Each tenant should have their own distinct carrier API keys, and these should never be shared across tenants. This isolation prevents one tenant's shipping volume from affecting another's rate limits or account standing. For example, if a single tenant has a high shipping volume, sharing carrier accounts could lead to rate limit issues for all tenants.

Carrier credentials should be securely stored and managed per organization, ensuring that each tenant's shipping operations remain independent and unaffected by others. This not only maintains operational efficiency but also protects each tenant's sensitive information.

3. Rate Limit Isolation

Rate limits are a common challenge when dealing with APIs, particularly in a multi-tenant environment. Applying per-tenant rate limits to your own API—separate from carrier rate limits—ensures that one tenant's activities, such as a bulk import, don't slow down others' real-time rate quotes.

Using technologies like Redis, you can implement tenant-prefixed keys (e.g., ratelimit:{orgId}:{endpoint}) to manage these rate limits effectively. This approach allows each tenant to operate independently without impacting the performance or availability of services for other tenants.

Carrier Account Models

There are three common models for managing carrier accounts in a multi-tenant environment:

Tenant's Own Accounts: This model offers tenants the best rates and full control over their shipping processes. However, it requires a more complex onboarding process as each tenant must configure and manage their own carrier accounts.

Platform Master Account: This approach simplifies the onboarding process, allowing tenants to start shipping immediately without setting up their own accounts. However, it places liability on the platform, as the platform assumes responsibility for all shipping activities.

Hybrid Model: This offers a balance between control and ease of use, providing flexibility for both the platform and the tenants. While it requires more code to maintain, it allows larger tenants to bring their own carrier accounts as they scale.

Most shipping SaaS platforms start with a master account setup and transition to allowing tenants to use their own accounts as they grow and require more customized solutions.

Webhook Routing

When carriers send webhooks, it's essential to route them to the correct tenant. This can be achieved by including the organizationId in the carrier API metadata when creating labels. When the webhook is received, this metadata can be extracted to route the notification to the appropriate tenant's processing queue. This ensures that each tenant receives timely and accurate updates on their shipments.

Data Migration Between Tenants

Moving data between tenants is sometimes necessary, such as when a merchant switches plans or is acquired by another company. Designing your schema to allow for easy data migration is key. By referencing the organization in all related records (orders, shipments, labels) through foreign keys, you can streamline the migration process. Changing the organizationId on all related records should be the only operation needed, simplifying what could otherwise be a complex and error-prone process.

Billing Per Tenant

Accurate billing is critical in a multi-tenant environment. Tracking shipping spend per tenant is necessary for generating precise invoices. This involves logging every label purchase with details such as the organizationId, carrier, service, and cost. Aggregating this data monthly allows for efficient invoicing. Maintaining a separate billing ledger from the shipping transaction log helps ensure that billing operations are organized and error-free.

Explore Atoship's multi-tenant architecture →