Tenant Merchants

Tenant Merchants enable organizations with multiple business units, regional entities, or sub-merchants to manage independent service configurations within a single Tenant.

List Tenant Merchants

Get a list of Tenant Merchants for the Tenant.

GET

https://api.basistheory.com/tenants/{id}/merchants

Permissions

tenant:merchant:read

Request

cURL

curl "https://api.basistheory.com/tenants/e4e865b2-304e-4179-a040-9f8b3cd8bedb/merchants" \
-H "BT-API-KEY: <MANAGEMENT_API_KEY>"

Node

await client.tenants.merchants.list();

JavaScript (legacy)

import { BasisTheory } from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<MANAGEMENT_API_KEY>");

const tenantMerchants = await bt.tenants.listMerchants();

C#

await client.Tenants.Merchants.ListAsync(new MerchantsListRequest());

Java

new MerchantsClient(ClientOptions.builder().build()).list();

Python

client.tenants.merchants.list()

Go

members, err := client.Tenants.Merchants.List(ctx, &tenants.MerchantsListRequest{})

Query Parameters

Parameter	Required	Type	Default	Description
page	false	integer	1	Page number of the results to return.
size	false	integer	20	Number of the results to return per page. Maximum size of 50 results.

Response

Returns a paginated object with the data property containing an array of Tenant Merchants. Returns an error if Tenant Merchants could not be retrieved.

{
  "pagination": {...},
  "data": [
    {
        "id": "fb32ea26-2185-4ad2-a7bf-2fe69c00ae13",
        "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
        "name": "Merchant A",
        "features": {
          "account_updater": true,
          "network_tokens": false
        },
        "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
        "created_at": "2025-09-15T15:53:00+00:00",
        "modified_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
        "modified_at": "2025-09-18T15:53:00+00:00"
    },
    {...},
    {...}
  ]
}

Get a Tenant Merchant

Get a Tenant Merchant by ID in the Tenant.

GET

https://api.basistheory.com/tenants/{id}/merchants/{id}

Permissions

tenant:merchant:read

Request

cURL

curl "https://api.basistheory.com/tenants/e4e865b2-304e-4179-a040-9f8b3cd8bedb/merchants/fb32ea26-2185-4ad2-a7bf-2fe69c00ae13" \
-H "BT-API-KEY: <MANAGEMENT_API_KEY>"

Node

await client.tenants.merchants.get("merchantId");

JavaScript (legacy)

import { BasisTheory } from "@basis-theory/basis-theory-js";

const bt = await new BasisTheory().init("<MANAGEMENT_API_KEY>");

const merchant = await bt.merchants.retrieveMerchant(
  "fb32ea26-2185-4ad2-a7bf-2fe69c00ae13"
);

C#

await client.Tenants.Merchants.GetAsync("merchantId");

Java

new MerchantsClient(ClientOptions.builder().build()).get("merchantId");

Python

client.tenants.merchants.get(
  merchant_id="merchantId",
)

Go

merchant, err := client.Tenants.Merchants.Get(ctx, "merchantId")

URI Parameters

Parameter	Required	Type	Default	Description
id	true	uuid	null	The ID of the Tenant Merchant

Response

Returns a Tenant Merchant with the id provided. Returns an error if the Tenant Merchant could not be retrieved.

{
  "id": "fb32ea26-2185-4ad2-a7bf-2fe69c00ae13",
  "tenant_id": "77cb0024-123e-41a8-8ff8-a3d5a0fa8a08",
  "name": "Merchant A",
  "features": {
    "account_updater": true,
    "network_tokens": false
  },
  "created_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "created_at": "2025-09-15T15:53:00+00:00",
  "modified_by": "fb124bba-f90d-45f0-9a59-5edca27b3b4a",
  "modified_at": "2025-09-18T15:53:00+00:00"
}

Tenant Merchant Object

Attribute	Type	Description
id	uuid	Unique identifier of the Tenant Merchant
tenant_id	uuid	The Tenant ID that the membership is attached
name	string	The name assigned to this tenant merchant. Each tenant merchant within a tenant must have a unique name
features	object	A dictionary of feature flags for the tenant merchant, where each key represents a feature and the value is a boolean indicating whether the feature is enabled.
created_by	uuid	(Optional) The ID of the User or Application that created the Tenant Merchant
created_at	date	(Optional) Created date of the Tenant Member in ISO 8601 format
modified_by	uuid	(Optional) The ID of the User or Application that last modified the Tenant Merchant
modified_at	date	(Optional) Last modified date of the Tenant Member in ISO 8601 format