Payload CMS Multi-Tenant: 5 Ways isGlobal Saves Data

In Payload CMS 3.7+, managing shared resources efficiently is key to a scalable multi-tenant architecture. By marking a collection as global, you eliminate data duplication and provide a single source of truth accessible to every tenant in your system.

How to Configure a Global Collection

To make a collection available across your entire instance, use the isGlobal: true property within your multiTenantPlugin configuration. This prevents the plugin from injecting a tenant relationship field and bypasses automatic tenant-based filtering.

multiTenantPlugin<Config>({
  tenantsSlug: 'tenants',
  // ... other config
  collections: {
    // Standard Tenant-Aware Collection
    [Media.slug]: {},

    // BENEFIT: Truly Global Collection (Shared Data)
    [Industries.slug]: {
      isGlobal: true,
    },
  },
}),

The Architecture Caveat: Data Integrity

Top Use Cases for Global Collections

Setting a collection to global is highly beneficial for "Master Data" that remains constant regardless of which client or organization is logged in.

1. Centralized Taxonomy (Industries & Categories)

Instead of forcing every tenant to create their own list of "Healthcare," "Finance," or "Tech," you manage one master list.

• Consistent reporting and analytics across your entire platform.

2. Global Product Catalogs

If you run a marketplace where all tenants sell the same core items but manage their own inventory.

• Update a product description or image once, and it reflects across every tenant's storefront instantly.

3. Support & Documentation

Shared help articles, FAQs, or system-wide announcements.

• Simplifies content management by preventing admins from copy-pasting the same support docs into every tenant.

4. Geographical & Localization Data

Custom lists of Regions, Currencies, or Languages that your specific business logic requires.

• Ensures data validation remains identical across all business units.

TypeScript Optional vs. Database Required: A Critical Distinction

Yes, exactly! TypeScript says the data is optional (it can be null or undefined), but the database column must still exist to store that "null" value.

Here is the distinction:

TypeScript (tenant?): "This object property might not have a value." (Correct for global vendors).

Database Query (SELECT tenant_id FROM vendor): "Go look in the tenant_id column."

When Payload runs a query, it asks for every field defined in the config. Because the plugin added the field to the config, Payload asks Postgres for the tenant_id column.

If you hadn't run that migration, the column wouldn't exist, and Postgres would crash saying: "I don't have a column named tenant_id to look inside," even though all we wanted to find inside was null.

So, the column is required to exist, but the data inside it is optional (nullable).

Thanks, Matija Matija