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:

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 configuration_merchant_id parameter to specify which Merchant configuration should be used, or send the BT-MERCHANT-ID header to act as the merchant entirely (see Merchant Context below).

Merchant Context: Acting as a Merchant

Beyond configuration, requests can act as a specific merchant by sending the BT-MERCHANT-ID header. The acting merchant drives resource ownership, access scoping, and merchant-level rate limiting, while two optional body properties allow ownership and configuration to be selected explicitly.

Concern	Input	Meaning
Request context	BT-MERCHANT-ID header	The merchant the request is acting as. Scopes resource access, selects the merchant rate-limit bucket, and defaults ownership and configuration when their body properties are omitted.
Resource ownership	owner_merchant_id body property	Associates a newly created token or Network Token with a merchant. Defaults from the header. Network Tokens created from a merchant-owned source token inherit that token's owner when neither input is supplied; otherwise the resource remains unassociated.
Provider configuration	configuration_merchant_id body property	Selects the merchant whose Account Updater or Network Token configuration is used. Defaults from the header, then falls back to tenant-level configuration.
Legacy configuration selector	merchant_id body property (AU/NT)	Deprecated: use configuration_merchant_id instead. Selects configuration only; it never sets ownership or access scope.

Precedence

• Resolved configuration merchant: explicit configuration_merchant_id → legacy merchant_id → BT-MERCHANT-ID header → tenant-level configuration.
• Resolved resource owner: explicit owner_merchant_id → BT-MERCHANT-ID header → source token's owner (Network Tokens created from a merchant-owned token) → no merchant association. When more than one of these is supplied they must name the same merchant.
• Rate limiting and access scoping always follow the header; body properties never change the acting merchant.

Scoping Behavior

• Without the header, requests operate at the tenant level and can access every resource in the tenant, including merchant-owned ones.
• With the header, requests only see resources owned by that merchant. This includes not seeing unassociated resources: tokens created before you adopted the header are invisible to merchant-scoped requests (they remain fully accessible at the tenant level). There is no retroactive association, so send the header from day one on resources you want scoped.
• A BT-MERCHANT-ID that does not exist in your tenant responds 404 on any endpoint.
• An owner_merchant_id that differs from the header merchant, or from a merchant-owned source token when creating a Network Token, is rejected with a validation error.

Sending the Header from SDKs

All server SDKs support per-request headers through their request options:

Node

await client.tokens.create(
  { type: "card", data: cardData },
  { headers: { "BT-MERCHANT-ID": merchantId } }
);

Python

client.tokens.create(
    type="card",
    data=card_data,
    request_options={"additional_headers": {"BT-MERCHANT-ID": merchant_id}},
)

Java

client.tokens().create(request, IdempotentRequestOptions.builder()
    .addHeader("BT-MERCHANT-ID", merchantId)
    .build());

Go

client.Tokens.Create(ctx, request,
    option.WithHTTPHeader(http.Header{"BT-MERCHANT-ID": []string{merchantID}}))

C#

await client.Tokens.CreateAsync(request, new IdempotentRequestOptions
{
    AdditionalHeaders = new Dictionary<string, string?>
    {
        ["BT-MERCHANT-ID"] = merchantId
    }
});

Configuration vs. Ownership: Which Do You Need?

• Configuration only: if merchants exist purely to route Account Updater or Network Token requests to different provider configurations (for example, different acquiring relationships per brand), use configuration_merchant_id and skip the header. Resources stay tenant-level, with one exception: a Network Token created from a merchant-owned source token inherits that token's owner.
• Ownership and isolation: if merchants are separate businesses whose resources must be queryable and isolated per merchant, send BT-MERCHANT-ID on every request from the start.
• The two can differ on the same request: provider registration sometimes consolidates at a parent level while resources stay owned per sub-merchant.

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

You can create and onboard Tenant Merchants directly from the Basis Theory Portal. See the Onboard a Merchant guide for a walkthrough covering registration, per-network status, and onboarding requests.

Tenant Merchants are also accessible programmatically through the Tenant Merchants API.