Checkbox Docs

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.

OperationEndpoint
Get a site's exposureGET /v1/sites/{site}/exposure
Record the owner's exposure estimatePOST /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.

FieldTypeDescription
objectenumString representing the object's type. Always "exposure".
sitestringThe site.
livemodebooleantrue for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).
sourceenumstripe_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_byenum | nullRound 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_ofinteger | nullWhen the figures were read or answered. Unix timestamp in seconds.
active_subscriptionsinteger | nullActive + trialing subscriptions in live Stripe (null when unknown).
trialinginteger | nullOf which in a trial.
annual_sharenumber | nullShare (0-1) billed yearly or longer.
by_jurisdictionobjectSubscriptions 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_90dnumber | nullDisputes / successful charges over the last 90 days (0-1).
bandenum | nullSubscriber band (owner estimate, or from the live count). One of lt100, 100to1k, 1kto10k, gt10k.
ca_shareenum | nullShare in California (owner estimate, or from live locations). One of low, medium, high.
gapsarray of objectsFields that could not be read and why (for example a permission the installed Stripe App does not have yet).
truncatedbooleanA read stopped at its cap: counts are lower bounds.
summaryobjectThe overall exposure line.
summary.levelenumvery_low, low, medium or high: Checkbox's estimate, not legal advice. One of very_low, low, medium, high.
summary.linestringOne line for people: counts, California share, dispute rate and the overall level.
summary.reasonsarray of stringsWhat raised or lowered the level.
summary.knownbooleanfalse when nothing is known and levels are general estimates.
questionExposureQuestion | nullThe optional owner question while nothing is known (null otherwise, or once answered or declined).
stripeobjectThe live Stripe read (refreshed daily and when Stripe is connected).
stripe.last_readinteger | nullWhen live Stripe was last read successfully. Unix timestamp in seconds.
stripe.last_errorstring | nullThe last read failure, if the newest read failed (the previous figures are kept).
disclaimerstringEstimates 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

ParameterInTypeDescription
site requiredpathstringUnique 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:"
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

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

ParameterInTypeDescription
site requiredpathstringUnique identifier of the site (site_…).

Body

FieldTypeDescription
subscribersenumAbout how many subscribers: lt100, 100to1k, 1kto10k, gt10k. One of lt100, 100to1k, 1kto10k, gt10k.
california_shareenumAbout how many of them are in California: low (under about 8%), medium (8-20%), high (over 20%). One of low, medium, high.
declinedbooleantrue: 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"
}'
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."
}

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.