> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suprsend.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tenant Preferences

> Learn how to manage preferences for your tenants and their users.

Tenants (previously named as brands) represent a segment that users belong to. They can be organizations, teams within an organization, subsidiary companies, or different product lines in the same business. If you're a B2B application or a multi-tenant SaaS product, you can use tenant preferences to allow platform admins to control what tenants can access, or allow tenant admins to set default preferences for their users.

## How tenant preferences work

Tenant preferences sit between global category defaults and user preferences. They let platform admins restrict what a tenant can access, and let tenant admins override defaults for their users. Notifications are sent only if the category and channel are allowed at all three levels.

## Platform admin: Controlling tenant access

As a platform administrator, you can define which notification categories and channels are available to different tenants. For example, if you're a SaaS platform with paid features and some clients haven't subscribed to those features, you can hide notification categories related to the paid features for those tenants.

<Steps>
  <Step title="Access tenant settings">
    Go to the [tenant details page on SuprSend dashboard](https://app.suprsend.com/en/staging/tenants/default/tenant_preference)
  </Step>

  <Step title="Disable categories or channels">
    Disable categories or set channels as opt-out that aren't valid for specific tenants
  </Step>

  <Step title="Save changes">
    Tenants won't be able to set preferences in hidden categories, and notifications won't be sent to tenant users in those categories
  </Step>
</Steps>

<Frame caption="Tenant preference controls in the SuprSend dashboard">
  <img src="https://mintcdn.com/suprsend/gBZUU0PzLMZeIXEx/images/tenant-pref.png?fit=max&auto=format&n=gBZUU0PzLMZeIXEx&q=85&s=6b3cce606f29897ffee1e23c1a240bdc" alt="" width="2088" height="1324" data-path="images/tenant-pref.png" />
</Frame>

## Tenant admin: Setting defaults for their users

Tenant administrators can set [default preferences](/reference/update-tenant-default-preference) for their end users and hide categories that aren't applicable to their users. This gives tenant admins control over which notifications are sent to their users and which categories appear on their users' preference pages.

Tenant admins can override category defaults and hide categories that don't apply to their users. These overrides apply only to that tenant and don't change global category defaults.

**Common scenarios:**

* Hide entire sections (for example, Sales section) from users' preference pages
* Override channel requirements (for example, make email mandatory for System categories)
* Hide specific categories while keeping others visible

You can set tenant defaults via API or through SuprSend dashboard.

<CardGroup cols="2">
  <Card title="Via API" icon="code" iconType="solid">
    Use the <a href="/reference/update-tenant-default-preference">tenant preference API</a> to programmatically manage preferences
  </Card>

  <Card title="Via Dashboard" icon="grid" iconType="solid">
    Configure from the <a href="https://app.suprsend.com/en/staging/tenants/default/tenant_preference">tenant details page → Tenant Preference tab</a>
  </Card>
</CardGroup>

## Controlling preference UI for users

Tenants can control which categories appear on their users' preference pages and which notifications are sent.

<Tabs>
  <Tab title="Platform Admin Actions">
    * Turning off categories or channels for a tenant from the [tenant preference page](https://app.suprsend.com/en/demo/tenants/default/tenant_preference) automatically removes them from the user's preference view.
    * Hidden categories won't send notifications to tenant users, even if they previously opted in.
    * Tenants can't set preferences in categories disabled by the platform admin.
  </Tab>

  <Tab title="Tenant Admin Actions">
    * Set `visible_to_subscriber: false` in [default tenant preferences](/reference/update-tenant-default-preference) to hide categories from tenant users' preference pages.
    * This allows tenant admins to further limit visibility beyond platform-level settings.
    * Hidden categories are removed from user preference APIs and UI view for that tenant's users.
  </Tab>

  <Tab title="Impact & Precedence">
    * Categories hidden via `visible_to_subscriber: false` won't appear on preference pages
    * Tenant-level category overrides take precedence over user preferences
    * **Channel preferences:** If a platform admin disables a channel for a tenant, it cannot be re-enabled by the tenant or user
  </Tab>
</Tabs>

## Collecting preferences from tenant users

You can load user preferences for a tenant by passing `tenant_id` in REST APIs and [preference centre SDK](/docs/embedded-preference-centre). The hosted preference page automatically loads preferences corresponding to the tenant passed in the workflow trigger.

**Example API call:**

```bash theme={"system"}
GET /v1/user/{distinct_id}/preference/?tenant_id=acme-inc
```

<CardGroup cols="2">
  <Card title="REST APIs" icon="code" iconType="solid" href="/reference/get-user-full-preference">
    Use preference APIs with `tenant_id` parameter
  </Card>

  <Card title="Preference Center SDK" icon="puzzle-piece" iconType="solid" href="/docs/embedded-preference-centre">
    Embed preference center in your app
  </Card>
</CardGroup>

For implementation details, see [Capturing User Preferences](/docs/user-preferences#capturing-user-preferences).

## Triggering tenant workflows

You can trigger tenant workflows by passing `tenant_id` in your workflow trigger. Passing `tenant_id` ensures the workflow resolves `$tenant.*` variables (branding, preferences, routing) before sending notifications. This enables tenant-level customizations including template design, notification preferences, and vendor routing. [Read more about tenant workflows here](/docs/tenant-workflows).

## How tenant preferences are evaluated

When a workflow is triggered, preferences are evaluated for both the recipient and tenant before each delivery node. Notifications are sent only in categories and channels where both tenant and user preferences are `opt_in`.

The evaluation follows the precedence order: **User Preference → Tenant Default → Category Default**. Platform admin restrictions override all-if a platform admin disables a category or channel for a tenant, users will not receive notifications in that category, even if they previously opted in.

For detailed information on how preferences are evaluated at runtime, including debugging steps, see [Preference Evaluation](/docs/preference-evaluation).

***