​
Why use subtenants?

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

📘 Note: for connections across different connectors and/or flows, subtenants are not necessary.

Subtenants are only needed when you need to make the “same link” twice. i.e. the same configured quickbooks supportedSource in a specific flow

​
How do subtenants work?

Subtenants are technically handled as unique tenants. They will appear as {ROOT TENANT}_{SUB TENANT ID}, (e.g., companyName_2).

This allows you to manage the connections individually across the API, CLI, and admin panel, while maintaining the association between them.

​
Why not just make two separate tenants?

There are three primary reasons to use subtenants in lieu of separate tenants:

  • Billing: Subtenants are billed as a single tenant, based on the root_tenant_id.
  • Shared links: The parent tenant linkedSource/linkedConnector returns the link and connection metadata across all subtenants.
  • ETL functions: Parents and subtenants have greater access to each others’ data in ETL scripts. This includes snapshots, allowing you to stitch data together across your root tenant’s connections.

​
Using subtenants

There are two ways to utilize subtenants:

  • Manually, by passing tenant IDs with the reserved _ value when creating new tenants.
  • In the widget, by toggling on Enable subtenant functionality in Settings > Widget
Tenant MetadataSources