Nest tenants in a parent–child tree. Preferences, templates, vendors, branding, and properties flow from parent to child — set them once at the top and override only where you need to.
Sub-tenants let you nest tenants in a parent–child tree, up to 5 levels deep. A child automatically inherits its parent’s preferences, templates, vendors, branding, and properties — you only override what should differ at that level. Use it when you’d otherwise be copying the same setup across many tenants.
Build hierarchical admin preferences. Take a project management tool with Company → Project → Cycle. An admin turns email off at the Company and no user gets email in any Project or Cycle; turn it back on for one Cycle and only that Cycle sends email.
Users can set different preferences along the tenant tree. A user picks “don’t email me” at the Company and it holds for every Project and Cycle; turn email on for one Project and they get email for that Project and its Cycles, still opted out everywhere else.
Globally turn off a channel or category for a tenant. Turn off email at the company level to keep costs down, block SMS at a customer’s tenant when their plan doesn’t include it, or turn off a specific notification category at the project level so it stays off for every tenant below.
Inherit templates, vendors, and branding — override where you need to. A white-label agency can let each client brand have its own vendors (Twilio, SendGrid, FCM) and templates. A notification SaaS can give each customer a default template that their sites, projects, or downstream customers tweak.
Users can have a different profile per tenant. The same person can be a team member on one Project and the project manager on another, each with the role, channels, and properties that fit that tenant. If sub-tenants represent different apps of the same customer, each app tenant stores that user’s push token and channel identity for that app, while their name, email, and other shared properties come from the tenant above.
Each tenant can have a single parent (parent_id). A tenant with no parent is a root.
Level
Depth in the tree. Root = level 0. Maximum level = 4 (5 levels total).
Ancestors
The chain of parent tenants from the root down to a given tenant’s immediate parent. Does not include the tenant itself.
Inheritance
A child uses its parent’s value for a setting until it explicitly sets its own.
Live cascade
Inheritance is resolved at trigger/read time — editing a parent immediately affects descendants that haven’t overridden the same value. There is no copy-on-create snapshot.
Locked cascade
A setting where an ancestor’s value is unioned into every descendant and cannot be removed lower down. A descendant’s own value adds to the effective set; sending an empty value is accepted but the ancestor’s contribution still applies. Used by tenant-level and category-level blocked_channels, and category-level enabled_for_tenant: false.
Effective value
The value actually applied at send time after walking the chain.
Shallow merge
Merging happens one key at a time. Overriding one key never blocks other keys from inheriting. Nested structures are not deep-merged.
Create a sub-tenant by passing parent_id in the tenant upsert API — the tenant becomes a child of that parent. Skip parent_id (or send null) to create a root tenant.
At trigger time, SuprSend walks the ancestor chain to figure out which value applies. Almost everything resolves bottom up — the closest tenant to where the notification fired wins. The one exception is channel and category blocks set at the tenant level, which cascade the other way and can’t be undone.
For each notification category, a tenant can either set default preferences that descendants override key by key, or hard-block the category — or specific channels within it — so no descendant can re-enable them. Update a category via the Update Tenant Category Preference endpoint:
Each key inherits independently — send only the ones you want to change:
Setting
Inheritance behavior
preference (with mandatory_channels and opt_in_channels)
The category default (opt_in, opt_out, or cant_unsubscribe). Overriding on a child replaces the whole default preference object for that category. Later changes to the parent’s preference stop propagating to that child.
blocked_channels (per category)
Locked cascade. A child’s effective list is the union of every ancestor’s blocked channels plus its own. Descendants can add more channels but never remove an ancestor’s.
enabled_for_tenant
Locked cascade. Once a parent disables a category (enabled_for_tenant: false), no descendant can re-enable it.
visible_to_subscriber
Inherits until the child sets its own. Once overridden, later parent changes stop propagating to that child.
digest_schedule
Inherits independently — overriding preference doesn’t detach it. Keeps inheriting from the closest ancestor that set it until the child sets its own.
conditions
Inherits independently, same rule as digest_schedule.
Here’s an example flow
Category "Marketing" (workspace default): preference: opt_in, blocked_channels: nullCompany (Level 0): preference: "opt_out" blocked_channels: ["sms"]Project (Level 1): visible_to_subscriber: false blocked_channels: ["email"]Effective at Cycle (Level 2):{ "preference": "opt_out", // inherited from Company (override of workspace default) "blocked_channels": ["sms","email"], // union: sms from Company + email from Project (locked cascade) "visible_to_subscriber": false // inherited from Project}// Cycle sets blocked_channels = [] → accepted, but effective stays ["sms"] (sms is locked from Company).// Cycle sets blocked_channels = ["whatsapp"] → accepted; effective becomes ["sms", "whatsapp"] (union with Company).
Set blocked_channels on the tenant itself (not scoped to any category) to globally turn a channel off for every user of that tenant, across every category — including root categories and ones marked cant_unsubscribe. Update it via the same Create / Update Tenants endpoint:
This is a locked cascade — a channel blocked at any ancestor stays blocked for every tenant below. Descendants can add more blocks but never remove an ancestor’s.
Company (Level 0): blocked_channels: ["sms"]Project (Level 1): blocked_channels: ["inbox"]Effective at Cycle (Level 2): blocked_channels: ["sms", "inbox"] // union of Company + Project// Cycle sets blocked_channels = [] → accepted, but effective stays ["sms", "inbox"].// Cycle sets blocked_channels = ["whatsapp"] → accepted; effective becomes ["sms", "inbox", "whatsapp"].
A user can set their own preferences on any tenant they belong to. Every user preference — category or channel — is always saved against a tenant; there is no workspace-wide user preference. At trigger time, walk up from where the notification fired; the first value the user has explicitly set wins. Update via the Update User Category Preference or Update User Channel Preference endpoint — the tenant_id query param scopes each write to a specific tenant and is required:
User Preference supports 2 granularities — category preferences (opt in/out per notification category, and per channel within a category) and channel preferences (restrict or allow a channel across every category the user is subscribed to).
Category preferences fall back to the tenant’s resolved default — if the user hasn’t set one anywhere in the chain, the tenant’s default for that category applies.
Channel preferences have no tenant default — set is_restricted: true on a channel to restrict, false to allow. If the user has never set it anywhere in the chain, the channel is treated as unrestricted. Mandatory channels on cant_unsubscribe categories still fire when restricted.
Channel preferences apply as a group — once a child sets its own channel_preferences, it replaces the parent’s list entirely; the parent’s restrictions on other channels no longer apply at that child.
Within a category, each key inherits independently — changing preference doesn’t detach digest_schedule or condition properties; each keeps inheriting from the closest ancestor until the user sets their own.
cant_unsubscribe at the triggered tenant beats a user’s opt-out — when the tenant’s resolved preference for a category is cant_unsubscribe at the triggered tenant, the notification still sends on that tenant’s effective mandatory_channels even if the user opted out anywhere in the ancestor chain. Only the triggered tenant’s mandatory channels apply — ancestors’ mandatory channel lists don’t stack.
Here’s an example flow:
Setup — Category "Marketing": Tenant defaults: Company: opt_out Project: cant_unsubscribe, mandatory_channels: ["email"] Alice's category preferences: Company: opt_out // "don't send Marketing to me from Company" Alice's channel preferences: Company: [{ slack: is_restricted }] Project: [{ email: is_restricted }]Trigger at Cycle (under Project) for Alice: Category resolves to cant_unsubscribe, mandatory: ["email"] // Project's default wins at Cycle Channel preferences resolve [{ email: is_restricted }] // Project's list wins; Company's slack is NOT merged in → Notification sends on email // mandatory channel at triggered tenant beats // Alice's opt-out AND her email restrictionTrigger at Cycle under a different Project (which inherits Company's opt_out): Category resolves to opt_out // no override in that branch → Company default → Notification does NOT send // walk-up finds Alice's opt_out at Company; no mandatory override
For each channel (email, SMS, push, WhatsApp, …), the closest tenant in the chain that configured a vendor wins. Vendors cascade through the full tenant tree today.
Per channel, per vendor — overriding the SMS vendor on a child still lets it inherit the parent’s email vendor.
Default tenant vendor as final fallback — if no tenant in the chain configures a vendor for a channel, the default tenant vendor for that channel applies.
The resolved vendor for a tenant + channel is cached for up to 5 minutes. Adding a new vendor or re-parenting a tenant mid-flight won’t interrupt notifications already in progress — the new vendor picks up on the next resolution after the cache expires.
For a workflow triggered at any tenant, SuprSend will walk the ancestor chain and pick the closest tenant that has a matching template variant — the same rule as vendors.
Per channel — a child that overrides only the email template keeps inheriting the parent’s SMS template.
Default tenant fallback — if no tenant in the chain has a variant for a channel, the default tenant’s template applies.
Locale fallback within each tenant — at every tenant along the chain, SuprSend will try the recipient’s locale from most specific to least specific (e.g. es-MX → es → template default like en) before moving to the next tenant.
Tenant proximity beats locale specificity — a closer tenant’s en variant wins over a farther tenant’s exact-locale variant. The selector picks the closest tenant that has any matching variant for the channel, then applies locale fallback within it.
Today, a workflow triggered at any tenant uses that tenant’s template variant if one exists on that exact tenant; otherwise it falls back to the default tenant’s variant. It does not yet walk the ancestor chain.
A user’s effective profile at trigger time will be their global profile merged with each subscribed tenant’s per-tenant profile, layered from root down. The lowest tenant in the chain wins on shared fields. Users won’t need a subscription at every level — skipped levels contribute nothing.
Today, a user’s effective profile at trigger time is their global profile merged with the per-tenant profile at the triggered tenant only — profiles on ancestor tenants do not layer in.
📘 User-Tenant Mapping → | Upsert User Tenant Profile →Trigger a workflow at sprint-42 and SuprSend takes logo and primary_color from acme, support_email from project-1, and the milestone property from sprint-42 itself. SMS stays blocked on every send because acme locks it at the root — no descendant can turn it back on.
Go to Tenants in the side nav and open the tenant you want to add a sub-tenant under.
Switch to the Sub-tenants tab and click Add Sub-tenant.
Sub-tenants tab — empty state
In the modal, enter a Tenant ID (unique across the workspace, ≤ 64 chars, characters [a-z0-9_.-]) and a Name. The parent is prefilled from the tenant you opened; if that tenant already has sub-tenants of its own, you can pick any tenant in its subtree as the parent instead. Click on Create Tenant.
Add Sub-tenant modal
The new sub-tenant starts inheriting branding, properties, vendors, and preferences from the parent immediately; Click on it to override the properties or preference for this sub-tenant.
Sub-tenants tab on the tenant details page
Once at least one sub-tenant exists in your workspace, the Add Tenant action on the Tenants listing page also exposes a Parent tenant picker — so you can create a new tenant anywhere in the hierarchy without opening its parent first.
Change the parent_id on an existing tenant to move it (and its entire subtree) somewhere else in the tree, or delink it from its parent so it becomes a root again. On the API it’s a single field — set parent_id to a new tenant to re-parent, or send null (or an empty string) to delink. On the dashboard the two flows are surfaced as separate actions.
Dashboard
API
On the Sub-tenants tab, click the three-dot menu next to a sub-tenant. You’ll see the options to Change Parent or Delink Parent.
Change Parent and Delink Parent actions on a sub-tenant row
Change Parent — pick a new parent from the selector. Any parent that would push the moved subtree past level 4 is disabled. Confirm to move the tenant (and every tenant below it) under the new parent. Inherited values are recomputed against the new chain.
Change Parent modal
Delink Parent — detaches the tenant from its current parent and promotes it to a root. Its subtree comes along; local values stay as they are; values and preferences that were being inherited from the parent chain stop applying.
Delink Parent modal
Send parent_id on the tenant upsert endpoint — a tenant ID to re-parent, or null (or an empty string) to delink and promote to a root:
Local values on the moved tenant (and every tenant below it) stay as they are. Inherited values are resolved from the new chain at the next send.
A re-parent that would push any tenant in the moved subtree past level 4 is rejected with a 400. So is any move that would create a loop (moving a tenant under one of its own descendants).
Deleting a tenant is permanent — its settings, preferences, and per-tenant profiles are gone, and creating a new tenant with the same ID doesn’t restore any previous settings. Notifications already in flight are not affected — they finish with the settings that were in effect when they were triggered. When the tenant has children, you decide what happens to them with children_action.
children_action
What happens to the children
"orphan" (default, also applied when omitted)
Children become root tenants. Their data stays; the deleted parent is dropped from their ancestor chain.
"reassign"
Children move under the tenant given in reassign_to. SuprSend checks the new subtree still fits within 5 levels. reassign_to is required — if omitted or null, the API returns 400.
"delete"
Every child (and their children, all the way down) is deleted too.
Dashboard
API
Open the tenant’s detail page and click the three-dot menu at the top-right corner, then choose Delete.
Delete option on a sub-tenant row
If the tenant has children, the confirmation modal gives you three options — reassign to a specific tenant, leave children as roots, or delete them all. If reassign is selected, you can choose the new parent from the dropdown.
Once sub-tenants exist, the Tenants listing adds two columns to every row — Parent and Level — so you can see each tenant’s place in the tree at a glance. On each row, a small dot next to logo, brand colors, or social_links means that value is inherited from an ancestor; no dot means it’s set locally on this tenant.
Tenant listing page after sub-tenants are added
Use the filter icon at the top of the listing to narrow the view:
Ancestor — pick a tenant and the listing shows every tenant in its subtree, at any depth.
Level — restrict to specific depths (0 = roots, 4 = deepest).
Combine them to narrow further — e.g. ancestor acme + level 1 returns every project directly under acme.
5 levels max. Root = level 0, deepest allowed = level 4. Every create and re-parent is checked — moves that would go past the limit are rejected with a 400.
One parent per tenant. Every non-root tenant has exactly one parent_id. There’s no multi-parent or DAG model.
id is unique across the workspace. A tenant can’t share its id with its parent, sibling, or any other tenant. IDs are ≤ 64 chars and accept letters, digits, ., _, and -.
Live inheritance. Editing an ancestor’s field takes effect right away for every tenant below that hasn’t overridden it. There’s no snapshot at create time.
Properties are merged per inner key. Override social_links.website on a child and other inner keys (twitter, linkedin, …) keep inheriting from the parent.
Category preferences merge per setting. Within a category, preference, digest_schedule, and conditions each inherit independently — overriding one doesn’t mean that other settings will also stop inheriting.
Tenant Preference — blocked channels and categories. Tenant blocked_channels, per-category blocked_channels, and category enabled_for_tenant: false cascade to every descendant and can’t be reversed.
Re-parenting is safe. Local values on the moved tenant stay put; inherited values resolve from the new chain at the next send. Notifications in flight finish with the settings that were in effect at trigger time.
The default tenant is unchanged. Every workspace still ships with the default tenant. It behaves as a root tenant with no children until you give it any.
5 levels total. Root is level 0; the deepest allowed level is 4. Creates and re-parents that would go past this are rejected with a 400 that names the tenant and level that busted the limit.
What happens if I edit a parent's primary_color?
Every tenant below it that hasn’t overridden primary_color picks up the new value right away — the next workflow triggered at any of those tenants uses the new value. Tenants that set their own primary_color aren’t affected.
Can I mix hierarchical and flat tenants in the same workspace?
Yes. A tenant with parent_id: null is a root and behaves exactly like flat tenants do today. You can use sub-tenants for one part of your customer base and leave the rest flat.
Do preferences, vendors, template variants, and user-tenant mapping cascade?
Not in this phase. Only properties, brand fields, tenant-level blocked_channels, and the category-level block settings (enabled_for_tenant, visible_to_subscriber, per-category blocked_channels) cascade. Everything else applies to the triggered tenant only. Hierarchy support for the rest ships in a later phase — reach out to support@suprsend.com if you have a use case that needs it sooner.
Can I re-parent a tenant that has children?
Yes. The whole subtree moves with it. SuprSend checks that the moved subtree still fits within the 5-level limit under the new parent, and rejects the move with a 400 if it doesn’t. Local values on every tenant in the subtree stay as they are; inherited values resolve from the new chain at the next send.
Can I reuse a tenant id after deleting it?
Yes. Deletes are soft — the old record is marked deleted and no longer reachable by id. Creating a new tenant with the same id starts a brand-new record; it does not bring back the deleted tenant’s users, subscriptions, or history.
Is there a performance cost to deep hierarchies?
No. Send-time resolution is optimized and doesn’t add measurable latency, even at the maximum depth of 5 levels.
My child tenant isn't picking up a parent update at send time.
Inheritance is resolved live at send time, so a workflow triggered after the parent update should already reflect the new value. If it doesn’t, check that (a) the write on the parent actually returned 200, (b) you’re triggering at the right child (parent_id and ancestors match what you expect), and (c) the field isn’t overridden on the child — a local value always wins over an inherited one.
My blocked_channels change didn't take effect for a descendant.
A blocked_channels block at any level flows down and can’t be undone. The descendant’s effective list at send time is the union across the chain — every ancestor’s blocks plus its own. If you were trying to unblock a channel by removing it from a child’s blocked_channels, that isn’t possible — an ancestor’s block always wins. Remove it at the level where it was originally set.
Can users have a global preference in a workspace?
No. Every user preference — category or channel — is always saved against a tenant. Preference writes require a tenant_id query param; without one, the API rejects the request. If your workspace uses just the built-in default tenant, all writes land there and behave workspace-wide in practice, but there is no global-across-all-tenants preference on a user.If you need a workspace-wide default preference that individual tenants can then override per user, model your tenants as sub-tenants of the default tenant. For example, keep the Company at default, nest Projects under it, and nest Cycles under each Project. The user’s preference at default acts as the global default; a preference set on a Project (or a Cycle) wins for triggers scoped to that subtree.
My customers are mapped as tenants and users need a global preference plus a per-tenant override. How do I model this?
Re-parent each customer tenant so it becomes a child of the default tenant. default then acts as the global layer, and each customer stays its own tenant where users can override.
Re-parent every customer tenant to default (or create new ones with parent_id: "default"). Existing users, subscriptions, and history stay intact.
Save the user’s global preference by writing to tenant_id=default.
Save a customer-specific override by writing to tenant_id=<customer_tenant_id>.
At trigger time, pass the customer’s tenant_id. SuprSend walks up the chain — the customer’s preference wins if the user set one there; otherwise the default preference applies; if neither is set, the customer tenant’s own default preference for the category applies.
Which plans include sub-tenants?
Sub-tenants are available on the Enterprise plan and as an add-on for the Business plan, matching how multi-tenancy is available today.
