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

# User Tenant Preferences

> Courier allows users to manage notification preferences per tenant, supporting layered opt-in/out choices based on tenant-specific or inherited defaults.

## Overview

User tenant preferences enable user-driven notification control by allowing users to set different preference choices for each tenant they belong to. This creates a layered preference system where users can have fine-grained control over notifications across different organizational contexts.

For example, a user might want to receive production alerts for their main project but opt out of development notifications for staging environments, or receive different types of notifications for different teams or organizations.

<Note>
  **Availability**: User-Tenant Preferences are available for Enterprise customers. Contact [Courier Support](mailto:support@courier.com) for access or [Request a Demo](https://www.courier.com/request-demo) to learn more about how Courier could help you.
</Note>

## Key Features

Courier's tenant preference system provides:

* **Per-Tenant Preferences** - Users can set different preferences for each tenant relationship
* **Layered Defaults** - Preferences inherit from tenant defaults but can be overridden by users
* **Hierarchical Inheritance** - Parent tenant preferences flow down to child tenants
* **Flexible Opt-in/Out** - Users can opt in to some tenants while opting out of others
* **Context-Aware Delivery** - Notifications respect the preference context of the specific tenant

## Preference Hierarchy

Adding tenant context creates multiple layers of preferences for a single user. For example, if you design tenants to map to your organizational structure (cloud provider with multiple projects), a user can have different preferences at each level:

```mermaid actions={false} theme={null}
flowchart TD
    W["Workspace: Alerts ON, email only"] --> P["Parent Tenant: Acme Corp"]
    P --> T1["prod-project: Alerts ON, email + slack"]
    P --> T2["stage-project: Alerts OFF"]
    T1 --> U1["User preference: ON ✓"]
    T2 --> U2["User preference: OFF ✗"]
```

In this example, the same user receives alert notifications via email and Slack for `prod-project` but receives nothing for `stage-project`, even though the workspace default is alerts ON.

## Preference Resolution Order

At send time, Courier merges preference layers top-to-bottom. Each layer overrides the one above it; only explicitly set fields are applied, and unset fields pass through.

1. **Workspace-level defaults** — Global defaults set on the subscription topic or preference page
2. **Parent tenant defaults** — Inherited from the [tenant hierarchy](/platform/tenants/tenant-deepdive#hierarchical-inheritance)
3. **Tenant defaults** — Defaults configured on the specific tenant via [default preferences](/platform/tenants/tenant-deepdive#default-preferences-management)
4. **User-level preferences** — The user's own global preference choices
5. **User-tenant preferences** — The user's per-tenant overrides (highest priority)

<Info>
  A user's **global** preferences and their **per-tenant** preferences are independent. Setting a global preference does not propagate to tenant-specific contexts. If a user opts out globally but a tenant default opts them in, the tenant default wins for that tenant's notifications unless the user also sets a per-tenant opt-out.
</Info>

## Tenant Defaults

If a user has not set their own preferences for a tenant, Courier uses the tenant's defaults. Each tenant can configure its own defaults — see [Default Preferences](/platform/tenants/tenant-deepdive#default-preferences-management).

**Example tenant default behavior:**

* Tenant A defaults: Opted IN for alerts, Email + Slack channels
* User has no preferences set for Tenant A
* Result: User receives alerts via Email + Slack for Tenant A notifications

### Parent Tenant Defaults

When using parent tenants, tenant preferences follow the same hierarchy loading technique described in [Hierarchical Inheritance](/platform/tenants/tenant-deepdive#hierarchical-inheritance). Parent tenant default preferences are loaded first, then child tenants can override specific fields.

**Example inheritance:**

* Parent Tenant: Alerts OPTED\_IN, channels: \[email]
* Child Tenant: Alerts OPTED\_IN, channels: \[email, slack]
* User preference: None set
* Result: User receives alerts via Email + Slack (child overrides parent's channel list)

<Note>
  Courier may also be auto-inferring the Tenant based on a single-user tenant membership, so if you have created tenant memberships, you need to set up your Inbox and Toast SDKs with a `tenantId`. More details on [auto-infer here](/platform/tenants/tenant-deepdive#auto-infer-tenant-context)
</Note>

## Related Resources

<CardGroup cols={2}>
  <Card title="Tenants Overview" href="/platform/tenants/tenants-overview" icon="building">
    Learn about tenant hierarchies and default preferences
  </Card>

  <Card title="Preferences Overview" href="/platform/preferences/preferences-overview" icon="sliders">
    Complete preference management documentation
  </Card>
</CardGroup>