Changes to the Checkbox API, SDKs, CLI, MCP server and legal catalog. API versions are dates; breaking changes only ship in a new version.

API versions are dates (Checkbox-Version). Backwards-compatible changes — new endpoints, new optional parameters, new fields, new event types, new error codes — ship continuously; breaking changes only in a new version. Legal catalog updates are announced as law updates and the law.changed webhook.

Current API version: 2026-10-30.

#One status on the wire

The deprecated 0-100 score is removed (there were no external integrations reading it yet).

• Removed: score and insurable from scans, evaluations, the site's compliance block and compliance plans; score_before / score_after from law-update site impacts; result.score from test runs; score from the public scan report. Read the status label instead: compliance.status / compliance.label.
• Scans gain compliance (status, label) once the scan's evaluation exists (null before).
• Webhooks: site.compliance_changed (data.object is the site with its current compliance.status and compliance.label) replaces site.score_changed, which is no longer sent. plan.updated's previous_attributes carries the previous status only.
• verifyTask with html, email or Stripe params: precheck.checks lists each pre-checked check (check_id, status, one-line reason, fix when it does not pass).
• Notice schedule: a yearly terms reminder that applies to a plan of a year or longer is listed (or named in not_required), and a price-change notice without price_change is named in not_required, so the schedule's email kinds match the compliance plan's email tasks.

#Newest Checkout Session and Payment Link trials

Backwards-compatible additions; nothing renamed or removed.

• Compliance plan, stripe_checkout_params: sessions are judged newest first by created, one per set of prices. The task's why and the verifyTask note name the judged session (cs_… (created YYYY-MM-DD)). Sessions a Payment Link created are judged as that Payment Link, not as Checkout Session parameters.
• Per-plan offers read a Payment Link's subscription_data.trial_period_days for the price it sells, so plan offer blocks, Notices trial timing and test runs carry the trial.
• Test runs: subscription_created events carry the subscription's actual trial end, and the mirrored Checkout Session is the newest one.
• Checkbox Elements 1.4.2 (no behaviour change). 1.4.1 and earlier stay available.

#Per-plan fixes, Stripe re-read and Notices expectations

Backwards-compatible additions; nothing renamed or removed.

• Compliance plan, sign-up task: with two or more plans, change.edits holds one insert_before per plan button, each with that plan's price, interval and trial. engine_verified is false for per-plan patches (only the resolved plan's text is engine-verified until the page is seen live).
• stripe_checkout_params: engine-corrected params keep the line_items Price id and subscription_data.trial_period_days. With several failing sessions, change.content is still the first one's params; the explanation lists the others. Sign-up checks open only on Stripe Checkout pages count under this task. Stripe-hosted styling and placement are a note, never a fix.
• verifyTask re-reads Stripe (rate-limited) before judging a Stripe-dependent task. The verification's precheck.note says what was re-read; when there was no other pre-check, precheck.source is billing_sync with verdict needs_review (it only carries the note: the re-evaluation decides). observed.billing_refresh lists the re-reads.
• The plan's one-click updateNoticeSettings config adds cancel_url and policy (confirm: true) when Notices settings do not hold them yet.
• MCP check_stripe_checkout_session: the description says Stripe-hosted conspicuousness is a note in the plan.
• Improve: SUGGESTIONS_VERSION 2026.11.03.2.
• Descriptions across the OpenAPI document use neutral wording ("a requirement is clearly not met" instead of "a clear violation"). Field names, including violations, are unchanged.

#One status, one to-do list

Backwards-compatible; one field deprecated.

• The 0-100 score (site compliance.score, evaluations, scans, compliance plans, setup sessions) is deprecated. It stays populated for existing integrations, but no Checkbox surface (dashboard, emails, Slack, MCP, CLI, Stripe App) shows it any more. Read the site's one status instead: compliance.status / compliance.label (Compliant, Needs a fix, Not set up yet, Not checked yet, Your call, counted in tasks).
• The compliance plan is the only to-do list: its open required tasks, in plan order, are what the dashboard, emails, MCP get_site_status / get_compliance_plan and the CLI list. Setup sessions gain compliance.todo (task id, key, title, status, label); compliance.failing, compliance.needs_review and compliance.top_findings are deprecated (per-check evidence, not the to-do list).
• MCP get_site_status returns data.todo (the plan's open tasks) instead of top_findings; its headline is the status label, without a score.
• The compliance plan's stripe_checkout_params task follows the rules engine on Stripe Checkout: with no registered Checkout config, it judges the recent subscription Checkout Sessions read from Stripe (consent_collection, custom_text, line items) instead of asking you to register them. verifyTask on that task checks those sessions too when the request carries no params and none are registered.
• checkNoticeSchedule / notice timing: a trial-ending reminder is never scheduled before the trial started. The send day is picked on the law's window, then pulled inside the trial when the trial is shorter.
• Sign-up checks: consent is judged per form (a second plan's form gated by its own required box is not a bypass); Stripe's placement and styling of custom text on Stripe-hosted pages is "Looks compliant with a note" (hidden text still fails); a trial is only expected on the plan that has one.
• Checkbox Elements 1.4.1: rebuilt on the shared per-plan offer model; no behaviour change. 1.4.0 stays served unchanged.

#Structured reviews

Backwards-compatible additions.

• POST /v1/feedback (createFeedback) takes type: "review" with score (0-10), liked, disliked, wrong_verdicts (each check id: reason), would_keep_using and stack; message is optional for reviews. A review describes Checkbox the product: no site or request id is attached and URLs are removed. Free text in all feedback is redacted (secrets and API keys, card numbers, email addresses become [redacted]); the response gains redacted.
• POST /v1/sites/:site/review_prompt (claimReviewPrompt): the one-time review prompt for a compliant site (show is true once per site). The MCP tools get_compliance_plan and verify_task call it and add the hint; send_feedback accepts the review fields. Agents ask the human once and never send a review without a yes.

#Retention settings and legal hold

Backwards-compatible additions.

• Account and site objects gain retention (good_practice_years, problem_history_days; sites also inherited) and legal_hold (active, scope: site or account, set, reason). Good-practice records are kept 7 years by default (1-10); problem history is deleted 30 days after a problem is resolved by default (7-730 days), keeping only counts. Open problems are never deleted.
• updateAccount and updateSite take retention (on a site, null returns a value to the account default) and legal_hold: { active, reason? }. Both need an admin key. Problem history also shows how fast you fixed things; keep it longer if you want that record.
• New error code legal_hold_active (409): shortening retention (including updateReceiptSettings retention_days) or erasing receipts while a legal hold covers the account or site.
• Evidence exports list records deleted under retention settings as redacted: { at, reason } with file: null; verify.mjs checks their chain links and reports them. Not in the MCP catalog (the tool list is at its size budget); agents can use call_api.

#Stripe checkouts, several plans, cancel gaps

Backwards-compatible additions.

• POST /v1/sites/:site/billing/resync (resyncBilling): re-reads the site's billing-platform settings and re-evaluates. Answers billing_sync with the queued platforms; 409 resource_conflict (next_action connect_billing) when none is connected. Not in the MCP catalog yet; agents can use call_api.
• Sites: facts.checkout_type (own_page, stripe_checkout, payment_link): where shoppers pay.
• Roll-ups (compliance on sites, evaluations and plans) gain checkouts: one verdict per plan / checkout (name, kind, plan, status, label, open), present when a site has two or more checkouts or one on Stripe. Statuses include not_set_up and not_checked. Evaluations of the current site now apply the site's decisions, like the site object.
• /v1/checks/disclosure and the other plan terms take intro_price / intro_amount (below the recurring price) and intro_periods; Elements 1.4.0 takes intro-amount.
• Suggestions: before.source (your_copy or example); account_url and sells_goods parameters.
• Compliance plan summary text now starts with the site status label; parse compliance instead of the text.
• Notices preview: priceProblem when the stated amount contradicts the Stripe charge (the send is refused).

#SDKs 0.1.1

• @checkbox-site/node, @checkbox-site/mcp and checkbox-site (Python) 0.1.1, regenerated from the current spec.
• Suggestions: verification.compliance_status and verification.compliance_label (the after-example's status roll-up, compliant for every offered suggestion) and surfaces[].held_label ("Needs a fix" while a failing check holds the surface). Backwards-compatible additions.
• Internal fields are marked internal and left out of the published spec and SDK types; responses still carry them, so nothing breaks for existing callers.

#Status labels and protection levels

Backwards-compatible additions. Machine verdicts (status: pass / fail / needs_review / not_applicable) and verdict are unchanged.

• Every check verdict (/v1/checks/*) and every finding gains compliance_status (needs_fix, pending_live_check, verified_live, your_call, compliant, not_applicable) and compliance (label, reason, tier, the one fix, a note, the pending_live_check {what, completes, action, due} or the question {text, recommended, why}). Check results, evaluations (compliance), sites (compliance.status, compliance.label, compliance.rollup) and compliance plans (compliance) gain a roll-up: needs_fix > your_call > compliant, where pending live checks count as compliant ("Compliant · 2 live checks pending"). Mapping: Checks and verdicts.
• Tasks gain status pending_live_check (counts as compliant, never blocks the plan), tier (required, recommended, extra) and compliance_status; plans gain protection_level, groups and counts.pending_live_check. A plan is compliant when every required task is done or only waits for a live check.
• Sites gain protection_level (minimum, balanced — the default — or maximum), settable on create / update. maximum adds two optional extra tasks; minimum hides recommended ones.
• SDK types regenerated; MCP update_site takes protection_level, and tool headlines use the labels.
• Elements 1.3.0: appearance="line" (default — one semibold line in the page's own size and colours) or "box".

#Compliant conversion suggestions

Backwards-compatible additions.

• GET /v1/sites/{site}/suggestions (listSiteSuggestions, ?surfaces=) and stateless POST /v1/suggestions (suggestImprovements; the same inputs as /v1/checks/* plus cancellation_flow and other_plans): new object suggestion_report (sugr_…, not stored) with suggestions[] (before / after, apply, preconditions, guardrails, verification), withheld[] and per-surface status. Scope checks:read.
• The compliance plan gains optional_improvements.conversion_suggestions, a pointer that is never a task and never changes status, score or counts.
• SDKs: checkbox.suggestions.forSite / generate (Python: for_site, generate). MCP tool suggest_improvements. Guide: Compliant conversion suggestions.

#Required emails you send

Backwards-compatible additions.

• GET /v1/notices/due (listDueNotices), GET /v1/notices/{notice} (retrieveDueNotice), POST /v1/notices/{notice}/sent (markNoticeSent) and POST /v1/notices/{notice}/missed (markNoticeMissed): the emails a merchant owes each subscriber (required true for legally required ones, false for the recommended cancellation confirmation), with the window, the recommended send date, the rendered email, the subscriber's name and masked address and the notice's own bcc address (<key>+<kind>.<token>@…); new object due_notice (ntd_…). Live keys see live subscribers' notices, test keys test-mode ones. markNoticeSent refuses a send before window_start and a sent_at from before an overdue notice became overdue.
• GET /v1/notices/templates (listNoticeTemplates) and POST /v1/notices/templates/check (checkNoticeTemplate).
• New event types notice.due (on the notice's send_at) and notice.overdue.
• notice_settings gains mode (merchant, the default for new sites, or checkbox) and bcc. Turning on an enabled_kinds notice without mode switches the site to checkbox, as before.
• SDKs: checkbox.notices.listDue / retrieve / markSent / markMissed / listTemplates / checkTemplate (Python: list_due, mark_sent, mark_missed, …). MCP tools list_due_notices, mark_notice_sent (missed: true), get_notice_templates.
• A required notice overdue without proof makes its check fail (confirmation.email.sent, reminder.*) and adds the computed plan task send_overdue_notices; overdue notices older than 90 days, test-mode subscribers and recommended notices never do.

#Pilot fixes

Backwards-compatible additions and fixes.

• New endpoint POST /v1/sites/{site}/integrations (connectBillingPlatform): connect Stripe, Recharge or Shopify with read-only credentials, in test mode too. The response carries a warning when the key's mode does not match the site.
• createSite / updateSite take terms_url and account_url; test_account.reset_url re-activates the test subscription before each cancellation test.
• verifyTask takes recheck: true. A task verification whose checks are still needs_review is failed with next_action.type = needs_review (it was passed).
• updateTask takes status: not_applicable (with a reason): the task closes as no_longer_applicable.
• updateNoticeSettings reports every missing prerequisite at once, with next_action.
• Elements 1.2.0: receipts record a bordered disclosure as set_off: true.
• listReceipts?customer_reference= also finds receipts by the reference attached with updateConsent.

#Feedback and public preview

Backwards-compatible additions.

• New endpoint POST /v1/feedback (createFeedback, any secret or restricted key, test or live) and MCP tool send_feedback: report a problem or a missing feature with context (site, request id, tool). 20 per key per hour.
• New crawler: the public preview (CheckboxPreview/1.0) takes one look at a newly added website's public pages, at most once per domain per day, before the domain is verified.

#Consent receipts

Backwards-compatible additions.

• New resource: consent receipts — createReceiptToken, createReceipt, listReceipts, retrieveReceipt, renderReceipt, verifyReceipt, exportReceipt, eraseReceipts, retrieveReceiptSettings, updateReceiptSettings; event receipt.created; error code receipts_disabled; scope receipts; MCP tools list_receipts and get_receipt.
• Receipts are off until you turn them on (updateReceiptSettings, after updating your privacy policy). Then Checkbox Elements 1.1.0 records a receipt with each consent (consent.receipt), and the snippet records receipts with data-receipts="1" and data-publishable-key.
• Stripe-hosted Checkout and Payment Links get receipts reconstructed from Stripe's record of the session.
• Compliance plans recommend "Turn on consent receipts" (low priority, never blocking) until a site records one.

#2026-10-31

Backwards-compatible additions and fixes from the first agent usability test and security review.

• Every next_action that names an operation_id also names its mcp_tool. New MCP tool update_site; setup_checkbox applies the facts and runs the first checks in the call that receives the keys.
• Plans: blocked_on, closed_reason, coverage; change.type: "needs_facts" instead of patches with placeholders; change.operation_id / endpoint for config changes; a stripe_checkout_params task from registered Checkout params; a notice sent outside its window is an agent task, not a human question; answers that attest a legal fact need the human's confirmation (ask_human_to_confirm).
• Setup sessions: merchant_name; test keys only see sessions created in test mode. The summary email goes out when the setup is finished (every check passes, or completeSetupSession), not right after setup starts.
• Emails: charge_notice kind in checkEmail / verifyTask; trial_ending accepted as an alias; unresolved placeholders in a checked email are reported (unresolved_placeholders); inbound emails honour a +kind plus-address or the X-Checkbox-Kind header.
• Consents: browser-claimed references are client_reference; customer_reference is set by secret keys only.
• Test mode only scans, monitors, fetches and test-runs local hosts and verified domains (plus a small daily scan budget for others): new error codes test_mode_domain_unverified, test_mode_scan_budget_exhausted.
• CLI: checkbox answer; checkbox init --merchant-name, --plan, --account-url, and facts are remembered across a resumed login.
• Every website Checkbox visits must be verified, in live mode too and per domain (details): new error code domain_not_verified; site objects carry monitoring.held_for_domain_verification and monitoring.verify_domains; plans start with a verify_domain task (verifyTask checks the DNS record / file); test runs can fail with domain_not_verified. Test mode adds a deployment-wide daily budget for scans of unverified domains.

#Later the same day: scan gate closed, one-click MCP

• Scan gate closed in test mode. Test mode no longer gives a daily allowance of scans of domains you have not verified: they are refused at once with 403 test_mode_domain_unverified and next_action.type: "verify_domain". test_mode_scan_budget_exhausted is no longer returned (it stays in the error catalog for older clients). Policy and homepage fetches follow the same rule.
• Redirects are followed only within verified websites (page fetch, policy fetch, and the scanner's browser, which also does not open other websites by navigation). Hosted checkout pages are reached by clicking through from your page; as a direct checkout / login URL they need a connected billing account.
• /.well-known/checkbox-verify.txt must be on https://<domain>/ (default port; an apex redirect to the same file on www. is followed).
• Setup sessions of a site whose domain is not verified start with a domain step and next_action.type: "verify_domain"; verifySite answers next_action.type: "verify_domain" instead of "first check complete"; verifyTask with html answers at once with next_action.type: "deploy_and_reverify".
• Domain verification of a localhost site: no DNS record, the file URL on the site's own origin, and next_action.type: "local_site".
• MCP: connect claude.ai, Claude Desktop, Claude Code or Cursor with one approval (OAuth); see MCP.

#2026-10-30

The first public version of the API.

• API v1 at https://app.checkbox.site/v1: secret, restricted and publishable keys; an isolated test mode for every account; live mode by domain verification; prefixed ids, cursor pagination, Idempotency-Key, dated versions, expand[], errors with stable codes and next_action. OpenAPI 3.1 at /v1/openapi.json.
• Agent setup: checkbox init with device-authorization login (one browser approval), setup sessions, Terms and policy checks.
• Preflight checks for disclosure text, Stripe Checkout Sessions and Payment Links, lifecycle emails, checkout HTML and notice schedules; also offline in the CLI.
• Compliance plans: ordered tasks with exact changes, verification and human questions.
• Test runs: synthetic subscriptions in Stripe test mode with test clocks.
• Checkbox Elements: the <checkbox-disclosure> web component and consent records.
• Webhooks for findings, scores, scans, plans, verifications, test runs, consents, certificates, notices and law changes.
• MCP server at https://app.checkbox.site/mcp; Node and Python SDKs (pre-release).
• Free to start: no plan limits on compliance features; fair-use limits apply.

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.