# Exposure API

> How exposed a business is to automatic-renewal claims: aggregate subscriber counts from live Stripe (never personal data) or the owner's estimate.

The plan's risk estimates use it.

| Operation | Endpoint |
|---|---|
| [Get a site's exposure](#retrieveSiteExposure) | `GET /v1/sites/{site}/exposure` |
| [Record the owner's exposure estimate](#updateSiteExposure) | `POST /v1/sites/{site}/exposure` |

## The Exposure object

Round 43: how exposed this business is (aggregate live Stripe counts, the owner's estimate, or unknown), with summary.line to show people and, while nothing is known, one optional owner question (exposure.question: ask once, never blocking). Same object as retrieveSiteExposure. Never changes the status or next_action.

| Field | Type | Description |
|---|---|---|
| `object` | enum | String representing the object's type. Always "exposure". |
| `site` | string | The site. |
| `livemode` | boolean | true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox). |
| `source` | enum | stripe_live: aggregate counts read from live Stripe (read-only connection); owner_estimate: the owner's answer to the one question; unknown: neither yet (levels are general estimates). Test-mode Stripe data is never used. One of `stripe_live`, `owner_estimate`, `unknown`. |
| `estimate_by` | enum \| null | Round 43 review: owner_estimate only: who entered it. agent (an API key, never confirmed by the owner): shown as "estimate entered by your agent", and it never lowers a risk level below what no estimate gives. One of `owner`, `agent`. |
| `as_of` | integer \| null | When the figures were read or answered. Unix timestamp in seconds. |
| `active_subscriptions` | integer \| null | Active + trialing subscriptions in live Stripe (null when unknown). |
| `trialing` | integer \| null | Of which in a trial. |
| `annual_share` | number \| null | Share (0-1) billed yearly or longer. |
| `by_jurisdiction` | object | Subscriptions per billing location: "US-CA" (a U.S. state), "US" (state unknown), another country's code, or "unknown". Empty when locations could not be read (see gaps). Counts only. |
| `dispute_rate_90d` | number \| null | Disputes / successful charges over the last 90 days (0-1). |
| `band` | enum \| null | Subscriber band (owner estimate, or from the live count). One of `lt100`, `100to1k`, `1kto10k`, `gt10k`. |
| `ca_share` | enum \| null | Share in California (owner estimate, or from live locations). One of `low`, `medium`, `high`. |
| `gaps` | array of objects | Fields that could not be read and why (for example a permission the installed Stripe App does not have yet). |
| `truncated` | boolean | A read stopped at its cap: counts are lower bounds. |
| `summary` | object | The overall exposure line. |
| `summary.level` | enum | very_low, low, medium or high: Checkbox's estimate, not legal advice. One of `very_low`, `low`, `medium`, `high`. |
| `summary.line` | string | One line for people: counts, California share, dispute rate and the overall level. |
| `summary.reasons` | array of strings | What raised or lowered the level. |
| `summary.known` | boolean | false when nothing is known and levels are general estimates. |
| `question` | ExposureQuestion \| null | The optional owner question while nothing is known (null otherwise, or once answered or declined). |
| `stripe` | object | The live Stripe read (refreshed daily and when Stripe is connected). |
| `stripe.last_read` | integer \| null | When live Stripe was last read successfully. Unix timestamp in seconds. |
| `stripe.last_error` | string \| null | The last read failure, if the newest read failed (the previous figures are kept). |
| `disclaimer` | string | Estimates from public enforcement records and these counts; not legal advice. |

## Get a site's exposure {#retrieveSiteExposure}

`GET /v1/sites/{site}/exposure`

Aggregate subscriber counts read from live Stripe through the read-only connection (active and trialing subscriptions, the share billed yearly, counts per billing state or country, the 90-day dispute rate), refreshed daily and when Stripe is connected; else the owner's estimate; else unknown with one optional question. Counts only: no names, emails or addresses are stored. summary.line is the sentence to show people. Not legal advice.

**Scope** `sites:read` · **Operation** `retrieveSiteExposure`

SDK: `checkbox.siteExposures.retrieve()` (Node) · `checkbox.site_exposures.retrieve()` (Python). MCP / agents: operation `retrieveSiteExposure`.

#### Parameters

| Parameter | In | Type | Description |
|---|---|---|---|
| `site` **required** | path | string | Unique identifier of the site (site_…). |

#### Returns

Returns an [Exposure](https://checkbox.site/docs/api/exposure#the-exposure-object) object.

Errors use the [standard envelope](https://checkbox.site/docs/api/errors) with a stable `code` and, where useful, `next_action`.

```curl
curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/exposure \
  -u "$CHECKBOX_SECRET_KEY:"
```
```node
import Checkbox from '@checkbox-site/node';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const siteExposure = await checkbox.siteExposures.retrieve('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(siteExposure);
```
```python
import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

site_exposure = checkbox.site_exposures.retrieve("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(site_exposure)
```

```json title="Response"
{
  "object": "exposure",
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "livemode": false,
  "source": "stripe_live",
  "estimate_by": null,
  "as_of": 1793318400,
  "active_subscriptions": 1240,
  "trialing": 85,
  "annual_share": 0.3,
  "by_jurisdiction": {
    "US-CA": 210,
    "US-NY": 95,
    "US": 40
  },
  "dispute_rate_90d": 0.003,
  "band": "1kto10k",
  "ca_share": "medium",
  "gaps": [],
  "truncated": false,
  "summary": {
    "level": "low",
    "line": "1,240 active subscriptions in live Stripe on 2026-11-14, 17% in California, dispute rate 0.3% over 90 days. Overall exposure: medium.",
    "reasons": [],
    "known": true
  },
  "question": {
    "id": "exposure_estimate",
    "text": "About how many subscribers do you have, and how many are in California? (Optional: it only makes the risk estimates more accurate.)",
    "optional": true,
    "options": {
      "subscribers": [
        "lt100"
      ],
      "california_share": [
        "low"
      ]
    },
    "how_to_answer": "updateSiteExposure { subscribers: \"100to1k\", california_share: \"low\" } (MCP: call_api with operation_id updateSiteExposure); { declined: true } if the owner prefers not to say."
  },
  "stripe": {
    "last_read": 1793318400,
    "last_error": null
  },
  "disclaimer": "Checkbox's estimate from public enforcement records; not legal advice."
}
```

## Record the owner's exposure estimate {#updateSiteExposure}

`POST /v1/sites/{site}/exposure`

The owner's answer to the one optional question "About how many subscribers do you have, and how many are in California?": subscribers (lt100, 100to1k, 1kto10k, gt10k) and california_share (low, medium, high), or declined: true. Used only while live Stripe figures are not available; live figures win once read. Never blocks the plan. Round 43 review: an estimate sent with an API key is shown as "estimate entered by your agent" (estimate_by agent) and never lowers a risk level below what no estimate gives; ask the owner, never guess.

**Scope** `sites:write` · **Idempotent** (send `Idempotency-Key`) · **Operation** `updateSiteExposure`

SDK: `checkbox.siteExposures.update()` (Node) · `checkbox.site_exposures.update()` (Python). MCP / agents: operation `updateSiteExposure`.

#### Parameters

| Parameter | In | Type | Description |
|---|---|---|---|
| `site` **required** | path | string | Unique identifier of the site (site_…). |

#### Body

| Field | Type | Description |
|---|---|---|
| `subscribers` | enum | About how many subscribers: lt100, 100to1k, 1kto10k, gt10k. One of `lt100`, `100to1k`, `1kto10k`, `gt10k`. |
| `california_share` | enum | About how many of them are in California: low (under about 8%), medium (8-20%), high (over 20%). One of `low`, `medium`, `high`. |
| `declined` | boolean | true: the owner prefers not to say (the question is not asked again). |

#### Returns

Returns an [Exposure](https://checkbox.site/docs/api/exposure#the-exposure-object) object.

Errors use the [standard envelope](https://checkbox.site/docs/api/errors) with a stable `code` and, where useful, `next_action`.

```curl
curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/exposure \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "subscribers": "100to1k",
  "california_share": "low"
}'
```
```node
import Checkbox from '@checkbox-site/node';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const siteExposure = await checkbox.siteExposures.update('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b', { subscribers: '100to1k', california_share: 'low' });
console.log(siteExposure);
```
```python
import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

site_exposure = checkbox.site_exposures.update("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", subscribers="100to1k", california_share="low")
print(site_exposure)
```

```json title="Response"
{
  "object": "exposure",
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "livemode": false,
  "source": "stripe_live",
  "estimate_by": null,
  "as_of": 1793318400,
  "active_subscriptions": 1240,
  "trialing": 85,
  "annual_share": 0.3,
  "by_jurisdiction": {
    "US-CA": 210,
    "US-NY": 95,
    "US": 40
  },
  "dispute_rate_90d": 0.003,
  "band": "1kto10k",
  "ca_share": "medium",
  "gaps": [],
  "truncated": false,
  "summary": {
    "level": "low",
    "line": "1,240 active subscriptions in live Stripe on 2026-11-14, 17% in California, dispute rate 0.3% over 90 days. Overall exposure: medium.",
    "reasons": [],
    "known": true
  },
  "question": {
    "id": "exposure_estimate",
    "text": "About how many subscribers do you have, and how many are in California? (Optional: it only makes the risk estimates more accurate.)",
    "optional": true,
    "options": {
      "subscribers": [
        "lt100"
      ],
      "california_share": [
        "low"
      ]
    },
    "how_to_answer": "updateSiteExposure { subscribers: \"100to1k\", california_share: \"low\" } (MCP: call_api with operation_id updateSiteExposure); { declined: true } if the owner prefers not to say."
  },
  "stripe": {
    "last_read": 1793318400,
    "last_error": null
  },
  "disclaimer": "Checkbox's estimate from public enforcement records; not legal advice."
}
```
