Skip to main content

What are Tenant Merchants?

Tenant Merchants represent logical boundaries within a Tenant for configuration and operational isolation. They enable organizations with multiple business units, regional entities, or sub-merchants to manage independent service configurations within a single Tenant.

If you operate multiple business units that each need their own payment service configurations, Tenant Merchants allow you to consolidate operations under one Tenant while maintaining separate configurations for each business unit.

Why Use Tenant Merchants?​

If your organization has multiple business units that each need independent payment configurations, Tenant Merchants allow you to manage them all within a single Tenant:

  • Configuration Isolation: Each Tenant Merchant maintains independent settings for payment services like Account Updater and Network Tokens, without affecting other Merchants in the same Tenant.
  • Operational Simplicity: Manage multiple business units from a single Tenant with one set of API keys and a unified integration.
  • Clear Organizational Mapping: Establish a direct relationship between your real-world organizational structure (business units, brands, sub-merchants) and their corresponding configurations in Basis Theory.

How Tenant Merchants Work​

Tenant Merchants exist within a Tenant and allow you to scope service configurations to specific business units:

Tenant Merchants Overview

Each Tenant Merchant contains its own settings that can override Tenant-level defaults. When you make API calls for services like Account Updater or Network Tokens, you can include a merchant_id parameter to specify which Merchant configuration should be used.

Common Use Cases​

Platform Providers​

Software platforms that manage payment processing for multiple sub-merchants need to provide isolated configurations for each customer. Tenant Merchants enable platforms to:

  • Onboard new sub-merchants without creating separate Tenants or managing additional API keys
  • Allow each sub-merchant to maintain their own Account Updater and Network Tokens configurations
  • Maintain rate limits and operational isolation between sub-merchants
  • Scale efficiently as their customer base grows

For example, a vertical SaaS platform serving hundreds of businesses can use a single Tenant with individual Tenant Merchants for each customer, providing configuration independence while maintaining centralized management.

Multi-Brand Operations​

Organizations operating multiple brands or properties often need different payment service configurations for each brand. Tenant Merchants are particularly valuable when you need:

  • Independent Account Updater and Network Tokens configurations for each property (reflecting different acquiring relationships)
  • Isolated rate limits to prevent one property's transaction volume from impacting others
  • Different compliance configurations based on regional or jurisdictional requirements

For example, a hospitality company operating multiple hotel brands can use Tenant Merchants to maintain separate configurations for each brand—each with its own acquiring relationships and compliance requirements—while managing everything from a single Tenant.

Getting Started​

Tenant Merchants are configured at the Tenant level by Basis Theory. To set up Tenant Merchants for your organization, please reach out to support.

Once configured, you can view your Tenant Merchants through the API. See the Tenant Merchants API reference for details on listing with Tenant Merchants.

Last updated on