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 | GET /v1/sites/{site}/exposure |
| Record the owner's exposure estimate | 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
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 object.
Errors use the standard envelope with a stable code and, where useful, next_action.
curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/exposure \
-u "$CHECKBOX_SECRET_KEY:"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);import os
from checkbox import Checkbox
checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])
site_exposure = checkbox.site_exposures.retrieve("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(site_exposure){
"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
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 object.
Errors use the standard envelope with a stable code and, where useful, next_action.
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"
}'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);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){
"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."
}Checkbox is compliance software, not a law firm; nothing in these docs is legal advice (details). You remain solely responsible for your subscription program, and Checkbox takes on no legal liability for it (Terms). Checkbox is a System1 company; Trust center · Status. For AI agents: every page is available as Markdown at the same URL plus .md; the index is /llms.txt.