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