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

# Customer Suppressions

> View active suppressions for a customer — what's blocked, why, and when it expires.

## GET /api/v1/customers/:customerId/suppressions

Returns all active and expired suppression records for a specific customer. Suppressions are created automatically by the suppression engine when outcomes trigger contact policy rules (e.g., an `unsubscribed` outcome activates the "Suppress After Unsubscribe 90d" policy).

### Response

```json theme={null}
{
  "data": [
    {
      "id": "supp_001",
      "scope": "global",
      "scopeId": "all",
      "offerName": null,
      "policyType": "cooldown",
      "reason": "Cooldown 336h after unsubscribed",
      "triggerCount": 2,
      "expiresAt": "2026-04-10T00:00:00.000Z",
      "createdAt": "2026-03-27T00:00:00.000Z",
      "isActive": true
    },
    {
      "id": "supp_002",
      "scope": "offer",
      "scopeId": "offer_001",
      "offerName": "Annual Review Consultation",
      "policyType": "cooldown",
      "reason": "Cooldown 168h after unsubscribed",
      "triggerCount": 1,
      "expiresAt": "2026-04-03T00:00:00.000Z",
      "createdAt": "2026-03-27T00:00:00.000Z",
      "isActive": true
    }
  ]
}
```

### Field Reference

| Field          | Type         | Description                                                                                                                                                                                                          |
| -------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scope`        | string       | Suppression scope: `global` (all offers), `offer` (specific offer), `offer_channel` (a specific offer on a specific channel — written by channel-scoped policies), `channel` (all offers on one channel), `category` |
| `scopeId`      | string       | ID of the scoped entity; `"all"` for global; `"offerId:channelId"` for `offer_channel`; `"categoryId"` or `"categoryId:subCategoryId"` for category                                                                  |
| `offerName`    | string\|null | Human-readable offer name (resolved for `offer` and `offer_channel` suppressions)                                                                                                                                    |
| `policyType`   | string       | The contact policy type that created this suppression (e.g., `cooldown`, `frequency_cap`, `outcome_based`)                                                                                                           |
| `reason`       | string       | Human-readable reason for the suppression                                                                                                                                                                            |
| `triggerCount` | integer      | How many times this suppression has been triggered                                                                                                                                                                   |
| `expiresAt`    | datetime     | When the suppression expires and the customer becomes eligible again                                                                                                                                                 |
| `createdAt`    | datetime     | When the suppression was first created                                                                                                                                                                               |
| `isActive`     | boolean      | `true` if the suppression is currently active (not expired)                                                                                                                                                          |

### How Suppressions Are Created

Suppressions are created automatically by the suppression engine when outcomes are recorded via the [Respond API](/api-reference/respond):

1. Customer unsubscribes → "Suppress After Unsubscribe 90d" policy creates a 90-day global suppression
2. Customer dismisses an offer → "Offer-Level Cooldown 7d" creates a 7-day offer-scoped suppression
3. Customer converts → "Post-Purchase Cooldown 14d" prevents re-showing the same offer for 14 days

The written record never exceeds the scope of the policy that created it — a channel-scoped policy writes `offer_channel` / `channel` records that apply only on that channel, and a policy never fires for interactions outside its own scope. See [Scope-on-Write](/decisioning/contact-policies#scope-on-write).

The Customer Viewer UI in Studio shows these suppressions in the "Suppressions" tab with active/expired status badges and countdown to expiry.

## Lifecycle

A suppression never outlives the policy that wrote it. Deleting a contact policy (or deactivating it via `PUT` with a non-`active` status) removes its materialized suppressions immediately, and the decision-time read additionally ignores any suppression whose policy is no longer active. Otherwise a suppression applies until its `expiresAt`.