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.
Tenant MetadataJob Details