Skip to main content
Subtenants are used when a single tenant needs to link multiple instances of the same connector, in the same flow. This might happen when you have:
  • A Shopify connection with multiple stores
  • A Quickbooks Online connection with multiple Quickbooks companies
For connections across different connectors and/or flows, subtenants are not necessary. If your customers are only linking a specific Salesforce organization or a single Netsuite account, you can stick to regular tenants.

Quick Setup

  1. Navigate to Settings > Widget
  2. Toggle on Enable subtenant functionality
Once enabled, tenants with a _ delimeter will be recognized as a subtenant. You can then create subtenants using either:
  • API: Use the reserved naming convention {ROOT TENANT}_{SUB TENANT ID}.
  • Widget: Use the dropdown subtenant manager in the quick actions tab.

How subtenants work

Subtenants follow a specific naming pattern: {ROOT_TENANT}_{SUBTENANT_ID}. For example, acme_2 represents a subtenant where:
  • acme is the root tenant
  • 2 is the subtenant identifier
This naming convention helps maintain the relationship while allowing individual management across APIs, CLI, and the admin panel.

Benefits of using subtenants

Using subtenants instead of separate tenants offers three key advantages:
  • Billing: Subtenants are billed as a single tenant, based on the root_tenant_id.
  • Shared links: The same root tenant ID + JWT token can manage all of its subtenants. You can also fetch the root tenant’s connection (linkedSource/linkedConnector) to retrieve all associated subtenants.
  • ETL functions: Parents and subtenants have privileged access to each others’ snapshot data in ETL scripts.