# Customer Tiers

Airbyte Cloud customers are classified into tiers based on their commercial relationship. The tier system protects sensitive customers from unintended operational impact by gating destructive operations and enriching discovery results.

## Tier Definitions

| Tier | Criteria | Approximate Count | Risk Level |
|------|----------|-------------------|------------|
| **TIER_0** | Strategic/enterprise accounts and active sales opportunities | ~196 orgs | Highest — revenue-critical accounts |
| **TIER_1** | Named accounts (other significant customers) | ~92 orgs | High — important accounts |
| **TIER_2** | All other customers | ~100k orgs | Standard — default tier |

Tier assignments originate in Salesforce and flow through dbt into BigQuery (`airbyte-data-prod.airbyte_warehouse_reporting.sales_customer_attributes`). The Ops MCP tier cache fetches only Tier 0 and Tier 1 orgs; any organization not in the cache is implicitly TIER_2.

## How Tier Filtering Works

Every MCP tool that operates on customer data requires a `customer_tier_filter` parameter or annotates results with tier information. Tools with a `customer_tier_filter` parameter default to `"TIER_2"`, which means:

- **A naive agent call** (one that doesn't specify a tier) only sees or affects TIER_2 customers. This is the safe default.
- **To operate on sensitive customers**, the agent must explicitly pass `"TIER_0"`, `"TIER_1"`, or `"ALL"`.
- **`"ALL"` bypasses the filter** but emits a warning for TIER_0 and TIER_1 customers, reminding the operator of the risk.

### Discovery Tools

The following discovery tools enrich every result row with `customer_tier` and `is_eu` fields, and filter results by the specified tier:

- `query_prod_connections_by_connector`
- `query_prod_connections_by_stream`
- `query_prod_recent_syncs_for_connector`
- `query_prod_failed_sync_attempts_for_connector`

The following tools enrich results with `customer_tier` and `is_eu` annotations (no filtering):

- `query_prod_workspaces_by_email_domain`

Filtering is client-side (Python post-processing after the SQL query returns). The SQL queries themselves are tier-unaware.

### Pinning Tools (Guardrails)

The following pinning tools resolve the target's tier **before** executing the destructive API call. The operation is rejected if the actual tier does not match `customer_tier_filter`:

- `set_cloud_connector_version_override` (actor-level)
- `set_workspace_connector_version_override`
- `set_organization_connector_version_override`

CLI equivalents (`set-version-override`, `clear-version-override`) accept `--customer-tier-filter` with the same behavior.

### Tier Lookup Tool

The `lookup_customer_tiers` tool accepts mixed lists of organization IDs, workspace IDs, and/or connection IDs and returns enriched entries with tier classification, EU region flag, and a summary.

## Expected Agent Workflow

1. **Agent calls a tool with default tier** (`TIER_2`) and gets results scoped to standard customers only.
2. **If the agent needs to see or affect a sensitive customer**, it must know the tier. It can:
   - Call `lookup_customer_tiers` with the workspace or org ID to discover the tier.
   - Receive a tier mismatch error from a pinning tool, which includes the actual tier in the error message.
3. **Agent retries with the explicit tier** (e.g., `customer_tier_filter="TIER_0"`).
4. **For TIER_0 or TIER_1 operations**, the agent should escalate to a human before proceeding. Use `escalate_to_human` to post to `#human-in-the-loop` on Slack.

## EU Region Compliance

Every workspace is tagged with `is_eu` (derived from `dataplane_name == "EU"`). This flag is included in all discovery results and tier lookups. Use it to identify customers whose data is processed in the EU region for compliance-sensitive operations.

## Data Pipeline

```
Salesforce (Account.organization_id__c + customer_tier)
  → dbt model: sales_customer_attributes
    → BigQuery: airbyte-data-prod.airbyte_warehouse_reporting.sales_customer_attributes
      → Ops MCP tier cache (disk, 24h TTL, ~288 rows)
```

The cache stores only `organization_id` and `customer_tier` — no PII (customer names, email domains) is cached.

## Cache Details

- **Location:** `~/.cache/airbyte-ops-mcp/`
- **Org tier cache** (`tier_cache.json`): Bulk-fetched from BigQuery. Contains only Tier 0 and Tier 1 orgs. Refreshed every 24 hours.
- **Workspace-org cache** (`workspace_org_cache.json`): Lazy-populated from the Prod DB Replica on first lookup. Maps workspace IDs to their organization and dataplane region. Same 24-hour TTL.
- **Force refresh:** Call `refresh_customer_tier_cache` to bypass TTL and re-fetch from BigQuery.
- **Cache stats:** Call `get_customer_tier_cache_stats` to inspect cache freshness and size.

## Related Resources

- [Progressive Rollouts](./progressive-rollouts.md) — rollout lifecycle, including tier-targeted rollouts
- [AGENTS.md](../AGENTS.md) — agent-specific behavioral guidance for tier-aware operations
- [CONTRIBUTING.md](../CONTRIBUTING.md) — credentials and environment setup
