{ "openapi": "3.1.0", "info": { "title": "Checkbox API", "version": "2026-10-30", "description": "Checkbox is compliance infrastructure for subscription businesses: it checks a sign-up flow, the\nacknowledgment and reminder emails and the cancellation flow against automatic-renewal laws (ROSCA, California\nBus. & Prof. Code § 17600 et seq., New York GBL § 527-a and the other state laws), keeps signed evidence, and tells you\nexactly what to change.\n\n**Getting started (humans and AI agents):** call `createDeviceAuthorization` (the human approves once in a browser;\n`createDeviceToken` then returns test keys), connect the remote MCP server at `https://app.checkbox.site/mcp` (tool\n`setup_checkbox`), or create a test key in the dashboard, and call the API with `Authorization: Bearer ck_test_…`. Test keys act on an isolated sandbox and never\nneed activation. Live keys (`ck_live_…`) need an activated account: verify the domain of one of your sites.\n\n**Conventions:** JSON in and out, snake_case, prefixed ids (`site_…`), unix-second timestamps, cursor pagination\n(`limit`, `starting_after`, `ending_before`), `Idempotency-Key` on every POST, `Checkbox-Version` (date) header,\n`expand[]`. Errors are `{ \"error\": { \"type\", \"code\", \"message\", \"param\", \"doc_url\", \"request_id\", \"next_action\" } }`;\n`next_action` tells an agent what to call next. Webhooks are signed with `Checkbox-Signature: t=…,v1=…`\n(HMAC-SHA256 of `\"{t}.{raw body}\"` with the endpoint secret).\n\nFree to use: no plan limits on compliance features; fair-use limits apply (25 sites per account by default, per-key rate\nlimits). A compliance warranty for compliant merchants is coming (waitlist only; Checkbox does not provide insurance\ncoverage today).", "contact": { "name": "Checkbox", "url": "https://checkbox.site", "email": "support@checkbox.site" }, "termsOfService": "https://checkbox.site/terms" }, "servers": [ { "url": "https://app.checkbox.site", "description": "Checkbox API (test and live mode are chosen by the key)" } ], "tags": [ { "name": "Agent setup", "description": "One-call onboarding for AI coding agents: the setup_checkbox MCP tool (or the `checkbox init` CLI) signs the human in with one browser approval (device authorization), gets test-mode keys, and drives a setup session (snippet, site, Terms and policies, first checks, Stripe test subscription) until next_action is \"done\"." }, { "name": "Account", "description": "The account behind the API key: mode, live-mode activation, limits and the next step." }, { "name": "Sites", "description": "The subscription businesses Checkbox monitors, how to install the snippet, and domain verification (which activates live mode)." }, { "name": "Scans", "description": "Synthetic-shopper runs: Checkbox visits the checkout from each state and device, completes a sign-up when configured, receives the emails and tries to cancel online." }, { "name": "Evaluations", "description": "Compliance verdicts: score 0-100 and the insurable flag, with the checks that block insurability." }, { "name": "Findings", "description": "The latest result of each legal check for a site, with citations, evidence references and remediation." }, { "name": "Compliance plans", "description": "The agent-to-agent fix loop: an ordered, machine-readable plan of changes (requirement + citation, where, the exact patch / copy / Stripe params, how to verify), verification of each change, and questions for the human where a machine cannot decide." }, { "name": "Fixes", "description": "Engine-verified, platform-specific fixes for failing findings: Stripe Checkout code, Payment Link updates, Shopify blocks, snippet disclosures and the hosted cancellation page." }, { "name": "Evidence", "description": "The tamper-evident evidence vault behind every finding: screenshots, HTML, emails, platform configuration, evaluations." }, { "name": "Certificates", "description": "Signed monitoring certificates with a public verification page and trust badge. Not insurance." }, { "name": "Notices", "description": "Checkbox sends the legally required acknowledgment, trial-ending, renewal, yearly-terms and price-change emails for the merchant, timed from the legal catalog." }, { "name": "Law updates", "description": "Changes in automatic-renewal law that Checkbox applies, with their effect on your sites. Subscribe to the law.changed webhook to hear about them." }, { "name": "Checks", "description": "Preflight compliance checks (“check before you ship”) of disclosure text, Stripe params, lifecycle emails and checkout HTML — stateless, for AI coding agents and CI." }, { "name": "Elements", "description": "Checkbox Elements: the drop-in web component (and React wrapper) that shows the locked automatic-renewal disclosure above the pay button with an unchecked consent checkbox, and the consent records it creates." }, { "name": "Test runs", "description": "Synthetic test subscriptions (\"CMS preview\" of your subscription lifecycle): Checkbox subscribes a test customer in your billing platform's TEST mode, receives your emails at its own inbox, fast-forwards a Stripe test clock through trial end and renewal, cancels online, and reports every step with evidence, check results and fixes. Nothing is charged." }, { "name": "Webhook endpoints", "description": "Endpoints that receive signed events. Verify Checkbox-Signature with the endpoint secret (HMAC-SHA256 of \"{t}.{raw body}\", 5-minute tolerance). Failed deliveries are retried with backoff for about three days." }, { "name": "Events", "description": "Things that happened in the account (also delivered to webhook endpoints). Kept for 30 days." }, { "name": "Webhooks", "description": "Events Checkbox POSTs to your webhook endpoints." } ], "externalDocs": { "description": "Checkbox API documentation", "url": "https://checkbox.site/docs/api" }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Secret key (ck_test_… / ck_live_…), restricted key (rk_…) or legacy organization key (sk_live_…)." }, "basicAuth": { "type": "http", "scheme": "basic", "description": "HTTP Basic with the secret key as the username and an empty password (curl -u ck_test_…:)." } }, "schemas": { "NextAction": { "type": "object", "properties": { "type": { "type": "string", "description": "Stable machine-readable action type, e.g. \"verify_domain\", \"create_site\", \"wait\".", "example": "verify_domain" }, "message": { "type": "string", "description": "One sentence telling the caller what to do next.", "example": "Verify your site domain to turn on live mode." }, "operation_id": { "type": "string", "description": "operationId of the API call to make next (also the SDK method name).", "example": "createDomainVerification" }, "mcp_tool": { "type": "string", "description": "The MCP tool that performs operation_id on the Checkbox MCP server (`call_api` when there is no dedicated tool).", "example": "call_api" }, "url": { "type": "string", "description": "Documentation or dashboard URL for the step, when there is one.", "example": "https://checkbox.site/docs/api/activation" } }, "required": [ "type", "message" ], "description": "What the caller (often an AI agent) should do next." }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "rate_limit_error", "idempotency_error", "api_error" ], "description": "Category of the error.", "example": "invalid_request_error" }, "code": { "type": "string", "description": "Stable error code (see the error code list in the docs). Never changes meaning.", "example": "resource_missing" }, "message": { "type": "string", "description": "Human- and LLM-readable explanation.", "example": "No such site: site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "param": { "type": "string", "description": "The parameter the error relates to, when there is one.", "example": "site" }, "doc_url": { "type": "string", "description": "Link to the documentation of this error code.", "example": "https://checkbox.site/docs/api/errors#resource_missing" }, "request_id": { "type": "string", "description": "Id of the request (also in the Request-Id header). Quote it to support.", "example": "req_9f1c2e7b4d4e0f9a8b7c6d5e4f3a2b3c" }, "next_action": { "$ref": "#/components/schemas/NextAction" } }, "required": [ "type", "code", "message", "doc_url", "request_id" ], "description": "Error details.", "example": { "type": "invalid_request_error", "code": "resource_missing", "message": "No such site: site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "param": "site", "doc_url": "https://checkbox.site/docs/api/errors#resource_missing", "request_id": "req_9f1c2e7b4d4e0f9a8b7c6d5e4f3a2b3c", "next_action": { "type": "verify_domain", "message": "Verify your site domain to turn on live mode.", "operation_id": "createDomainVerification", "mcp_tool": "call_api", "url": "https://checkbox.site/docs/api/activation" } } } }, "required": [ "error" ], "description": "Every non-2xx response has this shape." }, "SetupNextAction": { "type": "object", "properties": { "type": { "type": "string", "description": "Stable action type: install_snippet, set_site_url, deploy_and_verify, register_policies, fix_policy_url, verify, wait, store_stripe_test_key, register_checkout_config, start_test_run, wait_for_test_run, fix_test_run, apply_compliance_plan, review_plan, verify_domain, complete_setup, done.", "example": "install_snippet" }, "message": { "type": "string", "description": "One or two sentences telling the agent exactly what to do.", "example": "Add to the of every page, then report snippet_installed_in." }, "operation_id": { "type": "string", "description": "The API operation (SDK method) that performs or checks the step.", "example": "updateSetupSession" }, "mcp_tool": { "type": "string", "description": "The MCP tool that performs operation_id (`call_api` when there is no dedicated tool).", "example": "update_setup" }, "command": { "type": "string", "description": "The equivalent `checkbox` CLI command, when there is one.", "example": "checkbox init --verify --json" }, "url": { "type": "string", "description": "Documentation or dashboard URL for the step.", "example": "https://dashboard.stripe.com/test/apikeys/create" } }, "required": [ "type", "message" ], "description": "The single next thing the agent should do." }, "DeviceAuthorization": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "device_authorization" ], "description": "String representing the object's type. Always \"device_authorization\".", "example": "device_authorization" }, "device_code": { "type": "string", "description": "Secret code the CLI polls with (keep it private).", "example": "cbdev_Q2hlY2tib3g…" }, "user_code": { "type": "string", "description": "Code the human sees and confirms in the browser.", "example": "BKRF-QXTP" }, "verification_uri": { "type": "string", "description": "Page the human opens.", "example": "https://app.checkbox.site/device" }, "verification_uri_complete": { "type": "string", "description": "Same page with the code filled in: open this.", "example": "https://app.checkbox.site/device?code=BKRF-QXTP" }, "expires_in": { "type": "integer", "description": "Seconds until the codes expire.", "example": 900 }, "interval": { "type": "integer", "description": "Seconds to wait between createDeviceToken polls.", "example": 5 }, "next_action": { "$ref": "#/components/schemas/SetupNextAction" } }, "required": [ "object", "device_code", "user_code", "verification_uri", "verification_uri_complete", "expires_in", "interval", "next_action" ], "description": "A pending device login (RFC 8628 style)." }, "SetupClient": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 60, "description": "Client program.", "example": "checkbox-cli" }, "version": { "type": "string", "maxLength": 40, "description": "Client version.", "example": "0.1.0" }, "agent": { "type": "string", "maxLength": 60, "description": "The AI agent driving the client, when known (shown to the human).", "example": "Claude Code" }, "os": { "type": "string", "maxLength": 40, "description": "Operating system.", "example": "darwin" } }, "description": "Who is setting up Checkbox." }, "DeviceAuthorizationParams": { "type": "object", "properties": { "client": { "$ref": "#/components/schemas/SetupClient" }, "site_url": { "type": "string", "maxLength": 2000, "format": "uri", "description": "Site URL detected in the project (shown on the approval screen; the test-mode site is created for it).", "example": "https://acme.com" }, "project_name": { "type": "string", "maxLength": 200, "description": "Project name.", "example": "acme-web" }, "framework": { "type": "string", "maxLength": 60, "description": "Detected framework.", "example": "nextjs-app" }, "package_manager": { "type": "string", "maxLength": 20, "description": "Package manager.", "example": "pnpm" }, "billing_platform": { "type": "string", "maxLength": 30, "description": "Detected billing platform.", "example": "stripe" }, "live": { "type": "boolean", "description": "Also ask for live-mode keys (live mode activates after domain verification).", "example": false }, "stripe_test_key_hint": { "type": "string", "maxLength": 24, "pattern": "^(sk|rk)_test_…[A-Za-z0-9]{4}$", "description": "A HINT of the Stripe TEST key found in the project (\"sk_test_…a1b2\" — never the key). The human is asked once whether Checkbox may use it for synthetic test subscriptions.", "example": "sk_test_…a1b2" } }, "additionalProperties": false, "description": "What the CLI is about to set up (display only)." }, "DeviceToken": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "device_token" ], "description": "String representing the object's type. Always \"device_token\".", "example": "device_token" }, "token_type": { "type": "string", "enum": [ "bearer" ], "description": "Always \"bearer\".", "example": "bearer" }, "secret_key": { "type": "string", "description": "Test-mode secret key (ck_test_…), shown once. Store it in CHECKBOX_SECRET_KEY (server side only; never commit it).", "example": "ck_test_51Hx…" }, "publishable_key": { "type": "string", "description": "Test-mode publishable key (pk_test_…) for the browser.", "example": "pk_test_51Hx…" }, "live_secret_key": { "type": [ "string", "null" ], "description": "Live-mode secret key when the human approved live keys (works for live routes after domain verification).", "example": null }, "live_publishable_key": { "type": [ "string", "null" ], "description": "Live-mode publishable key.", "example": null }, "account": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the account (acct_…).", "example": "acct_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "name": { "type": "string", "description": "Account (organization) name.", "example": "acme.com" }, "email": { "type": [ "string", "null" ], "description": "Email of the person who approved.", "example": "founder@acme.com" } }, "required": [ "id", "name", "email" ], "description": "The account the keys belong to.", "example": { "id": "acct_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "name": "acme.com", "email": "founder@acme.com" } }, "setup_session": { "type": "string", "description": "The setup session to continue with (retrieveSetupSession / updateSetupSession).", "example": "setup_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "site": { "type": [ "string", "null" ], "description": "The test-mode site created for site_url, if any.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "consents": { "type": "object", "properties": { "stripe_test_key": { "type": "boolean", "description": "The human allowed Checkbox to use the project's Stripe TEST key (send it with createTestCredential).", "example": true }, "live_keys": { "type": "boolean", "description": "Live keys were issued.", "example": false } }, "required": [ "stripe_test_key", "live_keys" ], "description": "What the human approved.", "example": { "stripe_test_key": true, "live_keys": false } }, "next_action": { "$ref": "#/components/schemas/SetupNextAction" } }, "required": [ "object", "token_type", "secret_key", "publishable_key", "live_secret_key", "live_publishable_key", "account", "setup_session", "site", "consents", "next_action" ], "description": "Keys issued after the human approved the device login. Returned exactly once." }, "SetupPlan": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200, "description": "Plan name.", "example": "Pro" }, "amount": { "type": "integer", "minimum": 0, "description": "Recurring charge in minor units.", "example": 1900 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "ISO currency code.", "example": "usd" }, "interval": { "type": "string", "enum": [ "day", "week", "month", "year" ], "description": "Billing interval.", "example": "month" }, "interval_count": { "type": "integer", "minimum": 1, "maximum": 36, "description": "Intervals per billing period.", "example": 1 }, "trial_days": { "type": "integer", "minimum": 0, "maximum": 730, "description": "Free-trial days (0 = none).", "example": 14 } }, "description": "A subscription plan as the merchant sells it." }, "SetupStep": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "account", "site", "snippet", "policies", "checks", "lifecycle_test", "fixes", "domain", "owner_notified" ], "description": "Stable step key.", "example": "snippet" }, "title": { "type": "string", "description": "Human-readable title.", "example": "Snippet installed" }, "status": { "type": "string", "enum": [ "done", "pending", "action_required", "skipped", "failed" ], "description": "done; pending (waiting on Checkbox or a deploy); action_required (the agent must act: see next_action); skipped; failed.", "example": "action_required" }, "summary": { "type": "string", "description": "What is true now, in one sentence.", "example": "Snippet not installed yet" }, "next_action": { "allOf": [ { "$ref": "#/components/schemas/SetupNextAction" }, { "type": [ "object", "null" ], "description": "What to do for this step (null when nothing is needed)." } ], "example": { "type": "install_snippet", "message": "Add to the of every page, then report snippet_installed_in.", "operation_id": "updateSetupSession", "mcp_tool": "update_setup", "command": "checkbox init --verify --json", "url": "https://dashboard.stripe.com/test/apikeys/create" } } }, "required": [ "key", "title", "status", "summary", "next_action" ], "description": "One step of the setup checklist." }, "SetupSession": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the setup session (setup_…).", "example": "setup_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "setup_session" ], "description": "String representing the object's type. Always \"setup_session\".", "example": "setup_session" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "status": { "type": "string", "enum": [ "open", "completed", "canceled" ], "description": "open while the agent works; completed after completeSetupSession (checks keep running).", "example": "open" }, "created": { "type": "integer", "description": "When the human approved the setup. Unix timestamp in seconds.", "example": 1793318400 }, "updated": { "type": "integer", "description": "Last change. Unix timestamp in seconds.", "example": 1793318400 }, "account": { "type": "string", "description": "The Checkbox account.", "example": "acct_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "site": { "type": [ "string", "null" ], "description": "The test-mode site (null until a site URL is known).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "live_site": { "type": [ "string", "null" ], "description": "The live-mode site, once created.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "client": { "type": "object", "properties": { "name": { "type": [ "string", "null" ], "description": "Client program.", "example": "checkbox-cli" }, "version": { "type": [ "string", "null" ], "description": "Client version.", "example": "0.1.0" }, "agent": { "type": [ "string", "null" ], "description": "AI agent, when known.", "example": "Claude Code" } }, "required": [ "name", "version", "agent" ], "description": "Who set it up.", "example": { "name": "checkbox-cli", "version": "0.1.0", "agent": "Claude Code" } }, "project": { "type": "object", "additionalProperties": {}, "description": "Facts about the codebase the agent reported (framework, layout_file, checkout_code…).", "example": { "framework": "nextjs-app", "layout_file": "app/layout.tsx" } }, "business": { "type": "object", "properties": { "site_url": { "type": [ "string", "null" ], "description": "Site URL.", "example": "https://acme.com" }, "checkout_url": { "type": [ "string", "null" ], "description": "Checkout / pricing page.", "example": "https://acme.com/pricing" }, "account_url": { "type": [ "string", "null" ], "description": "Account page.", "example": null }, "terms_url": { "type": [ "string", "null" ], "description": "Terms of service.", "example": "https://acme.com/terms" }, "privacy_url": { "type": [ "string", "null" ], "description": "Privacy policy.", "example": "https://acme.com/privacy" }, "refund_url": { "type": [ "string", "null" ], "description": "Refund policy.", "example": null }, "cancellation_url": { "type": [ "string", "null" ], "description": "Cancellation policy.", "example": null }, "support_email": { "type": [ "string", "null" ], "description": "Support email.", "example": "support@acme.com" }, "merchant_name": { "type": [ "string", "null" ], "description": "Merchant (brand) name used in generated legal copy (the site name).", "example": "Acme" }, "billing_platform": { "type": [ "string", "null" ], "description": "Billing platform.", "example": "stripe" }, "plans": { "type": "array", "items": { "$ref": "#/components/schemas/SetupPlan" }, "description": "Plans.", "example": [] } }, "required": [ "site_url", "checkout_url", "account_url", "terms_url", "privacy_url", "refund_url", "cancellation_url", "support_email", "merchant_name", "billing_platform", "plans" ], "description": "The business as registered.", "example": { "site_url": "https://acme.com", "checkout_url": "https://acme.com/pricing", "account_url": null, "terms_url": "https://acme.com/terms", "privacy_url": "https://acme.com/privacy", "refund_url": null, "cancellation_url": null, "support_email": "support@acme.com", "merchant_name": "Acme", "billing_platform": "stripe", "plans": [] } }, "discovered": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Policy / pricing links Checkbox found in the site's HTML (terms_url, privacy_url, refund_url, cancellation_url, pricing_url, account_url).", "example": { "terms_url": "https://acme.com/terms" } }, "install": { "type": "object", "properties": { "script_tag": { "type": [ "string", "null" ], "description": "The exact tag to put in on every page.", "example": "" }, "snippet_key": { "type": [ "string", "null" ], "description": "Public snippet key of the site.", "example": "k3y9" }, "publishable_key": { "type": [ "string", "null" ], "description": "Test-mode publishable key (pk_test_…) for Checkbox Elements in the browser.", "example": "pk_test_3f9a…" }, "inbound_email": { "type": [ "string", "null" ], "description": "BCC this address on subscription emails (acknowledgment, reminders) so they are checked.", "example": "k3y9@in.checkbox.site" }, "installed_in": { "type": [ "string", "null" ], "description": "File the agent added the snippet to.", "example": "app/layout.tsx" }, "detected_on_site": { "type": [ "boolean", "null" ], "description": "Whether Checkbox saw the snippet on the live site at the last verify (null: not checked).", "example": false } }, "required": [ "script_tag", "snippet_key", "publishable_key", "inbound_email", "installed_in", "detected_on_site" ], "description": "Install details.", "example": { "script_tag": "", "snippet_key": "k3y9", "publishable_key": "pk_test_3f9a…", "inbound_email": "k3y9@in.checkbox.site", "installed_in": "app/layout.tsx", "detected_on_site": false } }, "policies": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "description": "terms, privacy, refund or cancellation.", "example": "terms" }, "url": { "type": "string", "description": "URL fetched.", "example": "https://acme.com/terms" }, "status": { "type": "string", "enum": [ "fetched", "failed" ], "description": "Fetch result.", "example": "fetched" }, "fetched": { "type": "integer", "description": "When it was fetched. Unix timestamp in seconds.", "example": 1793318400 }, "error": { "type": [ "string", "null" ], "description": "Why the fetch failed.", "example": null }, "evidence": { "type": [ "string", "null" ], "description": "Evidence record of the stored page (ev_…).", "example": "ev_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" } }, "required": [ "kind", "url", "status", "fetched", "error", "evidence" ] }, "description": "Policy documents Checkbox fetched (checked by terms.* checks).", "example": [] }, "stripe": { "type": "object", "properties": { "test_key_consent": { "type": "boolean", "description": "Whether the human allowed Checkbox to use the project's Stripe TEST key for synthetic subscriptions.", "example": true }, "test_key_hint": { "type": [ "string", "null" ], "description": "Hint of the key the CLI found (never the key).", "example": "sk_test_…a1b2" }, "test_credential_stored": { "type": "boolean", "description": "Whether a Stripe test-mode key is stored for test runs.", "example": false }, "checkout_configs": { "type": "integer", "description": "Registered Checkout Session param sets.", "example": 1 }, "restricted_key": { "type": "object", "properties": { "recommended": { "type": "boolean", "description": "true while no restricted (rk_test_) key is stored.", "example": true }, "reason": { "type": "string", "description": "Why.", "example": "Give Checkbox a restricted test key with only these permissions." }, "create_url": { "type": "string", "description": "Where to create it.", "example": "https://dashboard.stripe.com/test/apikeys/create" }, "permissions": { "type": "array", "items": { "type": "object", "properties": { "resource": { "type": "string", "description": "Stripe resource.", "example": "Test clocks" }, "access": { "type": "string", "enum": [ "read", "write" ], "description": "Access.", "example": "write" } }, "required": [ "resource", "access" ] }, "description": "Least-privilege permissions.", "example": [ { "resource": "Test clocks", "access": "write" } ] } }, "required": [ "recommended", "reason", "create_url", "permissions" ], "description": "Restricted-key recommendation.", "example": { "recommended": true, "reason": "Give Checkbox a restricted test key with only these permissions.", "create_url": "https://dashboard.stripe.com/test/apikeys/create", "permissions": [ { "resource": "Test clocks", "access": "write" } ] } } }, "required": [ "test_key_consent", "test_key_hint", "test_credential_stored", "checkout_configs", "restricted_key" ], "description": "Stripe test mode for lifecycle test runs.", "example": { "test_key_consent": true, "test_key_hint": "sk_test_…a1b2", "test_credential_stored": false, "checkout_configs": 1, "restricted_key": { "recommended": true, "reason": "Give Checkbox a restricted test key with only these permissions.", "create_url": "https://dashboard.stripe.com/test/apikeys/create", "permissions": [ { "resource": "Test clocks", "access": "write" } ] } } }, "test_run": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Unique identifier of the test run (run_…).", "example": "run_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "status": { "type": "string", "description": "queued, running, succeeded, failed or canceled.", "example": "running" }, "created": { "type": "integer", "description": "When it started. Unix timestamp in seconds.", "example": 1793318400 } }, "required": [ "id", "status", "created" ], "description": "Latest lifecycle test run of the site.", "example": { "id": "run_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "status": "running", "created": 1793318400 } }, "compliance": { "type": [ "object", "null" ], "properties": { "score": { "type": "number", "description": "0-100.", "example": 72 }, "insurable": { "type": "boolean", "description": "No critical/high failure open.", "example": false }, "evaluated": { "type": "integer", "description": "When it was evaluated. Unix timestamp in seconds.", "example": 1793318400 }, "failing": { "type": "integer", "description": "Open failing findings.", "example": 3 }, "needs_review": { "type": "integer", "description": "Open needs-review findings.", "example": 2 }, "top_findings": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the finding (fnd_…).", "example": "fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "check_id": { "type": "string", "description": "Check id.", "example": "terms.cancellation_policy_consistent" }, "status": { "type": "string", "description": "fail or needs_review.", "example": "fail" }, "severity": { "type": "string", "description": "critical, high, medium or low.", "example": "high" }, "title": { "type": "string", "description": "What is wrong.", "example": "Terms of service do not contradict online cancellation" } }, "required": [ "id", "check_id", "status", "severity", "title" ] }, "description": "Most urgent open findings (details: retrieveFinding; ordered tasks: `checkbox plan --json`).", "example": [] } }, "required": [ "score", "insurable", "evaluated", "failing", "needs_review", "top_findings" ], "description": "Latest verdict of the test-mode site.", "example": { "score": 72, "insurable": false, "evaluated": 1793318400, "failing": 3, "needs_review": 2, "top_findings": [] } }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/SetupStep" }, "description": "The setup checklist, in order.", "example": [] }, "next_action": { "$ref": "#/components/schemas/SetupNextAction" }, "owner_notified": { "type": "boolean", "description": "Whether the human got the summary email.", "example": false }, "owner_email": { "type": [ "string", "null" ], "enum": [ "sent", "not_configured" ], "description": "The summary email: sent, or not_configured when this deployment has no SMTP (null before completeSetupSession).", "example": "sent" }, "review_url": { "type": "string", "description": "Dashboard page with the setup timeline (for the human).", "example": "https://app.checkbox.site/setup/3f9a1c2e-7b4d-4e0f-9a8b-7c6d5e4f3a2b" } }, "required": [ "id", "object", "livemode", "status", "created", "updated", "account", "site", "live_site", "client", "project", "business", "discovered", "install", "policies", "stripe", "test_run", "compliance", "steps", "next_action", "owner_notified", "owner_email", "review_url" ], "description": "What an AI coding agent set up for a project, as a checklist with one next_action. Loop: apply next_action, call verifySetupSession, repeat until next_action.type is \"done\"." }, "SetupCodeRef": { "type": "object", "properties": { "file": { "type": "string", "maxLength": 500, "description": "Path relative to the project root.", "example": "app/api/checkout/route.ts" }, "line": { "type": "integer", "minimum": 1, "description": "1-based line number.", "example": 12 }, "kind": { "type": "string", "maxLength": 60, "description": "What was found: stripe_checkout_session, stripe_payment_link, stripe_pricing_table, stripe_elements, subscribe_button, shopify_checkout…", "example": "stripe_checkout_session" }, "snippet": { "type": "string", "maxLength": 500, "description": "The matching source line (trimmed).", "example": "const session = await stripe.checkout.sessions.create({" } }, "required": [ "file", "kind" ], "description": "A place in the builder's code relevant to compliance." }, "SetupSessionUpdate": { "type": "object", "properties": { "site_url": { "type": "string", "maxLength": 2000, "format": "uri", "description": "Public URL of the site (production, or a preview deployment).", "example": "https://acme.com" }, "checkout_url": { "type": "string", "maxLength": 2000, "format": "uri", "description": "Page where customers subscribe (pricing page or checkout).", "example": "https://acme.com/pricing" }, "account_url": { "type": "string", "maxLength": 2000, "format": "uri", "description": "Account page where subscribers manage / cancel.", "example": "https://acme.com/account" }, "terms_url": { "type": "string", "maxLength": 2000, "format": "uri", "description": "Terms of service page. Checkbox fetches and checks it.", "example": "https://acme.com/terms" }, "privacy_url": { "type": "string", "maxLength": 2000, "format": "uri", "description": "Privacy policy page.", "example": "https://acme.com/privacy" }, "refund_url": { "type": "string", "maxLength": 2000, "format": "uri", "description": "Refund policy page.", "example": "https://acme.com/refunds" }, "cancellation_url": { "type": "string", "maxLength": 2000, "format": "uri", "description": "Cancellation policy page (if separate from the Terms).", "example": "https://acme.com/cancellation-policy" }, "support_email": { "type": "string", "maxLength": 320, "format": "email", "description": "Support address subscribers can write to.", "example": "support@acme.com" }, "merchant_name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The brand subscribers know (it names the seller in generated disclosures and emails). Default: the site's host name, which the plan asks you to replace.", "example": "Acme" }, "billing_platform": { "type": "string", "enum": [ "stripe", "shopify", "recharge", "chargebee", "recurly", "paddle", "woocommerce", "custom" ], "description": "Billing platform.", "example": "stripe" }, "plans": { "type": "array", "items": { "$ref": "#/components/schemas/SetupPlan" }, "maxItems": 50, "description": "Plans and prices (sets the free-trial and term facts the law depends on).", "example": [ { "name": "Pro", "amount": 1900, "currency": "usd", "interval": "month", "trial_days": 14 } ] }, "project": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200, "description": "Project name (package.json name).", "example": "acme-web" }, "framework": { "type": "string", "maxLength": 60, "description": "Detected framework: nextjs-app, nextjs-pages, remix, sveltekit, nuxt, astro, express, html, shopify-theme…", "example": "nextjs-app" }, "package_manager": { "type": "string", "maxLength": 20, "description": "npm, pnpm, yarn or bun.", "example": "pnpm" }, "root": { "type": "string", "maxLength": 500, "description": "Project root (display only).", "example": "." }, "layout_file": { "type": "string", "maxLength": 500, "description": "Root layout / template where the snippet belongs.", "example": "app/layout.tsx" }, "env_file": { "type": "string", "maxLength": 500, "description": "File the keys were written to.", "example": ".env.local" }, "public_dir": { "type": "string", "maxLength": 500, "description": "Static files directory (for /.well-known).", "example": "public" }, "checkout_code": { "type": "array", "items": { "$ref": "#/components/schemas/SetupCodeRef" }, "maxItems": 100, "description": "Where checkout sessions / payment links are created.", "example": [ { "file": "app/api/checkout/route.ts", "line": 12, "kind": "stripe_checkout_session" } ] }, "pay_buttons": { "type": "array", "items": { "$ref": "#/components/schemas/SetupCodeRef" }, "maxItems": 100, "description": "Where the subscribe / pay buttons are rendered.", "example": [ { "file": "app/pricing/page.tsx", "line": 40, "kind": "subscribe_button" } ] } }, "description": "Facts about the builder's codebase.", "example": { "name": "acme-web", "framework": "nextjs-app", "package_manager": "pnpm", "root": ".", "layout_file": "app/layout.tsx", "env_file": ".env.local", "public_dir": "public", "checkout_code": [ { "file": "app/api/checkout/route.ts", "line": 12, "kind": "stripe_checkout_session" } ], "pay_buttons": [ { "file": "app/pricing/page.tsx", "line": 40, "kind": "subscribe_button" } ] } }, "snippet_installed_in": { "type": "string", "maxLength": 500, "description": "File the snippet tag was added to.", "example": "app/layout.tsx" }, "env_written": { "type": "string", "maxLength": 500, "description": "File the API keys were written to (never committed).", "example": ".env.local" }, "live_site": { "type": "string", "maxLength": 100, "description": "Live-mode site (site_…) you created with the live key, so the checklist tracks its domain verification.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "client": { "$ref": "#/components/schemas/SetupClient" }, "refetch_policies": { "type": "boolean", "description": "Fetch the policy pages again even when their URLs did not change (after editing them).", "example": false } }, "additionalProperties": false, "description": "What the agent learned or changed." }, "SetupSessionList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "String representing the object's type. Always \"list\".", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SetupSession" }, "description": "Setup sessions, newest first.", "example": [ { "id": "setup_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "setup_session", "livemode": false, "status": "open", "created": 1793318400, "updated": 1793318400, "account": "acct_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "live_site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "client": { "name": "checkbox-cli", "version": "0.1.0", "agent": "Claude Code" }, "project": { "framework": "nextjs-app", "layout_file": "app/layout.tsx" }, "business": { "site_url": "https://acme.com", "checkout_url": "https://acme.com/pricing", "account_url": null, "terms_url": "https://acme.com/terms", "privacy_url": "https://acme.com/privacy", "refund_url": null, "cancellation_url": null, "support_email": "support@acme.com", "merchant_name": "Acme", "billing_platform": "stripe", "plans": [] }, "discovered": { "terms_url": "https://acme.com/terms" }, "install": { "script_tag": "", "snippet_key": "k3y9", "publishable_key": "pk_test_3f9a…", "inbound_email": "k3y9@in.checkbox.site", "installed_in": "app/layout.tsx", "detected_on_site": false }, "policies": [], "stripe": { "test_key_consent": true, "test_key_hint": "sk_test_…a1b2", "test_credential_stored": false, "checkout_configs": 1, "restricted_key": { "recommended": true, "reason": "Give Checkbox a restricted test key with only these permissions.", "create_url": "https://dashboard.stripe.com/test/apikeys/create", "permissions": [ { "resource": "Test clocks", "access": "write" } ] } }, "test_run": { "id": "run_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "status": "running", "created": 1793318400 }, "compliance": { "score": 72, "insurable": false, "evaluated": 1793318400, "failing": 3, "needs_review": 2, "top_findings": [] }, "steps": [], "next_action": { "type": "install_snippet", "message": "Add to the of every page, then report snippet_installed_in.", "operation_id": "updateSetupSession", "mcp_tool": "update_setup", "command": "checkbox init --verify --json", "url": "https://dashboard.stripe.com/test/apikeys/create" }, "owner_notified": false, "owner_email": "sent", "review_url": "https://app.checkbox.site/setup/3f9a1c2e-7b4d-4e0f-9a8b-7c6d5e4f3a2b" } ] }, "has_more": { "type": "boolean", "description": "Whether more items exist after this page. Pass the last id as starting_after to fetch them.", "example": false }, "url": { "type": "string", "description": "The URL of this list.", "example": "/v1/sites" } }, "required": [ "object", "data", "has_more", "url" ], "description": "A page of setup sessions, newest first." }, "SetupVerification": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "setup_verification" ], "description": "String representing the object's type. Always \"setup_verification\".", "example": "setup_verification" }, "homepage": { "type": "object", "properties": { "ok": { "type": "boolean", "description": "Whether the site loaded.", "example": true }, "snippet_detected": { "type": [ "boolean", "null" ], "description": "Whether the snippet is live.", "example": true }, "error": { "type": [ "string", "null" ], "description": "Why the site could not be loaded.", "example": null } }, "required": [ "ok", "snippet_detected", "error" ], "description": "What Checkbox saw on the site.", "example": { "ok": true, "snippet_detected": true, "error": null } }, "policies": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "description": "Policy kind.", "example": "terms" }, "ok": { "type": "boolean", "description": "Fetched.", "example": true }, "error": { "type": [ "string", "null" ], "description": "Error.", "example": null } }, "required": [ "kind", "ok", "error" ] }, "description": "Policies fetched now.", "example": [] }, "scan": { "type": "object", "properties": { "queued": { "type": "boolean", "description": "Whether a scan was queued now.", "example": true }, "scan": { "type": [ "string", "null" ], "description": "The queued scan (scan_…).", "example": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "reason": { "type": [ "string", "null" ], "description": "Why not.", "example": null } }, "required": [ "queued", "scan", "reason" ], "description": "Synthetic-shopper scan.", "example": { "queued": true, "scan": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "reason": null } }, "evaluated": { "type": "boolean", "description": "Whether compliance was re-evaluated now.", "example": true }, "setup_session": { "$ref": "#/components/schemas/SetupSession" } }, "required": [ "object", "homepage", "policies", "scan", "evaluated", "setup_session" ], "description": "Result of verifySetupSession, with the updated session." }, "Account": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the account (acct_…).", "example": "acct_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "account" ], "description": "String representing the object's type. Always \"account\".", "example": "account" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "name": { "type": "string", "description": "Organization name.", "example": "Acme Subscriptions" }, "email": { "type": [ "string", "null" ], "description": "Contact email.", "example": "ops@acme.example" }, "api_version": { "type": "string", "description": "API version the account is pinned to (default for requests without Checkbox-Version).", "example": "2026-10-30" }, "activation": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "pending", "suspended" ], "description": "active: live mode is on; pending: verify a site domain; suspended: contact support.", "example": "pending" }, "method": { "type": [ "string", "null" ], "enum": [ "domain", "staff", "grandfathered" ], "description": "How the account was activated.", "example": null }, "domain": { "type": [ "string", "null" ], "description": "The verified domain that activated it.", "example": null }, "activated_at": { "type": [ "integer", "null" ], "description": "When live mode was activated. Unix timestamp in seconds.", "example": 1793318400 } }, "required": [ "status", "method", "domain", "activated_at" ], "description": "Live-mode activation. Test mode never needs it.", "example": { "status": "pending", "method": null, "domain": null, "activated_at": 1793318400 } }, "limits": { "type": "object", "properties": { "max_sites": { "type": "integer", "description": "Fair-use limit of active sites per mode.", "example": 25 }, "sites": { "type": "integer", "description": "Active sites in this mode.", "example": 1 }, "requests_per_minute": { "type": "integer", "description": "Fair-use API rate limit per mode.", "example": 300 } }, "required": [ "max_sites", "sites", "requests_per_minute" ], "description": "Fair-use limits (everything is free; these only prevent abuse).", "example": { "max_sites": 25, "sites": 1, "requests_per_minute": 300 } }, "key": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "secret", "restricted", "publishable" ], "description": "Kind of key used for this request.", "example": "secret" }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ], "description": "Role the key acts with.", "example": "admin" }, "scopes": { "type": [ "object", "null" ], "additionalProperties": { "type": "string", "enum": [ "read", "write" ] }, "description": "Restricted keys: resource permissions.", "example": null }, "legacy": { "type": "boolean", "description": "A legacy sk_live_ organization key.", "example": false } }, "required": [ "type", "role", "scopes", "legacy" ], "description": "The key that made this request.", "example": { "type": "secret", "role": "admin", "scopes": null, "legacy": false } }, "publishable_key": { "type": "string", "description": "Publishable key (pk_…) of this mode for the browser snippet / elements.", "example": "pk_test_9fT…" }, "billing": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "free" ], "description": "Checkbox is free to use.", "example": "free" }, "warranty": { "type": "string", "enum": [ "coming_soon" ], "description": "The compliance warranty is not offered yet (waitlist only; no coverage).", "example": "coming_soon" } }, "required": [ "plan", "warranty" ], "description": "Commercial status.", "example": { "plan": "free", "warranty": "coming_soon" } }, "created": { "type": "integer", "description": "When the account was created. Unix timestamp in seconds.", "example": 1793318400 }, "next_action": { "allOf": [ { "$ref": "#/components/schemas/NextAction" }, { "type": [ "object", "null" ], "description": "What to do next; null when nothing is needed." } ], "example": { "type": "verify_domain", "message": "Verify your site domain to turn on live mode.", "operation_id": "createDomainVerification", "mcp_tool": "call_api", "url": "https://checkbox.site/docs/api/activation" } } }, "required": [ "id", "object", "livemode", "name", "email", "api_version", "activation", "limits", "key", "publishable_key", "billing", "created", "next_action" ], "description": "The Checkbox account behind the API key." }, "SiteFacts": { "type": "object", "properties": { "has_free_trial": { "type": "boolean", "description": "The offer starts with a free trial.", "example": true }, "trial_days": { "type": "integer", "minimum": 0, "maximum": 3650, "description": "Trial length in days.", "example": 14 }, "term_months": { "type": "number", "minimum": 0, "maximum": 1200, "description": "Billing term in months (12 for annual plans).", "example": 1 }, "online_signup": { "type": "boolean", "description": "Customers sign up online (enables online-cancellation rules).", "example": true }, "sells_goods": { "type": "boolean", "description": "The subscription ships physical goods.", "example": false }, "notice_channel_email": { "type": "boolean", "description": "Notices are sent by email.", "example": true }, "price_increase_consent_or_refund": { "type": "boolean", "description": "Price increases need consent or allow a refund (NY).", "example": false }, "payment_methods": { "type": "array", "items": { "type": "string", "enum": [ "card", "debit", "ach", "wallet", "other" ] }, "description": "Accepted payment methods (debit / ACH bring in Reg E).", "example": [ "card" ] } }, "description": "Business facts that decide which legal requirements apply." }, "SiteMonitoring": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Scheduled re-scans are on.", "example": true }, "interval_minutes": { "type": "integer", "description": "Re-scan interval (0 = off).", "example": 1440 }, "held_for_activation": { "type": "boolean", "description": "Monitoring waits for a verified domain: live-mode activation, or in test mode a host that is not localhost or a domain the account verified.", "example": false }, "last_scanned": { "type": [ "integer", "null" ], "description": "Last scheduled or manual scan. Unix timestamp in seconds.", "example": 1793318400 } }, "required": [ "enabled", "interval_minutes", "held_for_activation", "last_scanned" ], "description": "Scheduled monitoring." }, "SiteCompliance": { "type": [ "object", "null" ], "properties": { "score": { "type": "number", "minimum": 0, "maximum": 100, "description": "Compliance score 0-100 (one decimal place).", "example": 82 }, "insurable": { "type": "boolean", "description": "No critical/high obligation failing or unverified.", "example": false }, "evaluated": { "type": "integer", "description": "When the latest evaluation ran. Unix timestamp in seconds.", "example": 1793318400 }, "open_findings": { "type": "integer", "description": "Open findings whose latest status is fail.", "example": 2 }, "needs_review": { "type": "integer", "description": "Open findings waiting for a human look.", "example": 1 } }, "required": [ "score", "insurable", "evaluated", "open_findings", "needs_review" ], "description": "Latest verdict; null until the first evaluation." }, "SiteInstall": { "type": "object", "properties": { "script_tag": { "type": "string", "description": "Paste into the of every page (or let `checkbox init` do it).", "example": "" }, "snippet_key": { "type": "string", "description": "Public key of the snippet (also the inbound email local part).", "example": "ab12cd34ef56" }, "inbound_email": { "type": "string", "description": "BCC this address on acknowledgment and reminder emails.", "example": "ab12cd34ef56@in.checkbox.site" }, "webhook_urls": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Billing-platform webhook URLs (platform -> URL).", "example": { "stripe": "https://app.checkbox.site/webhooks/stripe/…" } } }, "required": [ "script_tag", "snippet_key", "inbound_email", "webhook_urls" ], "description": "What to install on the merchant site." }, "Scan": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the scan (scan_…).", "example": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "scan" ], "description": "String representing the object's type. Always \"scan\".", "example": "scan" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "site": { "type": "string", "description": "The scanned site.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "status": { "type": "string", "enum": [ "queued", "running", "completed", "failed" ], "description": "queued → running → completed | failed.", "example": "completed" }, "trigger": { "type": "string", "enum": [ "manual", "scheduled", "page_changed", "api" ], "description": "What started the scan.", "example": "api" }, "regions": { "type": "array", "items": { "type": "string", "enum": [ "US-FED", "US-AL", "US-AK", "US-AZ", "US-AR", "US-CA", "US-CO", "US-CT", "US-DE", "US-DC", "US-FL", "US-GA", "US-HI", "US-ID", "US-IL", "US-IN", "US-IA", "US-KS", "US-KY", "US-LA", "US-ME", "US-MD", "US-MA", "US-MI", "US-MN", "US-MS", "US-MO", "US-MT", "US-NE", "US-NV", "US-NH", "US-NJ", "US-NM", "US-NY", "US-NC", "US-ND", "US-OH", "US-OK", "US-OR", "US-PA", "US-RI", "US-SC", "US-SD", "US-TN", "US-TX", "US-UT", "US-VT", "US-VA", "US-WA", "US-WV", "US-WI", "US-WY" ] }, "description": "States the synthetic shopper visited from (empty for evaluation-only runs).", "example": [ "US-CA", "US-NY" ] }, "error": { "type": [ "string", "null" ], "description": "Why the scan failed.", "example": null }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Partial failures of a scan that still produced results.", "example": [] }, "evaluation": { "type": [ "string", "null" ], "description": "The evaluation this scan produced (null until evaluated).", "example": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "score": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "Score of that evaluation (0-100, one decimal place).", "example": 82 }, "insurable": { "type": [ "boolean", "null" ], "description": "Insurable flag of that evaluation.", "example": false }, "started": { "type": [ "integer", "null" ], "description": "When the scan started. Unix timestamp in seconds.", "example": 1793318400 }, "finished": { "type": [ "integer", "null" ], "description": "When the scan finished. Unix timestamp in seconds.", "example": 1793318400 }, "created": { "type": "integer", "description": "When the scan was queued. Unix timestamp in seconds.", "example": 1793318400 } }, "required": [ "id", "object", "livemode", "site", "status", "trigger", "regions", "error", "warnings", "evaluation", "score", "insurable", "started", "finished", "created" ], "description": "Most recent scan (only with expand[]=latest_scan)." }, "DomainVerification": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the domain verification (dv_…).", "example": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "domain_verification" ], "description": "String representing the object's type. Always \"domain_verification\".", "example": "domain_verification" }, "site": { "type": "string", "description": "The site.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "domain": { "type": [ "string", "null" ], "description": "Domain of the site URL.", "example": "acme.example" }, "status": { "type": "string", "enum": [ "not_started", "pending", "verified" ], "description": "not_started until createDomainVerification; verified once the TXT record or file was found.", "example": "pending" }, "method": { "type": [ "string", "null" ], "enum": [ "dns_txt", "well_known" ], "description": "How control was proven.", "example": null }, "verified_at": { "type": [ "integer", "null" ], "description": "When it was verified. Unix timestamp in seconds.", "example": 1793318400 }, "last_checked": { "type": [ "integer", "null" ], "description": "Last check. Unix timestamp in seconds.", "example": 1793318400 }, "last_error": { "type": [ "string", "null" ], "description": "Why the last check failed.", "example": "TXT record not found" }, "dns_record": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "enum": [ "TXT" ], "description": "Record type.", "example": "TXT" }, "name": { "type": "string", "description": "Record name.", "example": "_checkbox-verify.acme.example" }, "value": { "type": "string", "description": "Record value.", "example": "checkbox-verify=Xy…" } }, "required": [ "type", "name", "value" ], "description": "Publish this DNS record (option 1).", "example": { "type": "TXT", "name": "_checkbox-verify.acme.example", "value": "checkbox-verify=Xy…" } }, "file": { "type": [ "object", "null" ], "properties": { "url": { "type": "string", "description": "Serve the file here.", "example": "https://acme.example/.well-known/checkbox-verify.txt" }, "contents": { "type": "string", "description": "Exact file contents.", "example": "Xy…" } }, "required": [ "url", "contents" ], "description": "Or serve this file (option 2).", "example": { "url": "https://acme.example/.well-known/checkbox-verify.txt", "contents": "Xy…" } }, "scan_target_problems": { "type": "array", "items": { "type": "string" }, "description": "Configured scan URLs outside the verified domain (certificates cover only the domain).", "example": [] }, "account_activated": { "type": "boolean", "description": "Whether live mode is activated for the account.", "example": false }, "next_action": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "description": "Stable action type.", "example": "publish_dns_record" }, "message": { "type": "string", "description": "What to do next.", "example": "Publish the TXT record, then call checkDomainVerification." }, "operation_id": { "type": "string", "description": "Operation to call next.", "example": "checkDomainVerification" }, "mcp_tool": { "type": "string", "description": "The MCP tool that performs operation_id (`call_api` when there is no dedicated tool).", "example": "call_api" } }, "required": [ "type", "message" ], "description": "What to do next; null when verified.", "example": { "type": "publish_dns_record", "message": "Publish the TXT record, then call checkDomainVerification.", "operation_id": "checkDomainVerification", "mcp_tool": "call_api" } } }, "required": [ "id", "object", "site", "domain", "status", "method", "verified_at", "last_checked", "last_error", "dns_record", "file", "scan_target_problems", "account_activated", "next_action" ], "description": "Domain verification (only with expand[]=domain_verification)." }, "Site": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "site" ], "description": "String representing the object's type. Always \"site\".", "example": "site" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "name": { "type": "string", "description": "Display name.", "example": "Acme Coffee Club" }, "url": { "type": "string", "description": "Base URL.", "example": "https://acme.example" }, "platform": { "type": "string", "enum": [ "stripe", "shopify", "recharge", "chargebee", "recurly", "paddle", "woocommerce", "custom" ], "description": "Billing platform.", "example": "stripe" }, "jurisdictions": { "type": "array", "items": { "type": "string", "enum": [ "US-FED", "US-AL", "US-AK", "US-AZ", "US-AR", "US-CA", "US-CO", "US-CT", "US-DE", "US-DC", "US-FL", "US-GA", "US-HI", "US-ID", "US-IL", "US-IN", "US-IA", "US-KS", "US-KY", "US-LA", "US-ME", "US-MD", "US-MA", "US-MI", "US-MN", "US-MS", "US-MO", "US-MT", "US-NE", "US-NV", "US-NH", "US-NJ", "US-NM", "US-NY", "US-NC", "US-ND", "US-OH", "US-OK", "US-OR", "US-PA", "US-RI", "US-SC", "US-SD", "US-TN", "US-TX", "US-UT", "US-VT", "US-VA", "US-WA", "US-WV", "US-WI", "US-WY" ] }, "description": "Evaluated jurisdictions (empty = all).", "example": [] }, "facts": { "$ref": "#/components/schemas/SiteFacts" }, "checkout": { "type": "object", "properties": { "url": { "type": "string", "description": "Checkout entry page.", "example": "https://acme.example/pricing" }, "regions": { "type": "array", "items": { "type": "string", "enum": [ "US-FED", "US-AL", "US-AK", "US-AZ", "US-AR", "US-CA", "US-CO", "US-CT", "US-DE", "US-DC", "US-FL", "US-GA", "US-HI", "US-ID", "US-IL", "US-IN", "US-IA", "US-KS", "US-KY", "US-LA", "US-ME", "US-MD", "US-MA", "US-MI", "US-MN", "US-MS", "US-MO", "US-MT", "US-NE", "US-NV", "US-NH", "US-NJ", "US-NM", "US-NY", "US-NC", "US-ND", "US-OH", "US-OK", "US-OR", "US-PA", "US-RI", "US-SC", "US-SD", "US-TN", "US-TX", "US-UT", "US-VT", "US-VA", "US-WA", "US-WV", "US-WI", "US-WY" ] }, "description": "States scanned from.", "example": [ "US-CA", "US-NY" ] }, "devices": { "type": "array", "items": { "type": "string", "enum": [ "desktop", "mobile" ] }, "description": "Devices scanned.", "example": [ "desktop", "mobile" ] }, "checkout_steps": { "type": "integer", "description": "Number of configured checkout steps.", "example": 0 }, "completes_purchase": { "type": "boolean", "description": "A synthetic sign-up is configured.", "example": false }, "has_test_account": { "type": "boolean", "description": "A test account for the cancellation test is configured.", "example": false }, "test_account": { "type": [ "object", "null" ], "properties": { "login_url": { "type": "string", "description": "Login page.", "example": "https://acme.example/login" }, "email": { "type": "string", "description": "Test subscriber email.", "example": "test-subscriber@acme.example" } }, "required": [ "login_url", "email" ], "description": "The test account as configured (the password is write-only and never returned).", "example": { "login_url": "https://acme.example/login", "email": "test-subscriber@acme.example" } }, "cancel_steps": { "type": "integer", "description": "Number of explicit cancellation steps.", "example": 0 } }, "required": [ "url", "regions", "devices", "checkout_steps", "completes_purchase", "has_test_account", "test_account", "cancel_steps" ], "description": "Synthetic-shopper configuration (secrets are never returned).", "example": { "url": "https://acme.example/pricing", "regions": [ "US-CA", "US-NY" ], "devices": [ "desktop", "mobile" ], "checkout_steps": 0, "completes_purchase": false, "has_test_account": false, "test_account": { "login_url": "https://acme.example/login", "email": "test-subscriber@acme.example" }, "cancel_steps": 0 } }, "monitoring": { "$ref": "#/components/schemas/SiteMonitoring" }, "compliance": { "$ref": "#/components/schemas/SiteCompliance" }, "install": { "$ref": "#/components/schemas/SiteInstall" }, "archived": { "type": "boolean", "description": "Archived (soft-deleted); evidence is retained.", "example": false }, "created": { "type": "integer", "description": "When the site was created. Unix timestamp in seconds.", "example": 1793318400 }, "latest_scan": { "$ref": "#/components/schemas/Scan" }, "domain_verification": { "$ref": "#/components/schemas/DomainVerification" } }, "required": [ "id", "object", "livemode", "name", "url", "platform", "jurisdictions", "facts", "checkout", "monitoring", "compliance", "install", "archived", "created" ], "description": "A subscription business Checkbox monitors." }, "SiteList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "String representing the object's type. Always \"list\".", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Site" }, "description": "Sites, newest first.", "example": [ { "id": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "site", "livemode": false, "name": "Acme Coffee Club", "url": "https://acme.example", "platform": "stripe", "jurisdictions": [], "facts": { "has_free_trial": true, "trial_days": 14, "term_months": 1, "online_signup": true, "sells_goods": false, "notice_channel_email": true, "price_increase_consent_or_refund": false, "payment_methods": [ "card" ] }, "checkout": { "url": "https://acme.example/pricing", "regions": [ "US-CA", "US-NY" ], "devices": [ "desktop", "mobile" ], "checkout_steps": 0, "completes_purchase": false, "has_test_account": false, "test_account": { "login_url": "https://acme.example/login", "email": "test-subscriber@acme.example" }, "cancel_steps": 0 }, "monitoring": { "enabled": true, "interval_minutes": 1440, "held_for_activation": false, "last_scanned": 1793318400 }, "compliance": { "score": 82, "insurable": false, "evaluated": 1793318400, "open_findings": 2, "needs_review": 1 }, "install": { "script_tag": "", "snippet_key": "ab12cd34ef56", "inbound_email": "ab12cd34ef56@in.checkbox.site", "webhook_urls": { "stripe": "https://app.checkbox.site/webhooks/stripe/…" } }, "archived": false, "created": 1793318400, "latest_scan": { "id": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "scan", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "status": "completed", "trigger": "api", "regions": [ "US-CA", "US-NY" ], "error": null, "warnings": [], "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "score": 82, "insurable": false, "started": 1793318400, "finished": 1793318400, "created": 1793318400 }, "domain_verification": { "id": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "domain_verification", "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "domain": "acme.example", "status": "pending", "method": null, "verified_at": 1793318400, "last_checked": 1793318400, "last_error": "TXT record not found", "dns_record": { "type": "TXT", "name": "_checkbox-verify.acme.example", "value": "checkbox-verify=Xy…" }, "file": { "url": "https://acme.example/.well-known/checkbox-verify.txt", "contents": "Xy…" }, "scan_target_problems": [], "account_activated": false, "next_action": { "type": "publish_dns_record", "message": "Publish the TXT record, then call checkDomainVerification.", "operation_id": "checkDomainVerification", "mcp_tool": "call_api" } } } ] }, "has_more": { "type": "boolean", "description": "Whether more items exist after this page. Pass the last id as starting_after to fetch them.", "example": false }, "url": { "type": "string", "description": "The URL of this list.", "example": "/v1/sites" } }, "required": [ "object", "data", "has_more", "url" ], "description": "A page of sites, newest first." }, "ScanStep": { "oneOf": [ { "type": "object", "properties": { "action": { "type": "string", "enum": [ "goto" ], "description": "Navigate to a URL.", "example": "goto" }, "url": { "type": "string", "maxLength": 2000, "description": "URL to open.", "example": "https://example.com/pricing" } }, "required": [ "action", "url" ] }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "click" ], "description": "Click an element (by CSS selector or visible text).", "example": "click" }, "selector": { "type": "string", "maxLength": 1000, "description": "CSS selector of the element.", "example": "button.subscribe" }, "text": { "type": "string", "maxLength": 500, "description": "Visible text of the element (used when no selector).", "example": "Start free trial" } }, "required": [ "action" ] }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "fill", "select" ], "description": "Type into an input (fill) or choose an option (select).", "example": "fill" }, "selector": { "type": "string", "maxLength": 1000, "description": "CSS selector of the input.", "example": "#email" }, "value": { "type": "string", "maxLength": 2000, "description": "Value; {{email}}, {{password}} and {{promoCode}} are substituted.", "example": "{{email}}" } }, "required": [ "action", "selector", "value" ] }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "wait" ], "description": "Wait for a time or an element.", "example": "wait" }, "ms": { "type": "integer", "minimum": 0, "maximum": 60000, "description": "Milliseconds to wait.", "example": 1000 }, "selector": { "type": "string", "maxLength": 1000, "description": "Wait until this element appears.", "example": ".order-summary" } }, "required": [ "action" ] }, { "type": "object", "properties": { "action": { "type": "string", "enum": [ "capture" ], "description": "Record the current page as evidence.", "example": "capture" }, "page_kind": { "type": "string", "enum": [ "checkout", "account", "cancel", "pricing", "confirmation", "other" ], "description": "What the page is.", "example": "checkout" }, "label": { "type": "string", "maxLength": 200, "description": "Label shown in the dashboard.", "example": "Plan picker" } }, "required": [ "action", "page_kind" ] } ], "description": "One synthetic-shopper step." }, "SitePurchase": { "type": "object", "properties": { "steps": { "type": "array", "items": { "$ref": "#/components/schemas/ScanStep" }, "maxItems": 50, "description": "Steps that complete a sign-up after the checkout page.", "example": [ { "action": "click", "text": "Subscribe" } ] }, "promo_code": { "type": "string", "maxLength": 200, "description": "100%-off promo code used for the synthetic sign-up (write-only).", "example": "CHECKBOX100" } }, "required": [ "steps" ], "description": "How the synthetic shopper completes a real (free) sign-up." }, "SiteTestAccount": { "type": "object", "properties": { "login_url": { "type": "string", "maxLength": 2000, "description": "Login page of the test customer account.", "example": "https://example.com/login" }, "email": { "type": "string", "maxLength": 320, "description": "Test account email.", "example": "checkbox-test@example.com" }, "password": { "type": "string", "maxLength": 500, "description": "Test account password (write-only; encrypted at rest).", "example": "correct horse battery staple" }, "login_steps": { "type": "array", "items": { "$ref": "#/components/schemas/ScanStep" }, "maxItems": 50, "description": "Custom login steps.", "example": [] } }, "required": [ "login_url", "email", "password" ], "description": "A test customer account the synthetic shopper uses to try cancelling online." }, "CreateSiteParams": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Display name.", "example": "Acme Coffee Club" }, "url": { "type": "string", "maxLength": 2000, "description": "Base URL of the business website.", "example": "https://acme.example" }, "platform": { "type": "string", "enum": [ "stripe", "shopify", "recharge", "chargebee", "recurly", "paddle", "woocommerce", "custom" ], "description": "Billing platform.", "example": "stripe" }, "jurisdictions": { "type": "array", "items": { "type": "string", "enum": [ "US-FED", "US-AL", "US-AK", "US-AZ", "US-AR", "US-CA", "US-CO", "US-CT", "US-DE", "US-DC", "US-FL", "US-GA", "US-HI", "US-ID", "US-IL", "US-IN", "US-IA", "US-KS", "US-KY", "US-LA", "US-ME", "US-MD", "US-MA", "US-MI", "US-MN", "US-MS", "US-MO", "US-MT", "US-NE", "US-NV", "US-NH", "US-NJ", "US-NM", "US-NY", "US-NC", "US-ND", "US-OH", "US-OK", "US-OR", "US-PA", "US-RI", "US-SC", "US-SD", "US-TN", "US-TX", "US-UT", "US-VT", "US-VA", "US-WA", "US-WV", "US-WI", "US-WY" ] }, "description": "Jurisdictions to evaluate (empty = all US laws).", "example": [ "US-CA", "US-NY" ] }, "facts": { "$ref": "#/components/schemas/SiteFacts" }, "checkout_url": { "type": "string", "maxLength": 2000, "description": "Page with the subscribe button (defaults to url). Not a Stripe-hosted session link.", "example": "https://acme.example/pricing" }, "checkout_steps": { "type": "array", "items": { "$ref": "#/components/schemas/ScanStep" }, "maxItems": 50, "description": "Steps to reach the final pre-payment screen.", "example": [ { "action": "click", "text": "Choose monthly" } ] }, "purchase": { "$ref": "#/components/schemas/SitePurchase" }, "test_account": { "$ref": "#/components/schemas/SiteTestAccount" }, "cancel_steps": { "type": "array", "items": { "$ref": "#/components/schemas/ScanStep" }, "maxItems": 50, "description": "Explicit cancellation steps (otherwise auto-discovered).", "example": [] }, "regions": { "type": "array", "items": { "type": "string", "enum": [ "US-FED", "US-AL", "US-AK", "US-AZ", "US-AR", "US-CA", "US-CO", "US-CT", "US-DE", "US-DC", "US-FL", "US-GA", "US-HI", "US-ID", "US-IL", "US-IN", "US-IA", "US-KS", "US-KY", "US-LA", "US-ME", "US-MD", "US-MA", "US-MI", "US-MN", "US-MS", "US-MO", "US-MT", "US-NE", "US-NV", "US-NH", "US-NJ", "US-NM", "US-NY", "US-NC", "US-ND", "US-OH", "US-OK", "US-OR", "US-PA", "US-RI", "US-SC", "US-SD", "US-TN", "US-TX", "US-UT", "US-VT", "US-VA", "US-WA", "US-WV", "US-WI", "US-WY" ] }, "minItems": 1, "description": "States the synthetic shopper visits from.", "example": [ "US-CA", "US-NY" ] }, "devices": { "type": "array", "items": { "type": "string", "enum": [ "desktop", "mobile" ] }, "minItems": 1, "description": "Devices to emulate.", "example": [ "desktop", "mobile" ] }, "monitoring_interval_minutes": { "type": "integer", "minimum": 0, "description": "Scheduled re-scan interval (0 = off, minimum 60). Default 1440 in live mode, 0 in test mode.", "example": 1440 } }, "required": [ "url" ] }, "UpdateSiteParams": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Display name.", "example": "Acme Coffee Club" }, "url": { "type": "string", "maxLength": 2000, "description": "Base URL of the business website.", "example": "https://acme.example" }, "platform": { "type": "string", "enum": [ "stripe", "shopify", "recharge", "chargebee", "recurly", "paddle", "woocommerce", "custom" ], "description": "Billing platform.", "example": "stripe" }, "jurisdictions": { "type": "array", "items": { "type": "string", "enum": [ "US-FED", "US-AL", "US-AK", "US-AZ", "US-AR", "US-CA", "US-CO", "US-CT", "US-DE", "US-DC", "US-FL", "US-GA", "US-HI", "US-ID", "US-IL", "US-IN", "US-IA", "US-KS", "US-KY", "US-LA", "US-ME", "US-MD", "US-MA", "US-MI", "US-MN", "US-MS", "US-MO", "US-MT", "US-NE", "US-NV", "US-NH", "US-NJ", "US-NM", "US-NY", "US-NC", "US-ND", "US-OH", "US-OK", "US-OR", "US-PA", "US-RI", "US-SC", "US-SD", "US-TN", "US-TX", "US-UT", "US-VT", "US-VA", "US-WA", "US-WV", "US-WI", "US-WY" ] }, "description": "Jurisdictions to evaluate (empty = all US laws).", "example": [ "US-CA", "US-NY" ] }, "facts": { "$ref": "#/components/schemas/SiteFacts" }, "checkout_url": { "type": "string", "maxLength": 2000, "description": "Page with the subscribe button (defaults to url). Not a Stripe-hosted session link.", "example": "https://acme.example/pricing" }, "checkout_steps": { "type": "array", "items": { "$ref": "#/components/schemas/ScanStep" }, "maxItems": 50, "description": "Steps to reach the final pre-payment screen.", "example": [ { "action": "click", "text": "Choose monthly" } ] }, "purchase": { "$ref": "#/components/schemas/SitePurchase" }, "test_account": { "$ref": "#/components/schemas/SiteTestAccount" }, "cancel_steps": { "type": "array", "items": { "$ref": "#/components/schemas/ScanStep" }, "maxItems": 50, "description": "Explicit cancellation steps (otherwise auto-discovered).", "example": [] }, "regions": { "type": "array", "items": { "type": "string", "enum": [ "US-FED", "US-AL", "US-AK", "US-AZ", "US-AR", "US-CA", "US-CO", "US-CT", "US-DE", "US-DC", "US-FL", "US-GA", "US-HI", "US-ID", "US-IL", "US-IN", "US-IA", "US-KS", "US-KY", "US-LA", "US-ME", "US-MD", "US-MA", "US-MI", "US-MN", "US-MS", "US-MO", "US-MT", "US-NE", "US-NV", "US-NH", "US-NJ", "US-NM", "US-NY", "US-NC", "US-ND", "US-OH", "US-OK", "US-OR", "US-PA", "US-RI", "US-SC", "US-SD", "US-TN", "US-TX", "US-UT", "US-VT", "US-VA", "US-WA", "US-WV", "US-WI", "US-WY" ] }, "minItems": 1, "description": "States the synthetic shopper visits from.", "example": [ "US-CA", "US-NY" ] }, "devices": { "type": "array", "items": { "type": "string", "enum": [ "desktop", "mobile" ] }, "minItems": 1, "description": "Devices to emulate.", "example": [ "desktop", "mobile" ] }, "monitoring_interval_minutes": { "type": "integer", "minimum": 0, "description": "Scheduled re-scan interval (0 = off, minimum 60). Default 1440 in live mode, 0 in test mode.", "example": 1440 } } }, "ScanList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "String representing the object's type. Always \"list\".", "example": "list" }, "data": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Scan" }, { "description": "One synthetic-shopper run (checkout per state and device, optional sign-up and cancellation attempt) or evaluation-only run." } ] }, "description": "Scans, newest first.", "example": [ { "id": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "scan", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "status": "completed", "trigger": "api", "regions": [ "US-CA", "US-NY" ], "error": null, "warnings": [], "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "score": 82, "insurable": false, "started": 1793318400, "finished": 1793318400, "created": 1793318400 } ] }, "has_more": { "type": "boolean", "description": "Whether more items exist after this page. Pass the last id as starting_after to fetch them.", "example": false }, "url": { "type": "string", "description": "The URL of this list.", "example": "/v1/sites" } }, "required": [ "object", "data", "has_more", "url" ], "description": "A page of scans, newest first." }, "CheckSummary": { "type": "object", "properties": { "check_id": { "type": "string", "description": "Check id.", "example": "cancellation.online_cancel_available" }, "title": { "type": "string", "description": "Title.", "example": "Customers can cancel online" }, "status": { "type": "string", "enum": [ "pass", "fail", "needs_review", "not_applicable" ], "description": "Result.", "example": "pass" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ], "description": "Severity.", "example": "critical" }, "stage": { "type": "string", "enum": [ "signup", "confirmation", "reminder", "cancellation", "config" ], "description": "Lifecycle stage.", "example": "cancellation" } }, "required": [ "check_id", "title", "status", "severity", "stage" ], "description": "One check of an evaluation." }, "Evaluation": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the evaluation (eval_…).", "example": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "evaluation" ], "description": "String representing the object's type. Always \"evaluation\".", "example": "evaluation" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "site": { "type": "string", "description": "The evaluated site.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "scan": { "type": "string", "description": "The scan row this evaluation belongs to.", "example": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "score": { "type": "number", "minimum": 0, "maximum": 100, "description": "Compliance score 0-100 (severity-weighted, one decimal place, e.g. 82.5).", "example": 82 }, "insurable": { "type": "boolean", "description": "No critical/high check failing, no critical check undecided, no high check without evidence.", "example": false }, "rules_version": { "type": "string", "description": "Legal catalog / rules version used.", "example": "2026.10.1" }, "evaluated": { "type": "integer", "description": "When it was evaluated. Unix timestamp in seconds.", "example": 1793318400 }, "observed": { "type": [ "integer", "null" ], "description": "Newest synthetic-shopper observation it used. Unix timestamp in seconds.", "example": 1793318400 }, "summary": { "type": "object", "properties": { "pass": { "type": "integer", "description": "Passing checks.", "example": 20 }, "fail": { "type": "integer", "description": "Failing checks.", "example": 2 }, "needs_review": { "type": "integer", "description": "Checks needing a human look.", "example": 1 }, "not_applicable": { "type": "integer", "description": "Checks that do not apply.", "example": 9 } }, "required": [ "pass", "fail", "needs_review", "not_applicable" ], "description": "Counts per status.", "example": { "pass": 20, "fail": 2, "needs_review": 1, "not_applicable": 9 } }, "blockers": { "type": "array", "items": { "$ref": "#/components/schemas/CheckSummary" }, "description": "Checks that keep the site from being insurable.", "example": [ { "check_id": "cancellation.online_cancel_available", "title": "Customers can cancel online", "status": "pass", "severity": "critical", "stage": "cancellation" } ] }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/CheckSummary" }, "description": "Every check evaluated.", "example": [ { "check_id": "cancellation.online_cancel_available", "title": "Customers can cancel online", "status": "pass", "severity": "critical", "stage": "cancellation" } ] } }, "required": [ "id", "object", "livemode", "site", "scan", "score", "insurable", "rules_version", "evaluated", "observed", "summary", "blockers", "checks" ], "description": "A compliance verdict for a site at a point in time." }, "EvaluationList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "String representing the object's type. Always \"list\".", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Evaluation" }, "description": "Evaluations, newest first.", "example": [ { "id": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "evaluation", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "scan": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "score": 82, "insurable": false, "rules_version": "2026.10.1", "evaluated": 1793318400, "observed": 1793318400, "summary": { "pass": 20, "fail": 2, "needs_review": 1, "not_applicable": 9 }, "blockers": [ { "check_id": "cancellation.online_cancel_available", "title": "Customers can cancel online", "status": "pass", "severity": "critical", "stage": "cancellation" } ], "checks": [ { "check_id": "cancellation.online_cancel_available", "title": "Customers can cancel online", "status": "pass", "severity": "critical", "stage": "cancellation" } ] } ] }, "has_more": { "type": "boolean", "description": "Whether more items exist after this page. Pass the last id as starting_after to fetch them.", "example": false }, "url": { "type": "string", "description": "The URL of this list.", "example": "/v1/sites" } }, "required": [ "object", "data", "has_more", "url" ], "description": "A page of evaluations, newest first." }, "RequirementRef": { "type": "object", "properties": { "id": { "type": "string", "description": "Requirement id in the legal catalog.", "example": "US-CA.17602.a.1" }, "jurisdiction": { "type": "string", "enum": [ "US-FED", "US-AL", "US-AK", "US-AZ", "US-AR", "US-CA", "US-CO", "US-CT", "US-DE", "US-DC", "US-FL", "US-GA", "US-HI", "US-ID", "US-IL", "US-IN", "US-IA", "US-KS", "US-KY", "US-LA", "US-ME", "US-MD", "US-MA", "US-MI", "US-MN", "US-MS", "US-MO", "US-MT", "US-NE", "US-NV", "US-NH", "US-NJ", "US-NM", "US-NY", "US-NC", "US-ND", "US-OH", "US-OK", "US-OR", "US-PA", "US-RI", "US-SC", "US-SD", "US-TN", "US-TX", "US-UT", "US-VT", "US-VA", "US-WA", "US-WV", "US-WI", "US-WY" ], "description": "Jurisdiction of the law.", "example": "US-CA" }, "citation": { "type": "string", "description": "Legal citation.", "example": "Cal. Bus. & Prof. Code § 17602(a)(1)" }, "title": { "type": "string", "description": "What the law requires, in short.", "example": "Clear and conspicuous auto-renewal terms before purchase" }, "source_url": { "type": "string", "description": "Official source of the text.", "example": "https://leginfo.legislature.ca.gov/…" } }, "required": [ "id", "jurisdiction", "citation", "title", "source_url" ], "description": "A legal requirement a finding checks." }, "Remediation": { "type": [ "object", "null" ], "properties": { "summary": { "type": "string", "description": "What to change.", "example": "Show the auto-renewal terms next to the subscribe button." }, "steps": { "type": "array", "items": { "type": "string" }, "description": "Steps to fix it.", "example": [ "Add the disclosure above the button" ] }, "platform": { "type": [ "string", "null" ], "description": "Platform the steps are written for.", "example": "stripe" }, "suggested_copy": { "type": [ "string", "null" ], "description": "Suggested disclosure text.", "example": "Your subscription renews automatically every month at $9.99 until you cancel." }, "snippet": { "type": [ "object", "null" ], "properties": { "language": { "type": "string", "description": "Language of the code.", "example": "html" }, "code": { "type": "string", "description": "Code to apply.", "example": "

…

" } }, "required": [ "language", "code" ], "description": "Code snippet, when there is one.", "example": { "language": "html", "code": "

…

" } } }, "required": [ "summary", "steps", "platform", "suggested_copy", "snippet" ], "description": "How to fix the finding (see also the fixes resource and compliance plans)." }, "Finding": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the finding (fnd_…).", "example": "fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "finding" ], "description": "String representing the object's type. Always \"finding\".", "example": "finding" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "site": { "type": "string", "description": "The site.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "check_id": { "type": "string", "description": "Stable id of the legal check.", "example": "signup.disclosure_clear_conspicuous" }, "title": { "type": "string", "description": "Short title.", "example": "Auto-renewal terms are not shown before purchase" }, "detail": { "type": "string", "description": "What was observed.", "example": "The checkout page in US-CA (mobile) shows no renewal terms near the subscribe button." }, "stage": { "type": "string", "enum": [ "signup", "confirmation", "reminder", "cancellation", "config" ], "description": "Lifecycle stage.", "example": "signup" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ], "description": "Strictest severity among the applicable requirements.", "example": "high" }, "status": { "type": "string", "enum": [ "pass", "fail", "needs_review", "not_applicable" ], "description": "Latest check result.", "example": "fail" }, "state": { "type": "string", "enum": [ "open", "acknowledged", "resolved", "accepted_risk" ], "description": "Triage state.", "example": "open" }, "note": { "type": [ "string", "null" ], "description": "Triage note.", "example": null }, "jurisdictions": { "type": "array", "items": { "type": "string", "enum": [ "US-FED", "US-AL", "US-AK", "US-AZ", "US-AR", "US-CA", "US-CO", "US-CT", "US-DE", "US-DC", "US-FL", "US-GA", "US-HI", "US-ID", "US-IL", "US-IN", "US-IA", "US-KS", "US-KY", "US-LA", "US-ME", "US-MD", "US-MA", "US-MI", "US-MN", "US-MS", "US-MO", "US-MT", "US-NE", "US-NV", "US-NH", "US-NJ", "US-NM", "US-NY", "US-NC", "US-ND", "US-OH", "US-OK", "US-OR", "US-PA", "US-RI", "US-SC", "US-SD", "US-TN", "US-TX", "US-UT", "US-VT", "US-VA", "US-WA", "US-WV", "US-WI", "US-WY" ] }, "description": "Jurisdictions whose laws this check applies.", "example": [ "US-CA", "US-NY" ] }, "requirements": { "type": "array", "items": { "$ref": "#/components/schemas/RequirementRef" }, "description": "The legal requirements behind the check, with citations.", "example": [ { "id": "US-CA.17602.a.1", "jurisdiction": "US-CA", "citation": "Cal. Bus. & Prof. Code § 17602(a)(1)", "title": "Clear and conspicuous auto-renewal terms before purchase", "source_url": "https://leginfo.legislature.ca.gov/…" } ] }, "remediation": { "$ref": "#/components/schemas/Remediation" }, "confidence": { "type": "number", "description": "Confidence 0-1 of the check result.", "example": 0.9 }, "evidence_refs": { "type": "array", "items": { "type": "string" }, "description": "Ids of the captures / emails / evidence records supporting the result.", "example": [] }, "details": { "type": "object", "additionalProperties": {}, "description": "Check-specific details (failing regions/devices/URLs, measurements, quotes).", "example": { "failingRegions": [ "US-CA" ] } }, "scan": { "type": [ "string", "null" ], "description": "Scan that produced the latest result.", "example": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "first_seen": { "type": "integer", "description": "First time the check was evaluated. Unix timestamp in seconds.", "example": 1793318400 }, "last_seen": { "type": "integer", "description": "Latest evaluation. Unix timestamp in seconds.", "example": 1793318400 }, "resolved_at": { "type": [ "integer", "null" ], "description": "When it was resolved. Unix timestamp in seconds.", "example": 1793318400 } }, "required": [ "id", "object", "livemode", "site", "check_id", "title", "detail", "stage", "severity", "status", "state", "note", "jurisdictions", "requirements", "remediation", "confidence", "evidence_refs", "details", "scan", "first_seen", "last_seen", "resolved_at" ], "description": "The latest result of one legal check for a site." }, "FindingList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "String representing the object's type. Always \"list\".", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Finding" }, "description": "Findings, most urgent first.", "example": [ { "id": "fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "finding", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "check_id": "signup.disclosure_clear_conspicuous", "title": "Auto-renewal terms are not shown before purchase", "detail": "The checkout page in US-CA (mobile) shows no renewal terms near the subscribe button.", "stage": "signup", "severity": "high", "status": "fail", "state": "open", "note": null, "jurisdictions": [ "US-CA", "US-NY" ], "requirements": [ { "id": "US-CA.17602.a.1", "jurisdiction": "US-CA", "citation": "Cal. Bus. & Prof. Code § 17602(a)(1)", "title": "Clear and conspicuous auto-renewal terms before purchase", "source_url": "https://leginfo.legislature.ca.gov/…" } ], "remediation": { "summary": "Show the auto-renewal terms next to the subscribe button.", "steps": [ "Add the disclosure above the button" ], "platform": "stripe", "suggested_copy": "Your subscription renews automatically every month at $9.99 until you cancel.", "snippet": { "language": "html", "code": "

…

" } }, "confidence": 0.9, "evidence_refs": [], "details": { "failingRegions": [ "US-CA" ] }, "scan": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "first_seen": 1793318400, "last_seen": 1793318400, "resolved_at": 1793318400 } ] }, "has_more": { "type": "boolean", "description": "Whether more items exist after this page. Pass the last id as starting_after to fetch them.", "example": false }, "url": { "type": "string", "description": "The URL of this list.", "example": "/v1/sites" } }, "required": [ "object", "data", "has_more", "url" ], "description": "A page of findings, most urgent first." }, "PlanCitation": { "type": "object", "properties": { "id": { "type": "string", "description": "Requirement id in the legal catalog.", "example": "US-CA.17602.a.1" }, "jurisdiction": { "type": "string", "description": "Jurisdiction.", "example": "US-CA" }, "citation": { "type": "string", "description": "Legal citation.", "example": "Cal. Bus. & Prof. Code § 17602(a)(1)" }, "source_url": { "type": "string", "description": "Official source.", "example": "https://leginfo.legislature.ca.gov/" } }, "required": [ "id", "jurisdiction", "citation", "source_url" ], "description": "One legal requirement behind a task." }, "PlanEdit": { "type": "object", "properties": { "op": { "type": "string", "enum": [ "insert_before", "insert_after", "remove_attribute", "replace_text", "append" ], "description": "Edit operation for `checkbox fix --file` (or your own editor).", "example": "insert_before" }, "target": { "type": "object", "properties": { "selector": { "type": [ "string", "null" ], "description": "CSS selector observed on the rendered page (ids are the most stable anchor).", "example": "#subscribe-button" }, "text": { "type": [ "string", "null" ], "description": "Visible text of the anchor element.", "example": "Start now" }, "tag": { "type": [ "string", "null" ], "description": "HTML tag of the anchor element.", "example": "button" } }, "required": [ "selector", "text", "tag" ], "description": "The element the edit is anchored to.", "example": { "selector": "#subscribe-button", "text": "Start now", "tag": "button" } }, "content": { "type": [ "string", "null" ], "description": "Markup / text to insert or the replacement text.", "example": "
…
" }, "attribute": { "type": [ "string", "null" ], "description": "For remove_attribute: the attribute to remove.", "example": "checked" } }, "required": [ "op", "target", "content", "attribute" ], "description": "A machine-applicable edit of the merchant's source, anchored to an element Checkbox observed." }, "PlanNextAction": { "type": "object", "properties": { "type": { "type": "string", "description": "Stable action type: apply_task, provide_facts, verify_task, answer_question, ask_human_to_confirm, connect_billing_in_dashboard, wait_for_verification, run_first_check, review_wont_fix, done.", "example": "apply_task" }, "description": { "type": "string", "description": "One or two sentences telling the agent exactly what to do now.", "example": "Apply task_… (add the renewal terms above the Subscribe button in app/checkout/page.tsx), then call verifyTask." }, "task": { "type": [ "string", "null" ], "description": "The task the action is about, when there is one.", "example": "task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "operation_id": { "type": [ "string", "null" ], "description": "operationId of the API call to make (also the SDK method name).", "example": "verifyTask" }, "mcp_tool": { "type": [ "string", "null" ], "description": "The MCP tool that performs operation_id (`call_api` when there is no dedicated tool).", "example": "verify_task" }, "endpoint": { "type": [ "string", "null" ], "description": "HTTP method and path of that call.", "example": "POST /v1/tasks/task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/verify" }, "command": { "type": [ "string", "null" ], "description": "Equivalent CLI command.", "example": "checkbox fix task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" } }, "required": [ "type", "description", "task", "operation_id", "endpoint", "command" ], "description": "What the caller (usually an AI coding agent) should do next." }, "Task": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the task (task_…).", "example": "task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "task" ], "description": "String representing the object's type. Always \"task\".", "example": "task" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "site": { "type": "string", "description": "The site.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "key": { "type": "string", "description": "Stable key of the task within the site (the id is derived from site + key).", "example": "signup_disclosure" }, "title": { "type": "string", "description": "Short imperative title.", "example": "Show the renewal terms and an unchecked consent box above the Subscribe button" }, "status": { "type": "string", "enum": [ "open", "in_progress", "verifying", "done", "wont_fix", "manual" ], "description": "open (apply the change), in_progress (an agent claimed it), verifying (a verification is waiting for a confirming observation), done, wont_fix (the merchant declined, with a reason), manual (needs a human answer: see question).", "example": "open" }, "priority": { "type": "string", "enum": [ "critical", "high", "medium", "low" ], "description": "Strictest severity among the task's legal checks.", "example": "critical" }, "order": { "type": "integer", "description": "Position in the plan (1 = do first). Dependency-aware.", "example": 1 }, "check_ids": { "type": "array", "items": { "type": "string" }, "description": "Legal checks this task makes pass.", "example": [ "signup.disclosure.autorenew_language", "signup.consent.affirmative" ] }, "findings": { "type": "array", "items": { "type": "string", "description": "Unique identifier of the finding (fnd_…).", "example": "fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "description": "Open findings the task resolves.", "example": [] }, "requirement": { "type": "object", "properties": { "jurisdictions": { "type": "array", "items": { "type": "string" }, "description": "Jurisdictions whose laws require it.", "example": [ "US-FED", "US-CA", "US-NY" ] }, "citation": { "type": "string", "description": "Main citations, joined.", "example": "15 U.S.C. § 8403(1); Cal. Bus. & Prof. Code § 17602(a)(1)" }, "citations": { "type": "array", "items": { "$ref": "#/components/schemas/PlanCitation" }, "description": "Every requirement behind the task.", "example": [ { "id": "US-CA.17602.a.1", "jurisdiction": "US-CA", "citation": "Cal. Bus. & Prof. Code § 17602(a)(1)", "source_url": "https://leginfo.legislature.ca.gov/" } ] }, "plain_language": { "type": "string", "description": "What the law requires, in one or two sentences.", "example": "Before the purchase, state clearly that the subscription renews automatically until canceled, the price and frequency, and how to cancel." } }, "required": [ "jurisdictions", "citation", "citations", "plain_language" ], "description": "The legal requirement.", "example": { "jurisdictions": [ "US-FED", "US-CA", "US-NY" ], "citation": "15 U.S.C. § 8403(1); Cal. Bus. & Prof. Code § 17602(a)(1)", "citations": [ { "id": "US-CA.17602.a.1", "jurisdiction": "US-CA", "citation": "Cal. Bus. & Prof. Code § 17602(a)(1)", "source_url": "https://leginfo.legislature.ca.gov/" } ], "plain_language": "Before the purchase, state clearly that the subscription renews automatically until canceled, the price and frequency, and how to cancel." } }, "why": { "type": "string", "description": "What Checkbox observed (why this task exists).", "example": "The checkout in US-CA shows no renewal terms near \"Start now\"; the consent checkbox is pre-checked." }, "where": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "code", "stripe_setting", "email_template", "policy_page", "dns", "checkbox_setting", "billing_platform" ], "description": "Where the change is made.", "example": "code" }, "file_hint": { "type": [ "string", "null" ], "description": "Likely source file (reported by `checkbox init` / updateSetupSession, else a framework convention).", "example": "app/checkout/page.tsx" }, "url": { "type": [ "string", "null" ], "description": "Page (or settings page) where the problem was observed / the change is made.", "example": "https://shop.example/checkout" }, "selector": { "type": [ "string", "null" ], "description": "CSS selector of the element to change, as observed on the rendered page.", "example": "#subscribe-button" }, "stripe_object": { "type": [ "string", "null" ], "description": "Stripe object / setting to change (stripe_setting tasks).", "example": "checkout.session" } }, "required": [ "kind", "file_hint", "url", "selector", "stripe_object" ], "description": "Where to make the change.", "example": { "kind": "code", "file_hint": "app/checkout/page.tsx", "url": "https://shop.example/checkout", "selector": "#subscribe-button", "stripe_object": "checkout.session" } }, "change": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "patch", "copy", "stripe_params", "config", "needs_facts", "manual" ], "description": "patch (code edit; content is a unified-diff template), copy (exact text), stripe_params (JSON to merge into a Stripe API call), config (a setting: content is the request body of operation_id), needs_facts (Checkbox needs facts before it can write exact copy: content is the body of operation_id to send them; never a patch with placeholders), manual (a human does it).", "example": "patch" }, "content": { "type": "string", "description": "The change itself: unified-diff template, exact copy, or JSON params. Generated from the merchant's real terms and verified against the rules engine where possible.", "example": "--- a/app/checkout/page.tsx\n+++ b/app/checkout/page.tsx\n@@ …" }, "language": { "type": [ "string", "null" ], "description": "Language of content (html, json, text, markdown, liquid, bash).", "example": "html" }, "explanation": { "type": "string", "description": "How to apply it and what must stay true.", "example": "Insert directly above the purchase button; never pre-check the box." }, "edits": { "type": "array", "items": { "$ref": "#/components/schemas/PlanEdit" }, "description": "Machine-applicable edits (`checkbox fix --file ` turns them into an exact diff of your file).", "example": [ { "op": "insert_before", "target": { "selector": "#subscribe-button", "text": "Start now", "tag": "button" }, "content": "
…
", "attribute": "checked" } ] }, "engine_verified": { "type": "boolean", "description": "The generated text was run through the rules engine on a model of the changed page and passes.", "example": true }, "operation_id": { "type": [ "string", "null" ], "description": "config / needs_facts: the API operation to send content to (its request body, validated against that operation).", "example": "updateSite" }, "endpoint": { "type": [ "string", "null" ], "description": "HTTP method and path of operation_id.", "example": "POST /v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" } }, "required": [ "type", "content", "language", "explanation", "edits", "engine_verified", "operation_id", "endpoint" ], "description": "The exact change.", "example": { "type": "patch", "content": "--- a/app/checkout/page.tsx\n+++ b/app/checkout/page.tsx\n@@ …", "language": "html", "explanation": "Insert directly above the purchase button; never pre-check the box.", "edits": [ { "op": "insert_before", "target": { "selector": "#subscribe-button", "text": "Start now", "tag": "button" }, "content": "
…
", "attribute": "checked" } ], "engine_verified": true, "operation_id": "updateSite", "endpoint": "POST /v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" } }, "verify": { "type": "object", "properties": { "method": { "type": "string", "enum": [ "page_fetch", "policy_refetch", "stripe_params", "email_copy", "platform_sync", "attestation", "evaluation", "test_run" ], "description": "How Checkbox re-checks it.", "example": "page_fetch" }, "how": { "type": "string", "description": "What to call after applying the change.", "example": "POST /v1/tasks/task_…/verify" }, "expected": { "type": "string", "description": "What Checkbox must observe for the task to be done.", "example": "Every listed check passes (layout checks may stay needs_review on a static fetch until the confirming scan)." } }, "required": [ "method", "how", "expected" ], "description": "How to verify the task.", "example": { "method": "page_fetch", "how": "POST /v1/tasks/task_…/verify", "expected": "Every listed check passes (layout checks may stay needs_review on a static fetch until the confirming scan)." } }, "blocked_on": { "type": [ "string", "null" ], "description": "What Checkbox needs before it can give the exact change (observation: it has not seen the page / email yet; facts: plan, price, cancel URL or merchant name). The title stays the same either way.", "example": null }, "closed_reason": { "type": [ "string", "null" ], "enum": [ "verified", "no_longer_applicable", "superseded", "declined" ], "description": "Done / declined tasks: verified (its checks pass), no_longer_applicable (its checks no longer apply, e.g. the data source changed), superseded, declined.", "example": null }, "depends_on": { "type": "array", "items": { "type": "string", "description": "Unique identifier of the task (task_…).", "example": "task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "description": "Tasks to finish first (their result changes this task's content).", "example": [] }, "blocked_by": { "type": "array", "items": { "type": "string", "description": "Unique identifier of the task (task_…).", "example": "task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "description": "Unfinished tasks among depends_on.", "example": [] }, "question": { "type": [ "object", "null" ], "properties": { "text": { "type": "string", "description": "The question for the human (manual tasks only).", "example": "Did your subscribers choose email as the channel for account notices?" }, "options": { "type": "array", "items": { "type": "string" }, "description": "Accepted answers.", "example": [ "yes", "no" ] }, "why": { "type": "string", "description": "Why a machine cannot answer it.", "example": "New York requires notices in the manner the subscriber selected; no page or email shows that choice." }, "effect": { "type": "string", "description": "What the answer changes.", "example": "yes records the attestation (site fact notice_channel_email) and re-evaluates." } }, "required": [ "text", "options", "why", "effect" ], "description": "For manual tasks: the human question; answer with answerTask.", "example": { "text": "Did your subscribers choose email as the channel for account notices?", "options": [ "yes", "no" ], "why": "New York requires notices in the manner the subscriber selected; no page or email shows that choice.", "effect": "yes records the attestation (site fact notice_channel_email) and re-evaluates." } }, "answer": { "type": [ "object", "null" ], "properties": { "value": { "type": "string", "description": "The recorded answer.", "example": "yes" }, "note": { "type": [ "string", "null" ], "description": "Note given with the answer.", "example": null }, "answered": { "type": "integer", "description": "When it was answered. Unix timestamp in seconds.", "example": 1793318400 }, "confirmed_by_human": { "type": "boolean", "description": "A person confirmed the answer while signed in to Checkbox (dashboard or the emailed link). Attestations (\"yes\", \"confirmed\") count only then; an API key alone cannot attest.", "example": false }, "pending_confirmation_url": { "type": [ "string", "null" ], "description": "Answer recorded by an agent and waiting for the human: the link they open to confirm it.", "example": null } }, "required": [ "value", "note", "answered", "confirmed_by_human", "pending_confirmation_url" ], "description": "The recorded answer of a manual task.", "example": { "value": "yes", "note": null, "answered": 1793318400, "confirmed_by_human": false, "pending_confirmation_url": null } }, "decision": { "type": [ "object", "null" ], "properties": { "status": { "type": "string", "enum": [ "in_progress", "wont_fix" ], "description": "Decision.", "example": "wont_fix" }, "reason": { "type": [ "string", "null" ], "description": "Reason given.", "example": "Annual plan retired; no subscribers left." } }, "required": [ "status", "reason" ], "description": "A decision recorded with updateTask.", "example": { "status": "wont_fix", "reason": "Annual plan retired; no subscribers left." } }, "last_verification": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Unique identifier of the verification (ver_…).", "example": "ver_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "status": { "type": "string", "enum": [ "pending", "passed", "failed" ], "description": "Result.", "example": "failed" }, "created": { "type": "integer", "description": "When it was requested. Unix timestamp in seconds.", "example": 1793318400 } }, "required": [ "id", "status", "created" ], "description": "The newest verification of the task (retrieveVerification for the details).", "example": { "id": "ver_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "status": "failed", "created": 1793318400 } }, "next_action": { "$ref": "#/components/schemas/PlanNextAction" }, "first_seen": { "type": "integer", "description": "When the task first appeared. Unix timestamp in seconds.", "example": 1793318400 }, "done_at": { "type": [ "integer", "null" ], "description": "When it was done. Unix timestamp in seconds.", "example": 1793318400 } }, "required": [ "id", "object", "livemode", "site", "key", "title", "status", "priority", "order", "check_ids", "findings", "requirement", "why", "where", "change", "verify", "blocked_on", "closed_reason", "depends_on", "blocked_by", "question", "answer", "decision", "last_verification", "next_action", "first_seen", "done_at" ], "description": "One ordered compliance task: the requirement, where to change, the exact change and how to verify it." }, "CompliancePlan": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the compliance plan (plan_…).", "example": "plan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "compliance_plan" ], "description": "String representing the object's type. Always \"compliance_plan\".", "example": "compliance_plan" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "site": { "type": "string", "description": "The site.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "status": { "type": "string", "enum": [ "action_required", "verifying", "compliant", "blocked" ], "description": "action_required (an agent can apply open tasks now), verifying (changes applied; waiting for confirming observations), compliant (every applicable check Checkbox could observe passes — an automated assessment, not a legal determination; see coverage for what was not observed), blocked (only human answers or declined critical tasks remain).", "example": "action_required" }, "score": { "type": [ "integer", "null" ], "description": "Compliance score 0-100 of the latest evaluation.", "example": 62 }, "insurable": { "type": [ "boolean", "null" ], "description": "Preview flag the planned Checkbox Warranty will key on (no checks failing at high severity). No warranty or insurance is offered yet; this is not an underwriting decision.", "example": false }, "evaluation": { "type": [ "string", "null" ], "description": "The evaluation the plan was built from (null before the first check).", "example": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "evaluated": { "type": [ "integer", "null" ], "description": "When that evaluation ran. Unix timestamp in seconds.", "example": 1793318400 }, "summary": { "type": "string", "description": "Two or three sentences for an LLM: where the site stands and what comes next.", "example": "StreamMax fails 4 critical checks…" }, "counts": { "type": "object", "properties": { "open": { "type": "integer", "description": "Open tasks.", "example": 3 }, "in_progress": { "type": "integer", "description": "Claimed tasks.", "example": 0 }, "verifying": { "type": "integer", "description": "Tasks waiting for a confirming observation.", "example": 1 }, "manual": { "type": "integer", "description": "Tasks waiting for a human answer.", "example": 1 }, "done": { "type": "integer", "description": "Done tasks.", "example": 2 }, "wont_fix": { "type": "integer", "description": "Declined tasks.", "example": 0 } }, "required": [ "open", "in_progress", "verifying", "manual", "done", "wont_fix" ], "description": "Tasks per status.", "example": { "open": 3, "in_progress": 0, "verifying": 1, "manual": 1, "done": 2, "wont_fix": 0 } }, "tasks": { "type": "array", "items": { "$ref": "#/components/schemas/Task" }, "description": "Tasks in the order to do them (done tasks last).", "example": [ { "id": "task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "task", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "key": "signup_disclosure", "title": "Show the renewal terms and an unchecked consent box above the Subscribe button", "status": "open", "priority": "critical", "order": 1, "check_ids": [ "signup.disclosure.autorenew_language", "signup.consent.affirmative" ], "findings": [], "requirement": { "jurisdictions": [ "US-FED", "US-CA", "US-NY" ], "citation": "15 U.S.C. § 8403(1); Cal. Bus. & Prof. Code § 17602(a)(1)", "citations": [ { "id": "US-CA.17602.a.1", "jurisdiction": "US-CA", "citation": "Cal. Bus. & Prof. Code § 17602(a)(1)", "source_url": "https://leginfo.legislature.ca.gov/" } ], "plain_language": "Before the purchase, state clearly that the subscription renews automatically until canceled, the price and frequency, and how to cancel." }, "why": "The checkout in US-CA shows no renewal terms near \"Start now\"; the consent checkbox is pre-checked.", "where": { "kind": "code", "file_hint": "app/checkout/page.tsx", "url": "https://shop.example/checkout", "selector": "#subscribe-button", "stripe_object": "checkout.session" }, "change": { "type": "patch", "content": "--- a/app/checkout/page.tsx\n+++ b/app/checkout/page.tsx\n@@ …", "language": "html", "explanation": "Insert directly above the purchase button; never pre-check the box.", "edits": [ { "op": "insert_before", "target": { "selector": "#subscribe-button", "text": "Start now", "tag": "button" }, "content": "
…
", "attribute": "checked" } ], "engine_verified": true, "operation_id": "updateSite", "endpoint": "POST /v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "verify": { "method": "page_fetch", "how": "POST /v1/tasks/task_…/verify", "expected": "Every listed check passes (layout checks may stay needs_review on a static fetch until the confirming scan)." }, "blocked_on": null, "closed_reason": null, "depends_on": [], "blocked_by": [], "question": { "text": "Did your subscribers choose email as the channel for account notices?", "options": [ "yes", "no" ], "why": "New York requires notices in the manner the subscriber selected; no page or email shows that choice.", "effect": "yes records the attestation (site fact notice_channel_email) and re-evaluates." }, "answer": { "value": "yes", "note": null, "answered": 1793318400, "confirmed_by_human": false, "pending_confirmation_url": null }, "decision": { "status": "wont_fix", "reason": "Annual plan retired; no subscribers left." }, "last_verification": { "id": "ver_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "status": "failed", "created": 1793318400 }, "next_action": { "type": "apply_task", "description": "Apply task_… (add the renewal terms above the Subscribe button in app/checkout/page.tsx), then call verifyTask.", "task": "task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "operation_id": "verifyTask", "mcp_tool": "verify_task", "endpoint": "POST /v1/tasks/task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/verify", "command": "checkbox fix task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "first_seen": 1793318400, "done_at": 1793318400 } ] }, "coverage": { "type": "object", "properties": { "observed": { "type": "array", "items": { "type": "string" }, "description": "Lifecycle stages Checkbox observed (signup, acknowledgment_email, reminders, cancellation, policies, billing_settings).", "example": [ "signup", "policies" ] }, "not_observed": { "type": "array", "items": { "type": "string" }, "description": "Stages Checkbox has no observation of: their checks cannot fail, so passing says nothing about them.", "example": [ "cancellation", "billing_settings" ] }, "attested": { "type": "array", "items": { "type": "string" }, "description": "Task keys resting on a human confirmation instead of an observation.", "example": [] }, "billing_connected": { "type": "boolean", "description": "A billing platform is connected (dashboard).", "example": false } }, "required": [ "observed", "not_observed", "attested", "billing_connected" ], "description": "What the assessment rests on. Tell the human about not_observed and attested items; never call the site \"compliant\" without them.", "example": { "observed": [ "signup", "policies" ], "not_observed": [ "cancellation", "billing_settings" ], "attested": [], "billing_connected": false } }, "next_action": { "$ref": "#/components/schemas/PlanNextAction" }, "rules_version": { "type": [ "string", "null" ], "description": "Rules / catalog version of the evaluation.", "example": "1.2.0" }, "disclaimer": { "type": "string", "description": "Automated assessment; not legal advice.", "example": "Checkbox checks against its legal catalog; it is not legal advice." }, "generated": { "type": "integer", "description": "When the plan was computed. Unix timestamp in seconds.", "example": 1793318400 } }, "required": [ "id", "object", "livemode", "site", "status", "score", "insurable", "evaluation", "evaluated", "summary", "counts", "tasks", "coverage", "next_action", "rules_version", "disclaimer", "generated" ], "description": "The ordered, machine-readable list of changes that makes a site compliant, recomputed from its latest evaluation." }, "UpdateTaskParams": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "open", "in_progress", "wont_fix" ], "description": "in_progress claims the task (other agents see it), wont_fix declines it (needs reason; a declined critical/high task keeps the plan from being compliant), open clears either.", "example": "in_progress" }, "reason": { "type": "string", "minLength": 3, "maxLength": 1000, "description": "Why (required for wont_fix).", "example": "This plan is no longer sold; no subscribers left." } }, "required": [ "status" ] }, "AnswerTaskParams": { "type": "object", "properties": { "answer": { "type": "string", "minLength": 2, "maxLength": 20, "description": "One of the task's question.options (yes / no, or confirmed / needs_change).", "example": "yes" }, "note": { "type": "string", "maxLength": 1000, "description": "Context from the human (stored with the attestation).", "example": "Subscribers pick email or SMS at sign-up; all current subscribers chose email." } }, "required": [ "answer" ] }, "VerificationCheck": { "type": "object", "properties": { "check_id": { "type": "string", "description": "Check id.", "example": "signup.disclosure.price" }, "expected": { "type": "string", "description": "Status the task needs.", "example": "pass" }, "observed": { "type": "string", "description": "Status observed (pass, fail, needs_review, not_applicable, unknown).", "example": "fail" }, "source": { "type": "string", "description": "Where the observation comes from: evaluation, static_fetch, html, stripe_params, email, policy_fetch.", "example": "static_fetch" }, "detail": { "type": "string", "description": "What was observed.", "example": "No recurring price near the purchase button." } }, "required": [ "check_id", "expected", "observed", "source", "detail" ], "description": "Expected vs observed for one check." }, "Verification": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the verification (ver_…).", "example": "ver_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "verification" ], "description": "String representing the object's type. Always \"verification\".", "example": "verification" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "site": { "type": "string", "description": "The site.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "task": { "type": [ "string", "null" ], "description": "The task verified (null for a whole-site verification).", "example": "task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "scope": { "type": "string", "enum": [ "task", "site" ], "description": "One task or the whole site.", "example": "task" }, "status": { "type": "string", "enum": [ "pending", "passed", "failed" ], "description": "pending (waiting for the confirming scan / re-evaluation), passed (Checkbox observed the expected result), failed (it did not: see diff).", "example": "pending" }, "method": { "type": "string", "enum": [ "page_fetch", "policy_refetch", "stripe_params", "email_copy", "platform_sync", "attestation", "evaluation", "test_run" ], "description": "How it was re-checked.", "example": "page_fetch" }, "precheck": { "type": [ "object", "null" ], "properties": { "source": { "type": "string", "description": "static_fetch, html, stripe_params, email or policy_fetch.", "example": "static_fetch" }, "verdict": { "type": "string", "enum": [ "pass", "fail", "needs_review" ], "description": "Pre-check verdict for the task's checks.", "example": "pass" }, "url": { "type": [ "string", "null" ], "description": "What was fetched.", "example": "https://shop.example/checkout" }, "note": { "type": "string", "description": "What the pre-check can and cannot confirm.", "example": "Static fetch: text checks are exact; layout is estimated until the confirming scan." } }, "required": [ "source", "verdict", "url", "note" ], "description": "The fast pre-check run immediately (seconds). A failing pre-check fails the verification at once.", "example": { "source": "static_fetch", "verdict": "pass", "url": "https://shop.example/checkout", "note": "Static fetch: text checks are exact; layout is estimated until the confirming scan." } }, "scan": { "type": [ "string", "null" ], "description": "Confirming scan queued by the verification.", "example": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/VerificationCheck" }, "description": "Expected vs observed per check.", "example": [ { "check_id": "signup.disclosure.price", "expected": "pass", "observed": "fail", "source": "static_fetch", "detail": "No recurring price near the purchase button." } ] }, "diff": { "type": "array", "items": { "$ref": "#/components/schemas/VerificationCheck" }, "description": "Only the checks whose observation differs from the expectation.", "example": [ { "check_id": "signup.disclosure.price", "expected": "pass", "observed": "fail", "source": "static_fetch", "detail": "No recurring price near the purchase button." } ] }, "plan_status": { "type": [ "string", "null" ], "enum": [ "action_required", "verifying", "compliant", "blocked" ], "description": "Plan status after this verification (null while pending).", "example": "action_required" }, "next_action": { "$ref": "#/components/schemas/PlanNextAction" }, "created": { "type": "integer", "description": "When it was requested. Unix timestamp in seconds.", "example": 1793318400 }, "completed": { "type": [ "integer", "null" ], "description": "When it resolved. Unix timestamp in seconds.", "example": 1793318400 }, "expires": { "type": "integer", "description": "A pending verification fails (timed_out) after this. Unix timestamp in seconds.", "example": 1793318400 } }, "required": [ "id", "object", "livemode", "site", "task", "scope", "status", "method", "precheck", "scan", "checks", "diff", "plan_status", "next_action", "created", "completed", "expires" ], "description": "A re-check of one task (or the whole site) after the agent applied changes." }, "VerifyTaskParams": { "type": "object", "properties": { "html": { "type": "string", "maxLength": 900000, "description": "page_fetch tasks: the rendered page HTML before you deploy, at most ~900 KB (request bodies are limited to 1 MB). Pre-check only; the confirming scan runs on the live page.", "example": "…" }, "stripe_checkout_session": { "type": "object", "additionalProperties": {}, "description": "stripe_params tasks: exactly what your code now passes to stripe.checkout.sessions.create.", "example": { "mode": "subscription", "consent_collection": { "terms_of_service": "required" } } }, "email": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "acknowledgment", "trial_reminder", "renewal_reminder", "price_change", "annual_terms", "charge_notice", "cancellation_confirmation" ], "description": "Email kind (default: from the task).", "example": "acknowledgment" }, "subject": { "type": "string", "maxLength": 500, "description": "Subject.", "example": "Welcome to Acme Pro" }, "text": { "type": "string", "maxLength": 200000, "description": "Plain-text body.", "example": "Thanks for subscribing…" }, "html": { "type": "string", "maxLength": 500000, "description": "HTML body.", "example": "

Thanks for subscribing…

" } }, "required": [ "subject" ], "description": "email_copy tasks: the new email template (pre-check; the real email confirms).", "example": { "kind": "acknowledgment", "subject": "Welcome to Acme Pro", "text": "Thanks for subscribing…", "html": "

Thanks for subscribing…

" } } } }, "VerificationList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "String representing the object's type. Always \"list\".", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Verification" }, "description": "Verifications, newest first.", "example": [ { "id": "ver_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "verification", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "task": "task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "scope": "task", "status": "pending", "method": "page_fetch", "precheck": { "source": "static_fetch", "verdict": "pass", "url": "https://shop.example/checkout", "note": "Static fetch: text checks are exact; layout is estimated until the confirming scan." }, "scan": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "checks": [ { "check_id": "signup.disclosure.price", "expected": "pass", "observed": "fail", "source": "static_fetch", "detail": "No recurring price near the purchase button." } ], "diff": [ { "check_id": "signup.disclosure.price", "expected": "pass", "observed": "fail", "source": "static_fetch", "detail": "No recurring price near the purchase button." } ], "plan_status": "action_required", "next_action": { "type": "apply_task", "description": "Apply task_… (add the renewal terms above the Subscribe button in app/checkout/page.tsx), then call verifyTask.", "task": "task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "operation_id": "verifyTask", "mcp_tool": "verify_task", "endpoint": "POST /v1/tasks/task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/verify", "command": "checkbox fix task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "created": 1793318400, "completed": 1793318400, "expires": 1793318400 } ] }, "has_more": { "type": "boolean", "description": "Whether more items exist after this page. Pass the last id as starting_after to fetch them.", "example": false }, "url": { "type": "string", "description": "The URL of this list.", "example": "/v1/sites" } }, "required": [ "object", "data", "has_more", "url" ], "description": "A page of verifications, newest first." }, "FixArtifact": { "type": "object", "properties": { "id": { "type": "string", "description": "Artifact id.", "example": "stripe-checkout-node" }, "title": { "type": "string", "description": "Title.", "example": "Stripe Checkout (Node.js)" }, "kind": { "type": "string", "enum": [ "code", "markup", "liquid", "script" ], "description": "Kind of change.", "example": "code" }, "language": { "type": "string", "description": "Language.", "example": "javascript" }, "filename": { "type": [ "string", "null" ], "description": "Suggested file.", "example": "checkout.js" }, "code": { "type": "string", "description": "The code / markup to apply.", "example": "const session = await stripe.checkout.sessions.create({ … })" }, "diff": { "type": [ "string", "null" ], "description": "Unified-diff view of the change.", "example": null } }, "required": [ "id", "title", "kind", "language", "filename", "code", "diff" ], "description": "A concrete change to apply." }, "Fix": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the fix (fix_…).", "example": "fix_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "fix" ], "description": "String representing the object's type. Always \"fix\".", "example": "fix" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "site": { "type": "string", "description": "The site.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "finding": { "type": [ "string", "null" ], "description": "Finding this fix addresses (null for site-level fix plans).", "example": "fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "group": { "type": "string", "enum": [ "signup", "cancellation", "other" ], "description": "Area of the fix.", "example": "signup" }, "kind": { "type": [ "string", "null" ], "description": "stripe_checkout, stripe_payment_link, shopify, html or hosted_cancellation.", "example": "stripe_checkout" }, "title": { "type": "string", "description": "Title.", "example": "Add the renewal disclosure to Stripe Checkout" }, "summary": { "type": "string", "description": "What the fix does.", "example": "Adds consent and terms text verified against the rules." }, "check_ids": { "type": "array", "items": { "type": "string" }, "description": "Checks it addresses.", "example": [ "signup.disclosure_clear_conspicuous" ] }, "steps": { "type": "array", "items": { "type": "string" }, "description": "Steps.", "example": [ "Replace the Checkout Session parameters with the code below" ] }, "artifacts": { "type": "array", "items": { "$ref": "#/components/schemas/FixArtifact" }, "description": "Code / markup to apply.", "example": [ { "id": "stripe-checkout-node", "title": "Stripe Checkout (Node.js)", "kind": "code", "language": "javascript", "filename": "checkout.js", "code": "const session = await stripe.checkout.sessions.create({ … })", "diff": null } ] }, "texts": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "Verified disclosure texts (snake_case keys).", "example": null }, "one_click": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "One-click option available in the dashboard, when there is one.", "example": null }, "verification": { "type": [ "object", "null" ], "additionalProperties": {}, "description": "How the engine verified the fixed texts pass the checks.", "example": null }, "problems": { "type": "array", "items": { "type": "string" }, "description": "Why parts of the fix could not be generated (e.g. plan terms unknown).", "example": [] }, "remediation": { "$ref": "#/components/schemas/Remediation" } }, "required": [ "id", "object", "livemode", "site", "finding", "group", "kind", "title", "summary", "check_ids", "steps", "artifacts", "texts", "one_click", "verification", "problems", "remediation" ], "description": "An engine-verified, platform-specific fix." }, "FixList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "String representing the object's type. Always \"list\".", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Fix" }, "description": "Fix plans.", "example": [ { "id": "fix_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "fix", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "finding": "fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "group": "signup", "kind": "stripe_checkout", "title": "Add the renewal disclosure to Stripe Checkout", "summary": "Adds consent and terms text verified against the rules.", "check_ids": [ "signup.disclosure_clear_conspicuous" ], "steps": [ "Replace the Checkout Session parameters with the code below" ], "artifacts": [ { "id": "stripe-checkout-node", "title": "Stripe Checkout (Node.js)", "kind": "code", "language": "javascript", "filename": "checkout.js", "code": "const session = await stripe.checkout.sessions.create({ … })", "diff": null } ], "texts": null, "one_click": null, "verification": null, "problems": [], "remediation": { "summary": "Show the auto-renewal terms next to the subscribe button.", "steps": [ "Add the disclosure above the button" ], "platform": "stripe", "suggested_copy": "Your subscription renews automatically every month at $9.99 until you cancel.", "snippet": { "language": "html", "code": "

…

" } } } ] }, "has_more": { "type": "boolean", "description": "Whether more items exist after this page. Pass the last id as starting_after to fetch them.", "example": false }, "url": { "type": "string", "description": "The URL of this list.", "example": "/v1/sites" } }, "required": [ "object", "data", "has_more", "url" ], "description": "A page of fix plans." }, "Evidence": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the evidence (ev_…).", "example": "ev_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "evidence" ], "description": "String representing the object's type. Always \"evidence\".", "example": "evidence" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "site": { "type": "string", "description": "Site the evidence belongs to.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "kind": { "type": "string", "enum": [ "screenshot", "html", "page_capture", "email_raw", "platform_config", "lifecycle_event", "evaluation" ], "description": "What was recorded.", "example": "screenshot" }, "content_type": { "type": "string", "description": "MIME type of the content.", "example": "image/png" }, "size": { "type": "integer", "description": "Bytes.", "example": 183204 }, "sha256": { "type": "string", "description": "SHA-256 of the content (hex).", "example": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" }, "chain_hash": { "type": "string", "description": "Hash chaining this record to the previous one (tamper evidence).", "example": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" }, "prev_chain_hash": { "type": [ "string", "null" ], "description": "Chain hash of the previous record.", "example": null }, "stored": { "type": "integer", "description": "When it was stored. Unix timestamp in seconds.", "example": 1793318400 }, "meta": { "type": "object", "additionalProperties": {}, "description": "Capture metadata (URL, region, device, scan…).", "example": { "url": "https://acme.example/pricing", "region": "US-CA" } }, "content_url": { "type": "string", "description": "Download the raw content (downloadEvidenceContent, same auth).", "example": "/v1/evidence/ev_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/content" } }, "required": [ "id", "object", "livemode", "site", "kind", "content_type", "size", "sha256", "chain_hash", "prev_chain_hash", "stored", "meta", "content_url" ], "description": "A record in the tamper-evident evidence vault." }, "EvidenceList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "String representing the object's type. Always \"list\".", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Evidence" }, "description": "Evidence records, newest first.", "example": [ { "id": "ev_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "evidence", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "kind": "screenshot", "content_type": "image/png", "size": 183204, "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "chain_hash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "prev_chain_hash": null, "stored": 1793318400, "meta": { "url": "https://acme.example/pricing", "region": "US-CA" }, "content_url": "/v1/evidence/ev_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/content" } ] }, "has_more": { "type": "boolean", "description": "Whether more items exist after this page. Pass the last id as starting_after to fetch them.", "example": false }, "url": { "type": "string", "description": "The URL of this list.", "example": "/v1/sites" } }, "required": [ "object", "data", "has_more", "url" ], "description": "A page of evidence records, newest first." }, "EvidenceChainVerification": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "evidence_chain_verification" ], "description": "String representing the object's type. Always \"evidence_chain_verification\".", "example": "evidence_chain_verification" }, "site": { "type": "string", "description": "Verified site.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "ok": { "type": "boolean", "description": "Every record re-hashed and the chain is intact.", "example": true }, "checked": { "type": "integer", "description": "Records checked.", "example": 128 }, "broken_at": { "type": [ "string", "null" ], "description": "Id of the first record that failed verification.", "example": null }, "reason": { "type": [ "string", "null" ], "description": "Why verification failed.", "example": null }, "head": { "type": [ "string", "null" ], "description": "Current chain head hash.", "example": "9f86d0…" } }, "required": [ "object", "site", "ok", "checked", "broken_at", "reason", "head" ], "description": "Result of re-hashing a site's evidence chain." }, "Certificate": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the certificate (cert_…).", "example": "cert_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "certificate" ], "description": "String representing the object's type. Always \"certificate\".", "example": "certificate" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "site": { "type": "string", "description": "Certified site.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "status": { "type": "string", "enum": [ "active", "lapsed", "revoked", "superseded" ], "description": "active while monitoring keeps the site insurable; lapses automatically otherwise.", "example": "active" }, "domain": { "type": "string", "description": "Verified domain frozen into the certificate.", "example": "acme.example" }, "issued": { "type": "integer", "description": "Issue time. Unix timestamp in seconds.", "example": 1793318400 }, "valid_until": { "type": "integer", "description": "Expiry (renewed automatically while compliant). Unix timestamp in seconds.", "example": 1793318400 }, "renewed": { "type": [ "integer", "null" ], "description": "Last renewal. Unix timestamp in seconds.", "example": 1793318400 }, "ended": { "type": [ "integer", "null" ], "description": "When it lapsed or was revoked. Unix timestamp in seconds.", "example": 1793318400 }, "public_reason": { "type": [ "string", "null" ], "description": "Public reason code shown on the verification page when it ended.", "example": null }, "verify_url": { "type": "string", "description": "Public verification page.", "example": "https://app.checkbox.site/verify/SC-7Q2K-9M4X" }, "badge": { "type": "object", "properties": { "svg_url": { "type": "string", "description": "Badge image.", "example": "https://app.checkbox.site/badge/SC-7Q2K-9M4X.svg" }, "script_url": { "type": "string", "description": "Badge script.", "example": "https://app.checkbox.site/badge/SC-7Q2K-9M4X.js" }, "embed_html": { "type": "string", "description": "HTML to embed the badge.", "example": "\"…\"" } }, "required": [ "svg_url", "script_url", "embed_html" ], "description": "Trust badge for the merchant site.", "example": { "svg_url": "https://app.checkbox.site/badge/SC-7Q2K-9M4X.svg", "script_url": "https://app.checkbox.site/badge/SC-7Q2K-9M4X.js", "embed_html": "\"…\"" } } }, "required": [ "id", "object", "livemode", "site", "status", "domain", "issued", "valid_until", "renewed", "ended", "public_reason", "verify_url", "badge" ], "description": "A signed monitoring certificate: the site met every critical and high obligation for the required streak of days. It is not insurance." }, "CertificateList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "String representing the object's type. Always \"list\".", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Certificate" }, "description": "Certificates, newest first.", "example": [ { "id": "cert_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "certificate", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "status": "active", "domain": "acme.example", "issued": 1793318400, "valid_until": 1793318400, "renewed": 1793318400, "ended": 1793318400, "public_reason": null, "verify_url": "https://app.checkbox.site/verify/SC-7Q2K-9M4X", "badge": { "svg_url": "https://app.checkbox.site/badge/SC-7Q2K-9M4X.svg", "script_url": "https://app.checkbox.site/badge/SC-7Q2K-9M4X.js", "embed_html": "\"…\"" } } ] }, "has_more": { "type": "boolean", "description": "Whether more items exist after this page. Pass the last id as starting_after to fetch them.", "example": false }, "url": { "type": "string", "description": "The URL of this list.", "example": "/v1/sites" } }, "required": [ "object", "data", "has_more", "url" ], "description": "A page of certificates, newest first." }, "NoticeSettings": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the notice settings (ntcs_…).", "example": "ntcs_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "notice_settings" ], "description": "String representing the object's type. Always \"notice_settings\".", "example": "notice_settings" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "site": { "type": "string", "description": "The site.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "enabled_kinds": { "type": "array", "items": { "type": "string", "enum": [ "acknowledgment", "trial_ending", "renewal_reminder", "annual_terms", "price_change" ] }, "description": "Notices Checkbox sends for the merchant.", "example": [ "acknowledgment", "renewal_reminder" ] }, "brand_name": { "type": [ "string", "null" ], "description": "Brand shown in notices (defaults to the site name).", "example": "Acme Coffee Club" }, "product_name": { "type": [ "string", "null" ], "description": "Product name used in notices.", "example": "Coffee subscription" }, "logo_url": { "type": [ "string", "null" ], "description": "Logo URL (https).", "example": null }, "support_email": { "type": [ "string", "null" ], "description": "Reply-to / support address.", "example": "help@acme.example" }, "cancel_url": { "type": [ "string", "null" ], "description": "Where subscribers cancel online (site domain, hosted cancellation page or billing portal).", "example": "https://acme.example/account/cancel" }, "brand_color": { "type": [ "string", "null" ], "description": "Hex brand colour.", "example": "#1f2937" }, "from_local_part": { "type": "string", "description": "Mailbox name of the sender.", "example": "notices" }, "policy": { "type": [ "object", "null" ], "properties": { "cancel_timing": { "type": "string", "enum": [ "period_end", "immediately" ], "description": "When a cancellation takes effect.", "example": "period_end" }, "confirmed": { "type": "integer", "description": "When the policy was confirmed. Unix timestamp in seconds.", "example": 1793318400 } }, "required": [ "cancel_timing", "confirmed" ], "description": "Confirmed cancellation policy (required before notices go out).", "example": { "cancel_timing": "period_end", "confirmed": 1793318400 } }, "sender": { "type": [ "object", "null" ], "properties": { "from": { "type": "string", "description": "From header.", "example": "Acme Coffee Club " }, "own_domain": { "type": "boolean", "description": "Sent from the merchant's verified domain.", "example": true } }, "required": [ "from", "own_domain" ], "description": "Sending address, when one is available.", "example": { "from": "Acme Coffee Club ", "own_domain": true } }, "sending_domain": { "type": "object", "properties": { "domain": { "type": [ "string", "null" ], "description": "Custom sending domain.", "example": "acme.example" }, "status": { "type": "string", "description": "none, pending, verified or failed.", "example": "verified" } }, "required": [ "domain", "status" ], "description": "Custom sending domain status (set it up in the dashboard).", "example": { "domain": "acme.example", "status": "verified" } }, "delivery_configured": { "type": "boolean", "description": "This Checkbox deployment can send email.", "example": true }, "kinds": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "acknowledgment", "trial_ending", "renewal_reminder", "annual_terms", "price_change" ], "description": "Notice kind.", "example": "renewal_reminder" }, "label": { "type": "string", "description": "Label.", "example": "Renewal reminder" }, "description": { "type": "string", "description": "What it is and when it is sent.", "example": "Sent before an annual renewal." }, "enabled": { "type": "boolean", "description": "Checkbox sends it.", "example": true }, "check_ids": { "type": "array", "items": { "type": "string" }, "description": "Legal checks it satisfies.", "example": [ "reminder.annual_renewal_notice" ] } }, "required": [ "kind", "label", "description", "enabled", "check_ids" ] }, "description": "Every notice kind.", "example": [ { "kind": "renewal_reminder", "label": "Renewal reminder", "description": "Sent before an annual renewal.", "enabled": true, "check_ids": [ "reminder.annual_renewal_notice" ] } ] }, "updated": { "type": [ "integer", "null" ], "description": "Last change. Unix timestamp in seconds.", "example": 1793318400 }, "next_action": { "allOf": [ { "$ref": "#/components/schemas/NextAction" }, { "type": [ "object", "null" ], "description": "What to do next; null when nothing is needed." } ], "example": { "type": "verify_domain", "message": "Verify your site domain to turn on live mode.", "operation_id": "createDomainVerification", "mcp_tool": "call_api", "url": "https://checkbox.site/docs/api/activation" } } }, "required": [ "id", "object", "livemode", "site", "enabled_kinds", "brand_name", "product_name", "logo_url", "support_email", "cancel_url", "brand_color", "from_local_part", "policy", "sender", "sending_domain", "delivery_configured", "kinds", "updated", "next_action" ], "description": "Checkbox Notices for a site: the legally required emails Checkbox sends on the merchant's behalf." }, "UpdateNoticeSettingsParams": { "type": "object", "properties": { "enabled_kinds": { "type": "array", "items": { "type": "string", "enum": [ "acknowledgment", "trial_ending", "renewal_reminder", "annual_terms", "price_change", "trial_reminder" ] }, "description": "Notices to send (turning one on needs cancel_url, a confirmed policy and a connected Stripe/Recharge account). trial_reminder is accepted as an alias of trial_ending.", "example": [ "acknowledgment", "renewal_reminder" ] }, "brand_name": { "type": [ "string", "null" ], "maxLength": 100, "description": "Brand name.", "example": "Acme Coffee Club" }, "product_name": { "type": [ "string", "null" ], "maxLength": 100, "description": "Product name.", "example": "Coffee subscription" }, "logo_url": { "type": [ "string", "null" ], "maxLength": 500, "description": "Logo URL (https).", "example": "https://acme.example/logo.png" }, "support_email": { "type": [ "string", "null" ], "maxLength": 320, "description": "Support address.", "example": "help@acme.example" }, "cancel_url": { "type": [ "string", "null" ], "maxLength": 500, "description": "Online cancellation URL.", "example": "https://acme.example/account/cancel" }, "brand_color": { "type": [ "string", "null" ], "maxLength": 7, "description": "Hex colour.", "example": "#1f2937" }, "from_local_part": { "type": "string", "maxLength": 41, "description": "Sender mailbox name.", "example": "notices" }, "policy": { "type": [ "object", "null" ], "properties": { "cancel_timing": { "type": "string", "enum": [ "period_end", "immediately" ], "description": "When a cancellation takes effect (must match your Terms).", "example": "period_end" }, "confirm": { "type": "boolean", "enum": [ true ], "description": "Confirms this matches your Terms and your cancellation flow.", "example": true } }, "required": [ "cancel_timing", "confirm" ], "description": "Cancellation policy the notices state.", "example": { "cancel_timing": "period_end", "confirm": true } } } }, "LawChange": { "type": "object", "properties": { "requirement_id": { "type": "string", "description": "Requirement id in the legal catalog.", "example": "US-NY.527-a.1" }, "change": { "type": "string", "description": "added, removed, modified, effective or sunset.", "example": "effective" }, "jurisdiction": { "type": "string", "enum": [ "US-FED", "US-AL", "US-AK", "US-AZ", "US-AR", "US-CA", "US-CO", "US-CT", "US-DE", "US-DC", "US-FL", "US-GA", "US-HI", "US-ID", "US-IL", "US-IN", "US-IA", "US-KS", "US-KY", "US-LA", "US-ME", "US-MD", "US-MA", "US-MI", "US-MN", "US-MS", "US-MO", "US-MT", "US-NE", "US-NV", "US-NH", "US-NJ", "US-NM", "US-NY", "US-NC", "US-ND", "US-OH", "US-OK", "US-OR", "US-PA", "US-RI", "US-SC", "US-SD", "US-TN", "US-TX", "US-UT", "US-VT", "US-VA", "US-WA", "US-WV", "US-WI", "US-WY" ], "description": "Jurisdiction.", "example": "US-NY" }, "citation": { "type": "string", "description": "Legal citation.", "example": "N.Y. Gen. Bus. Law § 527-a" }, "title": { "type": "string", "description": "Requirement title.", "example": "Online cancellation" }, "summary": { "type": [ "string", "null" ], "description": "Plain-English summary.", "example": null }, "effective_date": { "type": [ "string", "null" ], "description": "Effective date (YYYY-MM-DD).", "example": "2026-11-01" }, "sunset_date": { "type": [ "string", "null" ], "description": "Sunset date (YYYY-MM-DD).", "example": null }, "source_url": { "type": [ "string", "null" ], "description": "Official source.", "example": "https://www.nysenate.gov/legislation/laws/GBS/527-A" } }, "required": [ "requirement_id", "change", "jurisdiction", "citation", "title", "summary", "effective_date", "sunset_date", "source_url" ], "description": "One changed requirement." }, "LawSiteImpact": { "type": "object", "properties": { "site": { "type": "string", "description": "Affected site.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "summary": { "type": "string", "description": "What changed for the site.", "example": "1 check now fails under the new rule." }, "score_before": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "Score before the change (0-100, one decimal place).", "example": 90 }, "score_after": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "Score after re-evaluation (0-100, one decimal place).", "example": 84 }, "affected_checks": { "type": "array", "items": { "type": "object", "properties": { "check_id": { "type": "string", "description": "Check id.", "example": "cancellation.online_cancel_available" }, "title": { "type": "string", "description": "Title.", "example": "Customers can cancel online" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ], "description": "Severity.", "example": "critical" }, "before": { "type": [ "string", "null" ], "enum": [ "pass", "fail", "needs_review", "not_applicable" ], "description": "Status before.", "example": "pass" }, "after": { "type": [ "string", "null" ], "enum": [ "pass", "fail", "needs_review", "not_applicable" ], "description": "Status after.", "example": "fail" } }, "required": [ "check_id", "title", "severity", "before", "after" ] }, "description": "Checks whose result changed or that the change touches.", "example": [ { "check_id": "cancellation.online_cancel_available", "title": "Customers can cancel online", "severity": "critical", "before": "pass", "after": "fail" } ] }, "evaluated": { "type": "integer", "description": "When the site was re-evaluated. Unix timestamp in seconds.", "example": 1793318400 } }, "required": [ "site", "summary", "score_before", "score_after", "affected_checks", "evaluated" ], "description": "How a law change affected one site." }, "LawUpdate": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the law update (law_…).", "example": "law_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "law_update" ], "description": "String representing the object's type. Always \"law_update\".", "example": "law_update" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "source": { "type": "string", "enum": [ "catalog_change", "effective", "sunset" ], "description": "catalog_change: Checkbox updated the legal catalog; effective / sunset: a dated rule started or ended.", "example": "effective" }, "date": { "type": "string", "description": "Date of the change (YYYY-MM-DD).", "example": "2026-11-01" }, "summary": { "type": "string", "description": "What changed.", "example": "New York online-cancellation rule takes effect." }, "jurisdictions": { "type": "array", "items": { "type": "string", "enum": [ "US-FED", "US-AL", "US-AK", "US-AZ", "US-AR", "US-CA", "US-CO", "US-CT", "US-DE", "US-DC", "US-FL", "US-GA", "US-HI", "US-ID", "US-IL", "US-IN", "US-IA", "US-KS", "US-KY", "US-LA", "US-ME", "US-MD", "US-MA", "US-MI", "US-MN", "US-MS", "US-MO", "US-MT", "US-NE", "US-NV", "US-NH", "US-NJ", "US-NM", "US-NY", "US-NC", "US-ND", "US-OH", "US-OK", "US-OR", "US-PA", "US-RI", "US-SC", "US-SD", "US-TN", "US-TX", "US-UT", "US-VT", "US-VA", "US-WA", "US-WV", "US-WI", "US-WY" ] }, "description": "Jurisdictions changed.", "example": [ "US-NY" ] }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/LawChange" }, "description": "Changed requirements.", "example": [ { "requirement_id": "US-NY.527-a.1", "change": "effective", "jurisdiction": "US-NY", "citation": "N.Y. Gen. Bus. Law § 527-a", "title": "Online cancellation", "summary": null, "effective_date": "2026-11-01", "sunset_date": null, "source_url": "https://www.nysenate.gov/legislation/laws/GBS/527-A" } ] }, "impacts": { "type": "array", "items": { "$ref": "#/components/schemas/LawSiteImpact" }, "description": "Effects on this account's sites (in this mode).", "example": [ { "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "summary": "1 check now fails under the new rule.", "score_before": 90, "score_after": 84, "affected_checks": [ { "check_id": "cancellation.online_cancel_available", "title": "Customers can cancel online", "severity": "critical", "before": "pass", "after": "fail" } ], "evaluated": 1793318400 } ] }, "created": { "type": "integer", "description": "When Checkbox recorded the change. Unix timestamp in seconds.", "example": 1793318400 } }, "required": [ "id", "object", "livemode", "source", "date", "summary", "jurisdictions", "changes", "impacts", "created" ], "description": "A change in the law Checkbox applies, and its effect on your sites." }, "LawUpdateList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "String representing the object's type. Always \"list\".", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LawUpdate" }, "description": "Law updates, newest first.", "example": [ { "id": "law_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "law_update", "livemode": false, "source": "effective", "date": "2026-11-01", "summary": "New York online-cancellation rule takes effect.", "jurisdictions": [ "US-NY" ], "changes": [ { "requirement_id": "US-NY.527-a.1", "change": "effective", "jurisdiction": "US-NY", "citation": "N.Y. Gen. Bus. Law § 527-a", "title": "Online cancellation", "summary": null, "effective_date": "2026-11-01", "sunset_date": null, "source_url": "https://www.nysenate.gov/legislation/laws/GBS/527-A" } ], "impacts": [ { "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "summary": "1 check now fails under the new rule.", "score_before": 90, "score_after": 84, "affected_checks": [ { "check_id": "cancellation.online_cancel_available", "title": "Customers can cancel online", "severity": "critical", "before": "pass", "after": "fail" } ], "evaluated": 1793318400 } ], "created": 1793318400 } ] }, "has_more": { "type": "boolean", "description": "Whether more items exist after this page. Pass the last id as starting_after to fetch them.", "example": false }, "url": { "type": "string", "description": "The URL of this list.", "example": "/v1/sites" } }, "required": [ "object", "data", "has_more", "url" ], "description": "A page of law updates, newest first." }, "CheckRequirementRef": { "type": "object", "properties": { "id": { "type": "string", "description": "Requirement id in the legal catalog.", "example": "US-CA.17602.a.1" }, "jurisdiction": { "type": "string", "enum": [ "US-FED", "US-AL", "US-AK", "US-AZ", "US-AR", "US-CA", "US-CO", "US-CT", "US-DE", "US-DC", "US-FL", "US-GA", "US-HI", "US-ID", "US-IL", "US-IN", "US-IA", "US-KS", "US-KY", "US-LA", "US-ME", "US-MD", "US-MA", "US-MI", "US-MN", "US-MS", "US-MO", "US-MT", "US-NE", "US-NV", "US-NH", "US-NJ", "US-NM", "US-NY", "US-NC", "US-ND", "US-OH", "US-OK", "US-OR", "US-PA", "US-RI", "US-SC", "US-SD", "US-TN", "US-TX", "US-UT", "US-VT", "US-VA", "US-WA", "US-WV", "US-WI", "US-WY" ], "description": "Jurisdiction.", "example": "US-CA" }, "citation": { "type": "string", "description": "Legal citation.", "example": "Cal. Bus. & Prof. Code § 17602(a)(1)" }, "title": { "type": "string", "description": "Requirement title.", "example": "Clear and conspicuous disclosure of automatic renewal offer terms" }, "source_url": { "type": "string", "description": "Official source.", "example": "https://leginfo.legislature.ca.gov/" } }, "required": [ "id", "jurisdiction", "citation", "title", "source_url" ], "description": "A legal requirement a check enforces." }, "CheckVerdict": { "type": "object", "properties": { "check_id": { "type": "string", "description": "Stable id of the check.", "example": "signup.disclosure.price" }, "status": { "type": "string", "enum": [ "pass", "fail", "needs_review", "not_applicable" ], "description": "pass, fail, needs_review (a human or more data must decide) or not_applicable.", "example": "fail" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ], "description": "Severity.", "example": "critical" }, "title": { "type": "string", "description": "What the check requires.", "example": "Discloses the recurring charge amount" }, "explanation": { "type": "string", "description": "What the engine observed.", "example": "The recurring charge amount is not stated in the terms next to the purchase button." }, "confidence": { "type": "number", "description": "Confidence 0..1.", "example": 0.85 }, "requirements": { "type": "array", "items": { "$ref": "#/components/schemas/CheckRequirementRef" }, "description": "Requirements this check enforces under the requested jurisdictions.", "example": [ { "id": "US-CA.17602.a.1", "jurisdiction": "US-CA", "citation": "Cal. Bus. & Prof. Code § 17602(a)(1)", "title": "Clear and conspicuous disclosure of automatic renewal offer terms", "source_url": "https://leginfo.legislature.ca.gov/" } ] }, "fix": { "type": "string", "description": "How to fix a failing / unclear check.", "example": "Show the recurring charge amount in the terms next to the purchase button." }, "static_estimate": { "type": "string", "enum": [ "pass", "fail", "needs_review", "not_applicable" ], "description": "Page checks on static HTML: the engine status on the estimated layout.", "example": "pass" } }, "required": [ "check_id", "status", "severity", "title", "explanation", "confidence", "requirements" ], "description": "One engine check and its verdict." }, "CheckRequirementVerdict": { "allOf": [ { "$ref": "#/components/schemas/CheckRequirementRef" }, { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pass", "fail", "needs_review", "not_applicable" ], "description": "Worst status among the requirement’s checks.", "example": "fail" }, "check_ids": { "type": "array", "items": { "type": "string" }, "description": "Checks that enforce it.", "example": [ "signup.disclosure.price" ] } }, "required": [ "status", "check_ids" ] } ], "description": "Verdict per legal requirement." }, "CheckWarning": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable warning code.", "example": "stripe_tos_url_required" }, "message": { "type": "string", "description": "Explanation.", "example": "consent_collection.terms_of_service needs a Terms of Service URL in Stripe." }, "param": { "type": "string", "description": "Related parameter.", "example": "params.consent_collection" } }, "required": [ "code", "message" ], "description": "A note about the input (never a compliance verdict)." }, "CheckReplacement": { "type": "object", "properties": { "disclosure_text": { "type": "string", "description": "Compliant disclosure generated from the plan terms (locked wording).", "example": "Your Joybox subscription automatically renews every month at $19.99 …" }, "consent_label": { "type": "string", "description": "Label for the unchecked, required consent checkbox.", "example": "I agree that my Joybox subscription renews automatically …" }, "button_text": { "type": "string", "description": "Purchase button label that itself states the renewal.", "example": "Subscribe — $19.99/month, renews automatically" }, "html": { "type": "string", "description": "Drop-in markup: disclosure (set off in a box) + unchecked required checkbox + button.", "example": "
…
" }, "placeholders": { "type": "array", "items": { "type": "string" }, "description": "Placeholders left to fill (e.g. {{cancel_url}}).", "example": [ "{{cancel_url}}" ] }, "verified": { "type": "boolean", "description": "The engine passes every targeted sign-up check on a page using this replacement.", "example": true }, "remaining_checks": { "type": "array", "items": { "type": "string" }, "description": "Targeted checks that still do not pass with it (normally empty).", "example": [] }, "sha256": { "type": "string", "description": "sha256 of disclosure + consent label.", "example": "3e49…" } }, "required": [ "disclosure_text", "consent_label", "button_text", "html", "placeholders", "verified", "remaining_checks", "sha256" ], "description": "A compliant replacement, verified by the engine." }, "DisclosureCheckResult": { "type": "object", "properties": { "id": { "type": "string", "description": "Id of this check run (chk_…). Checks are stateless and not stored.", "example": "chk_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "check_result" ], "description": "String representing the object's type. Always \"check_result\".", "example": "check_result" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "created": { "type": "integer", "description": "When the check ran. Unix timestamp in seconds.", "example": 1793318400 }, "kind": { "type": "string", "enum": [ "disclosure", "stripe_checkout_session", "stripe_payment_link", "email", "page" ], "description": "Which check ran.", "example": "disclosure" }, "verdict": { "type": "string", "enum": [ "pass", "fail", "needs_review", "not_applicable" ], "description": "Overall: fail if any check fails, else needs_review if any needs review, else pass (not_applicable when nothing applies).", "example": "fail" }, "summary": { "type": "object", "properties": { "pass": { "type": "integer", "description": "Checks passing.", "example": 6 }, "fail": { "type": "integer", "description": "Checks failing.", "example": 2 }, "needs_review": { "type": "integer", "description": "Checks needing review.", "example": 1 }, "not_applicable": { "type": "integer", "description": "Checks not applicable.", "example": 1 } }, "required": [ "pass", "fail", "needs_review", "not_applicable" ], "description": "Counts by status.", "example": { "pass": 6, "fail": 2, "needs_review": 1, "not_applicable": 1 } }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/CheckVerdict" }, "description": "Every evaluated check.", "example": [ { "check_id": "signup.disclosure.price", "status": "fail", "severity": "critical", "title": "Discloses the recurring charge amount", "explanation": "The recurring charge amount is not stated in the terms next to the purchase button.", "confidence": 0.85, "requirements": [ { "id": "US-CA.17602.a.1", "jurisdiction": "US-CA", "citation": "Cal. Bus. & Prof. Code § 17602(a)(1)", "title": "Clear and conspicuous disclosure of automatic renewal offer terms", "source_url": "https://leginfo.legislature.ca.gov/" } ], "fix": "Show the recurring charge amount in the terms next to the purchase button.", "static_estimate": "pass" } ] }, "requirements": { "type": "array", "items": { "$ref": "#/components/schemas/CheckRequirementVerdict" }, "description": "Verdict per legal requirement (federal first, then by state).", "example": [ { "id": "US-CA.17602.a.1", "jurisdiction": "US-CA", "citation": "Cal. Bus. & Prof. Code § 17602(a)(1)", "title": "Clear and conspicuous disclosure of automatic renewal offer terms", "source_url": "https://leginfo.legislature.ca.gov/" } ] }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/CheckWarning" }, "description": "Notes about the input.", "example": [ { "code": "stripe_tos_url_required", "message": "consent_collection.terms_of_service needs a Terms of Service URL in Stripe.", "param": "params.consent_collection" } ] }, "jurisdictions": { "anyOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "array", "items": { "type": "string", "enum": [ "US-FED", "US-AL", "US-AK", "US-AZ", "US-AR", "US-CA", "US-CO", "US-CT", "US-DE", "US-DC", "US-FL", "US-GA", "US-HI", "US-ID", "US-IL", "US-IN", "US-IA", "US-KS", "US-KY", "US-LA", "US-ME", "US-MD", "US-MA", "US-MI", "US-MN", "US-MS", "US-MO", "US-MT", "US-NE", "US-NV", "US-NH", "US-NJ", "US-NM", "US-NY", "US-NC", "US-ND", "US-OH", "US-OK", "US-OR", "US-PA", "US-RI", "US-SC", "US-SD", "US-TN", "US-TX", "US-UT", "US-VT", "US-VA", "US-WA", "US-WV", "US-WI", "US-WY" ] } } ], "description": "Jurisdictions evaluated.", "example": "all" }, "as_of": { "type": "string", "description": "Date the law was evaluated at.", "example": "2026-10-30" }, "rules_version": { "type": "string", "description": "Version of the check implementations.", "example": "1.2.0" }, "catalog_version": { "type": "string", "description": "Version of the legal catalog.", "example": "2026.10.30.1" }, "catalog_hash": { "type": "string", "description": "sha256 of the canonical legal catalog.", "example": "b1c2…" }, "disclaimer": { "type": "string", "description": "Not legal advice.", "example": "Automated compliance check … not legal advice." }, "next_action": { "$ref": "#/components/schemas/NextAction" }, "replacement": { "$ref": "#/components/schemas/CheckReplacement" } }, "required": [ "id", "object", "livemode", "created", "kind", "verdict", "summary", "checks", "requirements", "warnings", "jurisdictions", "as_of", "rules_version", "catalog_version", "catalog_hash", "disclaimer", "next_action", "replacement" ], "description": "Verdict on a checkout disclosure plus a verified replacement." }, "DisclosureCheckParams": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 5000, "description": "The disclosure shown next to the purchase button, exactly as rendered.", "example": "Your subscription renews automatically every month at $19.99 until you cancel. Cancel anytime online at https://joybox.example/account/cancel." }, "merchant_name": { "type": "string", "maxLength": 200, "description": "Brand shown to subscribers; used in generated text.", "example": "Joybox" }, "plan_name": { "type": "string", "maxLength": 200, "description": "Plan / product name.", "example": "Pro" }, "price": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "string", "maxLength": 40 } ], "description": "Recurring price in major units (19.99). Or give `amount` in minor units.", "example": 19.99 }, "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Recurring price in minor units (1999 = $19.99), Stripe style.", "example": 1999 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO currency (default usd).", "example": "usd" }, "interval": { "type": "string", "maxLength": 20, "description": "Billing interval: day, week, month or year (required).", "example": "month" }, "interval_count": { "type": "integer", "minimum": 1, "maximum": 36, "description": "Number of intervals between charges (default 1).", "example": 1 }, "trial_days": { "type": "integer", "minimum": 0, "maximum": 730, "description": "Free-trial length in days (0 or absent = no trial).", "example": 14 }, "cancel_url": { "type": "string", "maxLength": 2048, "description": "https URL where subscribers cancel online (used in generated text; a {{cancel_url}} placeholder otherwise).", "example": "https://joybox.example/account/cancel" }, "cancel_timing": { "type": "string", "enum": [ "period_end", "immediately" ], "description": "When a cancellation takes effect (default period_end).", "example": "period_end" }, "button_text": { "type": "string", "maxLength": 200, "description": "Label of the purchase button (default \"Subscribe\", or \"Start free trial\" with a trial).", "example": "Subscribe" }, "order_summary": { "type": "string", "maxLength": 1000, "description": "Other text next to the button (order summary), if any.", "example": "Pro plan — $19.99/month" }, "jurisdictions": { "anyOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "array", "items": { "type": "string", "maxLength": 10 }, "maxItems": 60 } ], "description": "Where you sell: \"all\" (default) or state codes (\"US-CA\", \"CA\", \"US-NY\"; \"US-FED\" is always included).", "example": [ "US-CA", "US-NY" ] }, "placement": { "type": "object", "properties": { "above_button": { "type": "boolean", "description": "The disclosure is shown before / above the purchase button (default true).", "example": true }, "same_page_as_payment": { "type": "boolean", "description": "The disclosure is on the same page as the payment form and button (default true).", "example": true }, "font_size_px": { "type": "number", "minimum": 4, "maximum": 96, "description": "Rendered font size of the disclosure (default 14).", "example": 14 }, "contrast_ratio": { "type": "number", "minimum": 1, "maximum": 21, "description": "WCAG contrast ratio of the text against its background (default ≈14.7).", "example": 7 }, "bold": { "type": "boolean", "description": "The disclosure is bold / semibold.", "example": true }, "boxed": { "type": "boolean", "description": "The disclosure is set off in a bordered or shaded box.", "example": true }, "body_font_size_px": { "type": "number", "minimum": 4, "maximum": 96, "description": "Font size of the surrounding body text (default 14).", "example": 14 } }, "description": "Where and how the disclosure is shown.", "example": { "above_button": true, "same_page_as_payment": true, "font_size_px": 14, "contrast_ratio": 7, "bold": true, "boxed": true, "body_font_size_px": 14 } }, "consent": { "type": "object", "properties": { "checkbox": { "type": "boolean", "description": "A checkbox the customer must tick to agree to the renewal terms.", "example": true }, "prechecked": { "type": "boolean", "description": "The checkbox is ticked by default.", "example": false }, "label": { "type": "string", "maxLength": 1000, "description": "The checkbox label (default \"I agree to the automatic renewal terms above.\").", "example": "I agree to the automatic renewal terms above." }, "required": { "type": "boolean", "description": "The form cannot be submitted without ticking it (default true).", "example": true } }, "required": [ "checkbox" ], "description": "The consent checkbox, if any. Omitted = no checkbox.", "example": { "checkbox": true, "prechecked": false, "label": "I agree to the automatic renewal terms above.", "required": true } }, "as_of": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Evaluate the law as of this date (YYYY-MM-DD, default today).", "example": "2026-10-30" } }, "required": [ "text", "interval" ], "description": "A checkout disclosure to check before it ships." }, "JsonPatchOperation": { "type": "object", "properties": { "op": { "type": "string", "enum": [ "add", "replace", "remove" ], "description": "JSON Patch operation.", "example": "add" }, "path": { "type": "string", "description": "JSON Pointer into params.", "example": "/consent_collection" }, "value": { "description": "Value to set.", "example": { "terms_of_service": "required" } } }, "required": [ "op", "path" ], "description": "RFC 6902 operation." }, "StripeCheckoutSessionCheckResult": { "type": "object", "properties": { "id": { "type": "string", "description": "Id of this check run (chk_…). Checks are stateless and not stored.", "example": "chk_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "check_result" ], "description": "String representing the object's type. Always \"check_result\".", "example": "check_result" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "created": { "type": "integer", "description": "When the check ran. Unix timestamp in seconds.", "example": 1793318400 }, "kind": { "type": "string", "enum": [ "disclosure", "stripe_checkout_session", "stripe_payment_link", "email", "page" ], "description": "Which check ran.", "example": "disclosure" }, "verdict": { "type": "string", "enum": [ "pass", "fail", "needs_review", "not_applicable" ], "description": "Overall: fail if any check fails, else needs_review if any needs review, else pass (not_applicable when nothing applies).", "example": "fail" }, "summary": { "type": "object", "properties": { "pass": { "type": "integer", "description": "Checks passing.", "example": 6 }, "fail": { "type": "integer", "description": "Checks failing.", "example": 2 }, "needs_review": { "type": "integer", "description": "Checks needing review.", "example": 1 }, "not_applicable": { "type": "integer", "description": "Checks not applicable.", "example": 1 } }, "required": [ "pass", "fail", "needs_review", "not_applicable" ], "description": "Counts by status.", "example": { "pass": 6, "fail": 2, "needs_review": 1, "not_applicable": 1 } }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/CheckVerdict" }, "description": "Every evaluated check.", "example": [ { "check_id": "signup.disclosure.price", "status": "fail", "severity": "critical", "title": "Discloses the recurring charge amount", "explanation": "The recurring charge amount is not stated in the terms next to the purchase button.", "confidence": 0.85, "requirements": [ { "id": "US-CA.17602.a.1", "jurisdiction": "US-CA", "citation": "Cal. Bus. & Prof. Code § 17602(a)(1)", "title": "Clear and conspicuous disclosure of automatic renewal offer terms", "source_url": "https://leginfo.legislature.ca.gov/" } ], "fix": "Show the recurring charge amount in the terms next to the purchase button.", "static_estimate": "pass" } ] }, "requirements": { "type": "array", "items": { "$ref": "#/components/schemas/CheckRequirementVerdict" }, "description": "Verdict per legal requirement (federal first, then by state).", "example": [ { "id": "US-CA.17602.a.1", "jurisdiction": "US-CA", "citation": "Cal. Bus. & Prof. Code § 17602(a)(1)", "title": "Clear and conspicuous disclosure of automatic renewal offer terms", "source_url": "https://leginfo.legislature.ca.gov/" } ] }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/CheckWarning" }, "description": "Notes about the input.", "example": [ { "code": "stripe_tos_url_required", "message": "consent_collection.terms_of_service needs a Terms of Service URL in Stripe.", "param": "params.consent_collection" } ] }, "jurisdictions": { "anyOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "array", "items": { "type": "string", "enum": [ "US-FED", "US-AL", "US-AK", "US-AZ", "US-AR", "US-CA", "US-CO", "US-CT", "US-DE", "US-DC", "US-FL", "US-GA", "US-HI", "US-ID", "US-IL", "US-IN", "US-IA", "US-KS", "US-KY", "US-LA", "US-ME", "US-MD", "US-MA", "US-MI", "US-MN", "US-MS", "US-MO", "US-MT", "US-NE", "US-NV", "US-NH", "US-NJ", "US-NM", "US-NY", "US-NC", "US-ND", "US-OH", "US-OK", "US-OR", "US-PA", "US-RI", "US-SC", "US-SD", "US-TN", "US-TX", "US-UT", "US-VT", "US-VA", "US-WA", "US-WV", "US-WI", "US-WY" ] } } ], "description": "Jurisdictions evaluated.", "example": "all" }, "as_of": { "type": "string", "description": "Date the law was evaluated at.", "example": "2026-10-30" }, "rules_version": { "type": "string", "description": "Version of the check implementations.", "example": "1.2.0" }, "catalog_version": { "type": "string", "description": "Version of the legal catalog.", "example": "2026.10.30.1" }, "catalog_hash": { "type": "string", "description": "sha256 of the canonical legal catalog.", "example": "b1c2…" }, "disclaimer": { "type": "string", "description": "Not legal advice.", "example": "Automated compliance check … not legal advice." }, "next_action": { "$ref": "#/components/schemas/NextAction" }, "correction": { "type": "object", "properties": { "patch": { "type": "array", "items": { "$ref": "#/components/schemas/JsonPatchOperation" }, "description": "JSON Patch turning params into corrected_params (empty: nothing to change).", "example": [ { "op": "add", "path": "/consent_collection", "value": { "terms_of_service": "required" } } ] }, "corrected_params": { "type": "object", "additionalProperties": {}, "description": "The full params with the fix applied.", "example": { "consent_collection": { "terms_of_service": "required" } } }, "verification": { "type": "object", "properties": { "checks": { "type": "array", "items": { "type": "object", "properties": { "check_id": { "type": "string", "description": "Check id.", "example": "signup.consent.affirmative" }, "before": { "type": "string", "description": "Status with params.", "example": "fail" }, "after": { "type": "string", "description": "Status with corrected_params.", "example": "pass" } }, "required": [ "check_id", "before", "after" ] }, "description": "Each check before and after the fix.", "example": [ { "check_id": "signup.consent.affirmative", "before": "fail", "after": "pass" } ] }, "passes": { "type": "boolean", "description": "No check fails after the fix (conspicuousness on Stripe styling excepted).", "example": true }, "remaining_checks": { "type": "array", "items": { "type": "string" }, "description": "Checks still failing / unclear after the fix.", "example": [] }, "note": { "type": "string", "description": "What Stripe params cannot fix.", "example": "Stripe renders custom_text in its own small grey style …" } }, "required": [ "checks", "passes", "remaining_checks", "note" ], "description": "Engine verification of corrected_params.", "example": { "checks": [ { "check_id": "signup.consent.affirmative", "before": "fail", "after": "pass" } ], "passes": true, "remaining_checks": [], "note": "Stripe renders custom_text in its own small grey style …" } }, "placeholders": { "type": "array", "items": { "type": "string" }, "description": "Placeholders left in the messages.", "example": [] } }, "required": [ "patch", "corrected_params", "verification", "placeholders" ], "description": "The fix.", "example": { "patch": [ { "op": "add", "path": "/consent_collection", "value": { "terms_of_service": "required" } } ], "corrected_params": { "consent_collection": { "terms_of_service": "required" } }, "verification": { "checks": [ { "check_id": "signup.consent.affirmative", "before": "fail", "after": "pass" } ], "passes": true, "remaining_checks": [], "note": "Stripe renders custom_text in its own small grey style …" }, "placeholders": [] } } }, "required": [ "id", "object", "livemode", "created", "kind", "verdict", "summary", "checks", "requirements", "warnings", "jurisdictions", "as_of", "rules_version", "catalog_version", "catalog_hash", "disclaimer", "next_action", "correction" ], "description": "Verdict on Checkout Session params plus corrected params." }, "CheckPlanTerms": { "type": "object", "properties": { "merchant_name": { "type": "string", "maxLength": 200, "description": "Brand shown to subscribers; used in generated text.", "example": "Joybox" }, "plan_name": { "type": "string", "maxLength": 200, "description": "Plan / product name.", "example": "Pro" }, "price": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "string", "maxLength": 40 } ], "description": "Recurring price in major units (19.99). Or give `amount` in minor units.", "example": 19.99 }, "amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Recurring price in minor units (1999 = $19.99), Stripe style.", "example": 1999 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "description": "Three-letter ISO currency (default usd).", "example": "usd" }, "interval": { "type": "string", "maxLength": 20, "description": "Billing interval: day, week, month or year.", "example": "month" }, "interval_count": { "type": "integer", "minimum": 1, "maximum": 36, "description": "Number of intervals between charges (default 1).", "example": 1 }, "trial_days": { "type": "integer", "minimum": 0, "maximum": 730, "description": "Free-trial length in days (0 or absent = no trial).", "example": 14 }, "cancel_url": { "type": "string", "maxLength": 2048, "description": "https URL where subscribers cancel online (used in generated text; a {{cancel_url}} placeholder otherwise).", "example": "https://joybox.example/account/cancel" }, "cancel_timing": { "type": "string", "enum": [ "period_end", "immediately" ], "description": "When a cancellation takes effect (default period_end).", "example": "period_end" } }, "description": "What Stripe params do not say: merchant_name, cancel_url, and price / interval when line_items reference a Price id." }, "StripeCheckParams": { "type": "object", "properties": { "params": { "type": "object", "additionalProperties": {}, "description": "Exactly the object your code passes to Stripe (checkout.sessions.create / paymentLinks.create), or a retrieved Payment Link.", "example": { "mode": "subscription", "line_items": [ { "price_data": { "currency": "usd", "unit_amount": 1999, "recurring": { "interval": "month" }, "product_data": { "name": "Joybox Pro" } }, "quantity": 1 } ], "success_url": "https://joybox.example/welcome" } }, "merchant": { "$ref": "#/components/schemas/CheckPlanTerms" }, "jurisdictions": { "anyOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "array", "items": { "type": "string", "maxLength": 10 }, "maxItems": 60 } ], "description": "Where you sell: \"all\" (default) or state codes (\"US-CA\", \"CA\", \"US-NY\"; \"US-FED\" is always included).", "example": [ "US-CA", "US-NY" ] }, "as_of": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Evaluate the law as of this date (YYYY-MM-DD, default today).", "example": "2026-10-30" } }, "required": [ "params" ], "description": "Stripe params to check before they ship." }, "StripePaymentLinkCheckResult": { "type": "object", "properties": { "id": { "type": "string", "description": "Id of this check run (chk_…). Checks are stateless and not stored.", "example": "chk_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "check_result" ], "description": "String representing the object's type. Always \"check_result\".", "example": "check_result" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "created": { "type": "integer", "description": "When the check ran. Unix timestamp in seconds.", "example": 1793318400 }, "kind": { "type": "string", "enum": [ "disclosure", "stripe_checkout_session", "stripe_payment_link", "email", "page" ], "description": "Which check ran.", "example": "disclosure" }, "verdict": { "type": "string", "enum": [ "pass", "fail", "needs_review", "not_applicable" ], "description": "Overall: fail if any check fails, else needs_review if any needs review, else pass (not_applicable when nothing applies).", "example": "fail" }, "summary": { "type": "object", "properties": { "pass": { "type": "integer", "description": "Checks passing.", "example": 6 }, "fail": { "type": "integer", "description": "Checks failing.", "example": 2 }, "needs_review": { "type": "integer", "description": "Checks needing review.", "example": 1 }, "not_applicable": { "type": "integer", "description": "Checks not applicable.", "example": 1 } }, "required": [ "pass", "fail", "needs_review", "not_applicable" ], "description": "Counts by status.", "example": { "pass": 6, "fail": 2, "needs_review": 1, "not_applicable": 1 } }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/CheckVerdict" }, "description": "Every evaluated check.", "example": [ { "check_id": "signup.disclosure.price", "status": "fail", "severity": "critical", "title": "Discloses the recurring charge amount", "explanation": "The recurring charge amount is not stated in the terms next to the purchase button.", "confidence": 0.85, "requirements": [ { "id": "US-CA.17602.a.1", "jurisdiction": "US-CA", "citation": "Cal. Bus. & Prof. Code § 17602(a)(1)", "title": "Clear and conspicuous disclosure of automatic renewal offer terms", "source_url": "https://leginfo.legislature.ca.gov/" } ], "fix": "Show the recurring charge amount in the terms next to the purchase button.", "static_estimate": "pass" } ] }, "requirements": { "type": "array", "items": { "$ref": "#/components/schemas/CheckRequirementVerdict" }, "description": "Verdict per legal requirement (federal first, then by state).", "example": [ { "id": "US-CA.17602.a.1", "jurisdiction": "US-CA", "citation": "Cal. Bus. & Prof. Code § 17602(a)(1)", "title": "Clear and conspicuous disclosure of automatic renewal offer terms", "source_url": "https://leginfo.legislature.ca.gov/" } ] }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/CheckWarning" }, "description": "Notes about the input.", "example": [ { "code": "stripe_tos_url_required", "message": "consent_collection.terms_of_service needs a Terms of Service URL in Stripe.", "param": "params.consent_collection" } ] }, "jurisdictions": { "anyOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "array", "items": { "type": "string", "enum": [ "US-FED", "US-AL", "US-AK", "US-AZ", "US-AR", "US-CA", "US-CO", "US-CT", "US-DE", "US-DC", "US-FL", "US-GA", "US-HI", "US-ID", "US-IL", "US-IN", "US-IA", "US-KS", "US-KY", "US-LA", "US-ME", "US-MD", "US-MA", "US-MI", "US-MN", "US-MS", "US-MO", "US-MT", "US-NE", "US-NV", "US-NH", "US-NJ", "US-NM", "US-NY", "US-NC", "US-ND", "US-OH", "US-OK", "US-OR", "US-PA", "US-RI", "US-SC", "US-SD", "US-TN", "US-TX", "US-UT", "US-VT", "US-VA", "US-WA", "US-WV", "US-WI", "US-WY" ] } } ], "description": "Jurisdictions evaluated.", "example": "all" }, "as_of": { "type": "string", "description": "Date the law was evaluated at.", "example": "2026-10-30" }, "rules_version": { "type": "string", "description": "Version of the check implementations.", "example": "1.2.0" }, "catalog_version": { "type": "string", "description": "Version of the legal catalog.", "example": "2026.10.30.1" }, "catalog_hash": { "type": "string", "description": "sha256 of the canonical legal catalog.", "example": "b1c2…" }, "disclaimer": { "type": "string", "description": "Not legal advice.", "example": "Automated compliance check … not legal advice." }, "next_action": { "$ref": "#/components/schemas/NextAction" }, "correction": { "type": "object", "properties": { "patch": { "type": "array", "items": { "$ref": "#/components/schemas/JsonPatchOperation" }, "description": "JSON Patch turning params into corrected_params (empty: nothing to change).", "example": [ { "op": "add", "path": "/consent_collection", "value": { "terms_of_service": "required" } } ] }, "corrected_params": { "type": "object", "additionalProperties": {}, "description": "The full params with the fix applied.", "example": { "consent_collection": { "terms_of_service": "required" } } }, "verification": { "type": "object", "properties": { "checks": { "type": "array", "items": { "type": "object", "properties": { "check_id": { "type": "string", "description": "Check id.", "example": "signup.consent.affirmative" }, "before": { "type": "string", "description": "Status with params.", "example": "fail" }, "after": { "type": "string", "description": "Status with corrected_params.", "example": "pass" } }, "required": [ "check_id", "before", "after" ] }, "description": "Each check before and after the fix.", "example": [ { "check_id": "signup.consent.affirmative", "before": "fail", "after": "pass" } ] }, "passes": { "type": "boolean", "description": "No check fails after the fix (conspicuousness on Stripe styling excepted).", "example": true }, "remaining_checks": { "type": "array", "items": { "type": "string" }, "description": "Checks still failing / unclear after the fix.", "example": [] }, "note": { "type": "string", "description": "What Stripe params cannot fix.", "example": "Stripe renders custom_text in its own small grey style …" } }, "required": [ "checks", "passes", "remaining_checks", "note" ], "description": "Engine verification of corrected_params.", "example": { "checks": [ { "check_id": "signup.consent.affirmative", "before": "fail", "after": "pass" } ], "passes": true, "remaining_checks": [], "note": "Stripe renders custom_text in its own small grey style …" } }, "placeholders": { "type": "array", "items": { "type": "string" }, "description": "Placeholders left in the messages.", "example": [] }, "update_params": { "type": "object", "additionalProperties": {}, "description": "For an existing link (params.id): params for stripe.paymentLinks.update (same URL).", "example": { "custom_text": { "submit": { "message": "…" } } } }, "needs_new_link_for_consent": { "type": "boolean", "description": "Stripe cannot add the consent checkbox to an existing link: create a new link with corrected_params.", "example": true } }, "required": [ "patch", "corrected_params", "verification", "placeholders", "needs_new_link_for_consent" ], "description": "The fix.", "example": { "patch": [ { "op": "add", "path": "/consent_collection", "value": { "terms_of_service": "required" } } ], "corrected_params": { "consent_collection": { "terms_of_service": "required" } }, "verification": { "checks": [ { "check_id": "signup.consent.affirmative", "before": "fail", "after": "pass" } ], "passes": true, "remaining_checks": [], "note": "Stripe renders custom_text in its own small grey style …" }, "placeholders": [], "update_params": { "custom_text": { "submit": { "message": "…" } } }, "needs_new_link_for_consent": true } } }, "required": [ "id", "object", "livemode", "created", "kind", "verdict", "summary", "checks", "requirements", "warnings", "jurisdictions", "as_of", "rules_version", "catalog_version", "catalog_hash", "disclaimer", "next_action", "correction" ], "description": "Verdict on Payment Link params plus corrected params." }, "EmailCheckResult": { "type": "object", "properties": { "id": { "type": "string", "description": "Id of this check run (chk_…). Checks are stateless and not stored.", "example": "chk_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "check_result" ], "description": "String representing the object's type. Always \"check_result\".", "example": "check_result" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "created": { "type": "integer", "description": "When the check ran. Unix timestamp in seconds.", "example": 1793318400 }, "kind": { "type": "string", "enum": [ "disclosure", "stripe_checkout_session", "stripe_payment_link", "email", "page" ], "description": "Which check ran.", "example": "disclosure" }, "verdict": { "type": "string", "enum": [ "pass", "fail", "needs_review", "not_applicable" ], "description": "Overall: fail if any check fails, else needs_review if any needs review, else pass (not_applicable when nothing applies).", "example": "fail" }, "summary": { "type": "object", "properties": { "pass": { "type": "integer", "description": "Checks passing.", "example": 6 }, "fail": { "type": "integer", "description": "Checks failing.", "example": 2 }, "needs_review": { "type": "integer", "description": "Checks needing review.", "example": 1 }, "not_applicable": { "type": "integer", "description": "Checks not applicable.", "example": 1 } }, "required": [ "pass", "fail", "needs_review", "not_applicable" ], "description": "Counts by status.", "example": { "pass": 6, "fail": 2, "needs_review": 1, "not_applicable": 1 } }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/CheckVerdict" }, "description": "Every evaluated check.", "example": [ { "check_id": "signup.disclosure.price", "status": "fail", "severity": "critical", "title": "Discloses the recurring charge amount", "explanation": "The recurring charge amount is not stated in the terms next to the purchase button.", "confidence": 0.85, "requirements": [ { "id": "US-CA.17602.a.1", "jurisdiction": "US-CA", "citation": "Cal. Bus. & Prof. Code § 17602(a)(1)", "title": "Clear and conspicuous disclosure of automatic renewal offer terms", "source_url": "https://leginfo.legislature.ca.gov/" } ], "fix": "Show the recurring charge amount in the terms next to the purchase button.", "static_estimate": "pass" } ] }, "requirements": { "type": "array", "items": { "$ref": "#/components/schemas/CheckRequirementVerdict" }, "description": "Verdict per legal requirement (federal first, then by state).", "example": [ { "id": "US-CA.17602.a.1", "jurisdiction": "US-CA", "citation": "Cal. Bus. & Prof. Code § 17602(a)(1)", "title": "Clear and conspicuous disclosure of automatic renewal offer terms", "source_url": "https://leginfo.legislature.ca.gov/" } ] }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/CheckWarning" }, "description": "Notes about the input.", "example": [ { "code": "stripe_tos_url_required", "message": "consent_collection.terms_of_service needs a Terms of Service URL in Stripe.", "param": "params.consent_collection" } ] }, "jurisdictions": { "anyOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "array", "items": { "type": "string", "enum": [ "US-FED", "US-AL", "US-AK", "US-AZ", "US-AR", "US-CA", "US-CO", "US-CT", "US-DE", "US-DC", "US-FL", "US-GA", "US-HI", "US-ID", "US-IL", "US-IN", "US-IA", "US-KS", "US-KY", "US-LA", "US-ME", "US-MD", "US-MA", "US-MI", "US-MN", "US-MS", "US-MO", "US-MT", "US-NE", "US-NV", "US-NH", "US-NJ", "US-NM", "US-NY", "US-NC", "US-ND", "US-OH", "US-OK", "US-OR", "US-PA", "US-RI", "US-SC", "US-SD", "US-TN", "US-TX", "US-UT", "US-VT", "US-VA", "US-WA", "US-WV", "US-WI", "US-WY" ] } } ], "description": "Jurisdictions evaluated.", "example": "all" }, "as_of": { "type": "string", "description": "Date the law was evaluated at.", "example": "2026-10-30" }, "rules_version": { "type": "string", "description": "Version of the check implementations.", "example": "1.2.0" }, "catalog_version": { "type": "string", "description": "Version of the legal catalog.", "example": "2026.10.30.1" }, "catalog_hash": { "type": "string", "description": "sha256 of the canonical legal catalog.", "example": "b1c2…" }, "disclaimer": { "type": "string", "description": "Not legal advice.", "example": "Automated compliance check … not legal advice." }, "next_action": { "$ref": "#/components/schemas/NextAction" }, "email_kind": { "type": "string", "description": "The email kind checked.", "example": "trial_reminder" }, "required_by": { "type": "array", "items": { "type": "string" }, "description": "Requirements that make this email mandatory for this plan (empty: not legally required).", "example": [ "US-CA.17602.a.3" ] }, "template": { "type": "object", "properties": { "subject": { "type": "string", "description": "Compliant subject.", "example": "Your Joybox free trial ends on {{trial_end_date}}" }, "text": { "type": "string", "description": "Compliant plain-text body.", "example": "Your free trial ends on {{trial_end_date}}. …" }, "html": { "type": "string", "description": "The same body as HTML.", "example": "

Your free trial ends on {{trial_end_date}}. …

" }, "merge_tags": { "type": "array", "items": { "type": "string" }, "description": "Per-subscriber merge tags your sender fills.", "example": [ "{{trial_end_date}}" ] }, "placeholders": { "type": "array", "items": { "type": "string" }, "description": "Values you have not given yet.", "example": [] }, "verified": { "type": "boolean", "description": "The engine passes this kind’s checks on the template.", "example": true }, "remaining_checks": { "type": "array", "items": { "type": "string" }, "description": "Checks the template does not pass (normally empty).", "example": [] } }, "required": [ "subject", "text", "html", "merge_tags", "placeholders", "verified", "remaining_checks" ], "description": "A compliant template generated from the plan terms.", "example": { "subject": "Your Joybox free trial ends on {{trial_end_date}}", "text": "Your free trial ends on {{trial_end_date}}. …", "html": "

Your free trial ends on {{trial_end_date}}. …

", "merge_tags": [ "{{trial_end_date}}" ], "placeholders": [], "verified": true, "remaining_checks": [] } } }, "required": [ "id", "object", "livemode", "created", "kind", "verdict", "summary", "checks", "requirements", "warnings", "jurisdictions", "as_of", "rules_version", "catalog_version", "catalog_hash", "disclaimer", "next_action", "email_kind", "required_by", "template" ], "description": "Verdict on a lifecycle email plus a verified template." }, "EmailCheckParams": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "acknowledgment", "trial_reminder", "trial_ending", "renewal_reminder", "price_change", "annual_terms", "charge_notice", "cancellation_confirmation" ], "description": "Which lifecycle email this is (the same names verifyTask, the plan and the X-Checkbox-Kind header use; trial_ending is an alias of trial_reminder, as in Notices).", "example": "trial_reminder" }, "subject": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Subject line.", "example": "Your free trial ends on December 4" }, "text": { "type": "string", "maxLength": 100000, "description": "Plain-text body (give text, html or both).", "example": "Your free trial ends on December 4, 2026. …" }, "html": { "type": "string", "maxLength": 100000, "description": "HTML body.", "example": "

Your free trial ends on December 4, 2026. …

" }, "terms": { "allOf": [ { "$ref": "#/components/schemas/CheckPlanTerms" }, { "type": "object", "properties": { "previous_price": { "anyOf": [ { "type": "number", "exclusiveMinimum": 0 }, { "type": "string", "maxLength": 40 } ], "description": "price_change only: the OLD price before the change, major units. price / amount is the NEW price the email announces.", "example": 14.99 }, "previous_amount": { "type": "integer", "exclusiveMinimum": 0, "description": "Price before a price change, minor units.", "example": 1499 }, "support_contact": { "type": "string", "maxLength": 200, "description": "Support email / URL shown in the generated template.", "example": "support@joybox.example" } } } ], "description": "The plan the email is about (price, interval and cancel_url at least).", "example": { "merchant_name": "Joybox", "plan_name": "Pro", "price": 19.99, "amount": 1999, "currency": "usd", "interval": "month", "interval_count": 1, "trial_days": 14, "cancel_url": "https://joybox.example/account/cancel", "cancel_timing": "period_end" } }, "jurisdictions": { "anyOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "array", "items": { "type": "string", "maxLength": 10 }, "maxItems": 60 } ], "description": "Where you sell: \"all\" (default) or state codes (\"US-CA\", \"CA\", \"US-NY\"; \"US-FED\" is always included).", "example": [ "US-CA", "US-NY" ] }, "as_of": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Evaluate the law as of this date (YYYY-MM-DD, default today).", "example": "2026-10-30" } }, "required": [ "kind", "subject", "terms" ], "description": "A lifecycle email to check before it is wired in." }, "PageCheckResult": { "type": "object", "properties": { "id": { "type": "string", "description": "Id of this check run (chk_…). Checks are stateless and not stored.", "example": "chk_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "check_result" ], "description": "String representing the object's type. Always \"check_result\".", "example": "check_result" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "created": { "type": "integer", "description": "When the check ran. Unix timestamp in seconds.", "example": 1793318400 }, "kind": { "type": "string", "enum": [ "disclosure", "stripe_checkout_session", "stripe_payment_link", "email", "page" ], "description": "Which check ran.", "example": "disclosure" }, "verdict": { "type": "string", "enum": [ "pass", "fail", "needs_review", "not_applicable" ], "description": "Overall: fail if any check fails, else needs_review if any needs review, else pass (not_applicable when nothing applies).", "example": "fail" }, "summary": { "type": "object", "properties": { "pass": { "type": "integer", "description": "Checks passing.", "example": 6 }, "fail": { "type": "integer", "description": "Checks failing.", "example": 2 }, "needs_review": { "type": "integer", "description": "Checks needing review.", "example": 1 }, "not_applicable": { "type": "integer", "description": "Checks not applicable.", "example": 1 } }, "required": [ "pass", "fail", "needs_review", "not_applicable" ], "description": "Counts by status.", "example": { "pass": 6, "fail": 2, "needs_review": 1, "not_applicable": 1 } }, "checks": { "type": "array", "items": { "$ref": "#/components/schemas/CheckVerdict" }, "description": "Every evaluated check.", "example": [ { "check_id": "signup.disclosure.price", "status": "fail", "severity": "critical", "title": "Discloses the recurring charge amount", "explanation": "The recurring charge amount is not stated in the terms next to the purchase button.", "confidence": 0.85, "requirements": [ { "id": "US-CA.17602.a.1", "jurisdiction": "US-CA", "citation": "Cal. Bus. & Prof. Code § 17602(a)(1)", "title": "Clear and conspicuous disclosure of automatic renewal offer terms", "source_url": "https://leginfo.legislature.ca.gov/" } ], "fix": "Show the recurring charge amount in the terms next to the purchase button.", "static_estimate": "pass" } ] }, "requirements": { "type": "array", "items": { "$ref": "#/components/schemas/CheckRequirementVerdict" }, "description": "Verdict per legal requirement (federal first, then by state).", "example": [ { "id": "US-CA.17602.a.1", "jurisdiction": "US-CA", "citation": "Cal. Bus. & Prof. Code § 17602(a)(1)", "title": "Clear and conspicuous disclosure of automatic renewal offer terms", "source_url": "https://leginfo.legislature.ca.gov/" } ] }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/CheckWarning" }, "description": "Notes about the input.", "example": [ { "code": "stripe_tos_url_required", "message": "consent_collection.terms_of_service needs a Terms of Service URL in Stripe.", "param": "params.consent_collection" } ] }, "jurisdictions": { "anyOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "array", "items": { "type": "string", "enum": [ "US-FED", "US-AL", "US-AK", "US-AZ", "US-AR", "US-CA", "US-CO", "US-CT", "US-DE", "US-DC", "US-FL", "US-GA", "US-HI", "US-ID", "US-IL", "US-IN", "US-IA", "US-KS", "US-KY", "US-LA", "US-ME", "US-MD", "US-MA", "US-MI", "US-MN", "US-MS", "US-MO", "US-MT", "US-NE", "US-NV", "US-NH", "US-NJ", "US-NM", "US-NY", "US-NC", "US-ND", "US-OH", "US-OK", "US-OR", "US-PA", "US-RI", "US-SC", "US-SD", "US-TN", "US-TX", "US-UT", "US-VT", "US-VA", "US-WA", "US-WV", "US-WI", "US-WY" ] } } ], "description": "Jurisdictions evaluated.", "example": "all" }, "as_of": { "type": "string", "description": "Date the law was evaluated at.", "example": "2026-10-30" }, "rules_version": { "type": "string", "description": "Version of the check implementations.", "example": "1.2.0" }, "catalog_version": { "type": "string", "description": "Version of the legal catalog.", "example": "2026.10.30.1" }, "catalog_hash": { "type": "string", "description": "sha256 of the canonical legal catalog.", "example": "b1c2…" }, "disclaimer": { "type": "string", "description": "Not legal advice.", "example": "Automated compliance check … not legal advice." }, "next_action": { "$ref": "#/components/schemas/NextAction" }, "source": { "type": "string", "enum": [ "html", "url" ], "description": "Whether html was given or fetched from url.", "example": "html" }, "extraction": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "static_html" ], "description": "How the page was read.", "example": "static_html" }, "url": { "type": "string", "description": "Page URL used.", "example": "https://joybox.example/checkout" }, "purchase_buttons": { "type": "array", "items": { "type": "string" }, "description": "Purchase buttons found (primary first).", "example": [ "Subscribe" ] }, "disclosures": { "type": "array", "items": { "type": "string" }, "description": "Text blocks that read like subscription terms.", "example": [ "Renews monthly at $19.99 until you cancel." ] }, "checkboxes": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "description": "Label.", "example": "I agree to the automatic renewal terms." }, "prechecked": { "type": "boolean", "description": "Checked by default.", "example": false }, "required": { "type": "boolean", "description": "Required.", "example": true } }, "required": [ "label", "prechecked", "required" ] }, "description": "Checkboxes found.", "example": [ { "label": "I agree to the automatic renewal terms.", "prechecked": false, "required": true } ] }, "links": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "description": "Link text.", "example": "Terms of Service" }, "href": { "type": "string", "description": "Target.", "example": "https://joybox.example/terms" } }, "required": [ "text", "href" ] }, "description": "Terms / cancellation / account links found.", "example": [ { "text": "Terms of Service", "href": "https://joybox.example/terms" } ] }, "limitations": { "type": "array", "items": { "type": "string" }, "description": "What a static read cannot measure.", "example": [ "Static HTML: stylesheets … were not applied." ] } }, "required": [ "mode", "url", "purchase_buttons", "disclosures", "checkboxes", "links", "limitations" ], "description": "What was read from the page.", "example": { "mode": "static_html", "url": "https://joybox.example/checkout", "purchase_buttons": [ "Subscribe" ], "disclosures": [ "Renews monthly at $19.99 until you cancel." ], "checkboxes": [ { "label": "I agree to the automatic renewal terms.", "prechecked": false, "required": true } ], "links": [ { "text": "Terms of Service", "href": "https://joybox.example/terms" } ], "limitations": [ "Static HTML: stylesheets … were not applied." ] } }, "replacement": { "$ref": "#/components/schemas/CheckReplacement" } }, "required": [ "id", "object", "livemode", "created", "kind", "verdict", "summary", "checks", "requirements", "warnings", "jurisdictions", "as_of", "rules_version", "catalog_version", "catalog_hash", "disclaimer", "next_action", "source", "extraction" ], "description": "Verdict on a checkout page." }, "PageCheckParams": { "type": "object", "properties": { "html": { "type": "string", "maxLength": 1000000, "description": "Checkout page HTML (rendered, after JavaScript, for client-side apps). Give html or url.", "example": "
…
" }, "url": { "type": "string", "maxLength": 2048, "description": "Fetch this live page instead (live mode, activated accounts only; public addresses only).", "example": "https://joybox.example/checkout" }, "page_kind": { "type": "string", "enum": [ "checkout", "pricing" ], "description": "What the page is (default checkout).", "example": "checkout" }, "terms": { "allOf": [ { "$ref": "#/components/schemas/CheckPlanTerms" }, { "description": "The subscription plan the checkout / email is about." } ], "example": { "merchant_name": "Joybox", "plan_name": "Pro", "price": 19.99, "amount": 1999, "currency": "usd", "interval": "month", "interval_count": 1, "trial_days": 14, "cancel_url": "https://joybox.example/account/cancel", "cancel_timing": "period_end" } }, "jurisdictions": { "anyOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "array", "items": { "type": "string", "maxLength": 10 }, "maxItems": 60 } ], "description": "Where you sell: \"all\" (default) or state codes (\"US-CA\", \"CA\", \"US-NY\"; \"US-FED\" is always included).", "example": [ "US-CA", "US-NY" ] }, "as_of": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Evaluate the law as of this date (YYYY-MM-DD, default today).", "example": "2026-10-30" } }, "description": "A checkout page to check." }, "ScheduledNotice": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "acknowledgment", "trial_ending", "renewal_reminder", "annual_terms", "price_change" ], "description": "Notice kind.", "example": "trial_ending" }, "occasion": { "type": "string", "description": "What the notice announces.", "example": "Trial ends" }, "anchor_date": { "type": "string", "description": "Date of the event (YYYY-MM-DD, UTC).", "example": "2026-11-15" }, "send_date": { "type": "string", "description": "Recommended send date (YYYY-MM-DD, UTC).", "example": "2026-11-03" }, "send_at": { "type": "integer", "description": "Recommended send time. Unix timestamp in seconds.", "example": 1793750400 }, "window_opens_at": { "type": "integer", "description": "Earliest compliant send time. Unix seconds.", "example": 1793318400 }, "window_closes_at": { "type": "integer", "description": "Latest compliant send time. Unix seconds.", "example": 1794182400 }, "days_before": { "type": "number", "description": "Days before the event (0 = right away).", "example": 12 }, "jurisdictions": { "type": "array", "items": { "type": "string" }, "description": "Jurisdictions whose window this send satisfies.", "example": [ "US-CA", "US-NY" ] }, "requirement_ids": { "type": "array", "items": { "type": "string" }, "description": "Requirements behind the timing.", "example": [ "US-CA.17602.a.3" ] }, "citations": { "type": "array", "items": { "type": "string" }, "description": "Citations of those requirements.", "example": [ "Cal. Bus. & Prof. Code § 17602(a)(3)" ] }, "default_window": { "type": "boolean", "description": "No requirement states a window; Checkbox’s default window was used.", "example": false } }, "required": [ "kind", "occasion", "anchor_date", "send_date", "send_at", "window_opens_at", "window_closes_at", "days_before", "jurisdictions", "requirement_ids", "citations", "default_window" ], "description": "One notice to send." }, "NoticeScheduleResult": { "type": "object", "properties": { "id": { "type": "string", "description": "Id of this check run (chk_…).", "example": "chk_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "notice_schedule" ], "description": "String representing the object's type. Always \"notice_schedule\".", "example": "notice_schedule" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "created": { "type": "integer", "description": "When computed. Unix seconds.", "example": 1793318400 }, "start_date": { "type": "string", "description": "Sign-up date planned for.", "example": "2026-11-01" }, "notices": { "type": "array", "items": { "$ref": "#/components/schemas/ScheduledNotice" }, "description": "Every legally required notice, in send order.", "example": [ { "kind": "trial_ending", "occasion": "Trial ends", "anchor_date": "2026-11-15", "send_date": "2026-11-03", "send_at": 1793750400, "window_opens_at": 1793318400, "window_closes_at": 1794182400, "days_before": 12, "jurisdictions": [ "US-CA", "US-NY" ], "requirement_ids": [ "US-CA.17602.a.3" ], "citations": [ "Cal. Bus. & Prof. Code § 17602(a)(3)" ], "default_window": false } ] }, "not_required": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "description": "Notice kind.", "example": "renewal_reminder" }, "reason": { "type": "string", "description": "Why it is not required.", "example": "Monthly term: renewal reminders apply to terms of 12+ months." } }, "required": [ "kind", "reason" ] }, "description": "Notice kinds no applicable requirement demands for this plan.", "example": [ { "kind": "renewal_reminder", "reason": "Monthly term: renewal reminders apply to terms of 12+ months." } ] }, "jurisdictions": { "anyOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "array", "items": { "type": "string", "enum": [ "US-FED", "US-AL", "US-AK", "US-AZ", "US-AR", "US-CA", "US-CO", "US-CT", "US-DE", "US-DC", "US-FL", "US-GA", "US-HI", "US-ID", "US-IL", "US-IN", "US-IA", "US-KS", "US-KY", "US-LA", "US-ME", "US-MD", "US-MA", "US-MI", "US-MN", "US-MS", "US-MO", "US-MT", "US-NE", "US-NV", "US-NH", "US-NJ", "US-NM", "US-NY", "US-NC", "US-ND", "US-OH", "US-OK", "US-OR", "US-PA", "US-RI", "US-SC", "US-SD", "US-TN", "US-TX", "US-UT", "US-VT", "US-VA", "US-WA", "US-WV", "US-WI", "US-WY" ] } } ], "description": "Jurisdictions planned for.", "example": "all" }, "as_of": { "type": "string", "description": "Date the law was applied at.", "example": "2026-10-30" }, "rules_version": { "type": "string", "description": "Version of the check implementations.", "example": "1.2.0" }, "catalog_version": { "type": "string", "description": "Version of the legal catalog.", "example": "2026.10.30.1" }, "catalog_hash": { "type": "string", "description": "sha256 of the canonical legal catalog.", "example": "b1c2…" }, "disclaimer": { "type": "string", "description": "Not legal advice.", "example": "Automated compliance check … not legal advice." }, "next_action": { "$ref": "#/components/schemas/NextAction" } }, "required": [ "id", "object", "livemode", "created", "start_date", "notices", "not_required", "jurisdictions", "as_of", "rules_version", "catalog_version", "catalog_hash", "disclaimer", "next_action" ], "description": "When each legally required notice must be sent." }, "NoticeScheduleParams": { "type": "object", "properties": { "terms": { "allOf": [ { "$ref": "#/components/schemas/CheckPlanTerms" }, { "description": "The plan: price, interval, interval_count, trial_days." } ], "example": { "merchant_name": "Joybox", "plan_name": "Pro", "price": 19.99, "amount": 1999, "currency": "usd", "interval": "month", "interval_count": 1, "trial_days": 14, "cancel_url": "https://joybox.example/account/cancel", "cancel_timing": "period_end" } }, "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Sign-up date of the subscription to plan for (default today).", "example": "2026-11-01" }, "price_change": { "type": "object", "properties": { "effective_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Date the new price is first charged.", "example": "2027-03-01" }, "new_price": { "type": "number", "exclusiveMinimum": 0, "description": "New recurring price, major units.", "example": 24.99 } }, "required": [ "effective_date" ], "description": "A planned price change to schedule the notice for.", "example": { "effective_date": "2027-03-01", "new_price": 24.99 } }, "cycles": { "type": "integer", "minimum": 1, "maximum": 24, "description": "How many renewals to plan (default: one year of renewals).", "example": 12 }, "payment_methods": { "type": "array", "items": { "type": "string", "enum": [ "card", "debit", "ach", "wallet", "other" ] }, "maxItems": 5, "description": "Payment methods offered (some notices apply only to debit / ACH).", "example": [ "card" ] }, "jurisdictions": { "anyOf": [ { "type": "string", "enum": [ "all" ] }, { "type": "array", "items": { "type": "string", "maxLength": 10 }, "maxItems": 60 } ], "description": "Where you sell: \"all\" (default) or state codes (\"US-CA\", \"CA\", \"US-NY\"; \"US-FED\" is always included).", "example": [ "US-CA", "US-NY" ] }, "as_of": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Evaluate the law as of this date (YYYY-MM-DD, default today).", "example": "2026-10-30" } }, "required": [ "terms" ], "description": "A subscription to plan the legally required notices for." }, "ElementsRelease": { "type": "object", "properties": { "version": { "type": "string", "description": "Semver of the bundle.", "example": "1.0.0" }, "url": { "type": "string", "description": "Immutable URL of this version.", "example": "https://app.checkbox.site/v1/elements/1.0.0/elements.js" }, "integrity": { "type": "string", "description": "Subresource Integrity hash (integrity attribute).", "example": "sha384-…" }, "size": { "type": "integer", "description": "Bytes.", "example": 33000 } }, "required": [ "version", "url", "integrity", "size" ] }, "ElementsManifest": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "elements_manifest" ], "description": "String representing the object's type. Always \"elements_manifest\".", "example": "elements_manifest" }, "latest": { "$ref": "#/components/schemas/ElementsRelease" }, "versions": { "type": "array", "items": { "$ref": "#/components/schemas/ElementsRelease" }, "description": "Every released version, newest first.", "example": [ { "version": "1.0.0", "url": "https://app.checkbox.site/v1/elements/1.0.0/elements.js", "integrity": "sha384-…", "size": 33000 } ] }, "script_tag": { "type": "string", "description": "Ready-to-paste " }, "element_tag": { "type": "string", "description": "Custom element name.", "example": "checkbox-disclosure" }, "docs_url": { "type": "string", "description": "Documentation.", "example": "https://checkbox.site/docs/elements" } }, "required": [ "object", "latest", "versions", "script_tag", "element_tag", "docs_url" ], "description": "Released Checkbox Elements bundles and their SRI hashes." }, "Disclosure": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the disclosure (disc_…).", "example": "disc_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "disclosure" ], "description": "String representing the object's type. Always \"disclosure\".", "example": "disclosure" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "created": { "type": "integer", "description": "Creation time. Unix timestamp in seconds.", "example": 1793318400 }, "site": { "type": "string", "description": "Site.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "terms": { "type": "object", "additionalProperties": {}, "description": "Terms stated (DisclosureTerms).", "example": { "merchant_name": "Joybox", "amount": 1999, "currency": "usd", "interval": "month" } }, "text": { "type": "string", "description": "Locked disclosure text.", "example": "Your Joybox subscription automatically renews every month at $19.99 …" }, "consent_label": { "type": "string", "description": "Locked consent checkbox label.", "example": "I agree that my Joybox subscription renews automatically …" }, "texts_sha256": { "type": "string", "description": "sha256 of text + \"\\n\" + consent_label.", "example": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" }, "rules_version": { "type": "string", "description": "Rules version that generated and verified the wording.", "example": "2026.10.30" }, "verification": { "type": [ "object", "null" ], "properties": { "passes": { "type": "boolean", "description": "Every targeted sign-up check passes on the modelled checkout.", "example": true }, "modelled": { "type": "string", "description": "from_capture (your scanned checkout) or synthetic.", "example": "synthetic" }, "remaining": { "type": "array", "items": { "type": "string" }, "description": "Checks that would still not pass.", "example": [] }, "checks": { "type": "array", "items": { "type": "object", "properties": { "check_id": { "type": "string", "description": "Sign-up check id.", "example": "signup.consent.affirmative" }, "before": { "type": "string", "description": "Status on the checkout today.", "example": "fail" }, "after": { "type": "string", "description": "Status with the element installed.", "example": "pass" } }, "required": [ "check_id", "before", "after" ] }, "description": "Per-check before / after.", "example": [] } }, "required": [ "passes", "modelled", "remaining", "checks" ], "description": "Rules-engine verification of the element on your checkout (secret-key responses only).", "example": { "passes": true, "modelled": "synthetic", "remaining": [], "checks": [] } }, "element_html": { "type": "string", "description": "Markup to paste directly above your pay button.", "example": "" }, "script_tag": { "type": "string", "description": "" }, "publishable_key": { "type": "string", "description": "The publishable key for this mode (safe to embed in pages).", "example": "pk_test_…" }, "next_action": { "$ref": "#/components/schemas/NextAction" } }, "required": [ "id", "object", "livemode", "created", "site", "terms", "text", "consent_label", "texts_sha256", "rules_version", "verification" ], "description": "Locked automatic-renewal disclosure + consent wording for a site, rendered by ." }, "DisclosureTerms": { "type": "object", "properties": { "merchant_name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Brand shown to subscribers.", "example": "Joybox" }, "amount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100000000, "description": "Recurring charge in minor units (1999 = $19.99).", "example": 1999 }, "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$", "description": "Three-letter ISO currency code.", "example": "usd" }, "interval": { "type": "string", "enum": [ "day", "week", "month", "year" ], "description": "Billing interval.", "example": "month" }, "interval_count": { "type": "integer", "minimum": 1, "maximum": 36, "description": "Intervals per charge (default 1).", "example": 1 }, "trial_days": { "type": "integer", "minimum": 0, "maximum": 730, "description": "Free-trial length in days (0 or absent: no trial).", "example": 14 }, "cancel_url": { "type": "string", "maxLength": 2048, "description": "https address where subscribers cancel online.", "example": "https://app.checkbox.site/cancel/joybox" }, "cancel_timing": { "type": "string", "enum": [ "period_end", "immediately" ], "description": "When a cancellation takes effect (default period_end).", "example": "period_end" } }, "description": "Terms to state. Omitted values come from the billing connection; cancel_url defaults to the hosted cancellation page." }, "DisclosureCreateParams": { "type": "object", "properties": { "site": { "type": "string", "maxLength": 100, "description": "site_… the disclosure is for.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "plan": { "type": "string", "maxLength": 200, "description": "Price / plan id from the site's billing connection (Stripe price_…) when it offers several.", "example": "price_1Q2w3E" }, "terms": { "$ref": "#/components/schemas/DisclosureTerms" } }, "required": [ "site" ] }, "Consent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the consent (cons_…).", "example": "cons_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "consent" ], "description": "String representing the object's type. Always \"consent\".", "example": "consent" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "created": { "type": "integer", "description": "When Checkbox recorded the consent. Unix timestamp in seconds.", "example": 1793318400 }, "site": { "type": "string", "description": "Site the consent belongs to.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "disclosure": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "description": "disc_… when a server-issued disclosure was shown.", "example": null }, "text": { "type": "string", "description": "Disclosure text shown.", "example": "Your Joybox subscription automatically renews every month …" }, "consent_label": { "type": "string", "description": "Consent checkbox label shown.", "example": "I agree that my Joybox subscription renews automatically …" }, "sha256": { "type": "string", "description": "sha256 of the disclosure text.", "example": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" }, "texts_sha256": { "type": "string", "description": "sha256 of disclosure + \"\\n\" + consent label (the hash Fixes uses).", "example": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" }, "matches_locked_text": { "type": "boolean", "description": "The texts equal Checkbox's locked wording for the terms (or the disclosure's).", "example": true } }, "required": [ "id", "text", "consent_label", "sha256", "texts_sha256", "matches_locked_text" ], "description": "What the subscriber saw.", "example": { "id": null, "text": "Your Joybox subscription automatically renews every month …", "consent_label": "I agree that my Joybox subscription renews automatically …", "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "texts_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "matches_locked_text": true } }, "terms": { "type": "object", "additionalProperties": {}, "description": "Terms the disclosure states (DisclosureTerms).", "example": { "merchant_name": "Joybox", "amount": 1999, "currency": "usd", "interval": "month" } }, "checkbox": { "type": "object", "properties": { "checked": { "type": "boolean", "description": "Always true.", "example": true }, "initially_checked": { "type": "boolean", "description": "The box was pre-ticked (consent then is not affirmative).", "example": false }, "required": { "type": "boolean", "description": "Ticking was required.", "example": true } }, "required": [ "checked", "initially_checked", "required" ], "description": "Checkbox state.", "example": { "checked": true, "initially_checked": false, "required": true } }, "page_url": { "type": [ "string", "null" ], "description": "Page of the consent.", "example": "https://joybox.example/checkout" }, "origin": { "type": [ "string", "null" ], "description": "Origin of the browser request (null for server-recorded consents).", "example": "https://joybox.example" }, "user_agent_sha256": { "type": [ "string", "null" ], "description": "sha256 of the browser User-Agent header.", "example": null }, "customer_reference": { "type": [ "string", "null" ], "description": "Your subscriber reference (set once, by a secret key only: createConsent from your server or updateConsent). Browser-recorded consents start with null.", "example": "cs_test_a1b2c3" }, "client_reference": { "type": [ "string", "null" ], "description": "Reference the page sent with a publishable key (customer-reference attribute). Unverified: anyone holding the public key can send any value, so bind the real subscription with updateConsent from your server.", "example": null }, "source": { "type": "string", "enum": [ "elements", "api" ], "description": "elements: recorded by the browser element; api: by your server.", "example": "elements" }, "element_version": { "type": [ "string", "null" ], "description": "elements.js version.", "example": "1.0.0" }, "client_timestamp": { "type": [ "integer", "null" ], "description": "Device time (unix seconds).", "example": null }, "presentation": { "type": [ "object", "null" ], "properties": { "violations": { "type": "array", "items": { "type": "string" }, "description": "Guard-rail violations measured on screen.", "example": [] }, "fallback_applied": { "type": "boolean", "description": "Safe styles replaced the theme.", "example": false }, "font_size_px": { "type": [ "number", "null" ], "description": "Font size.", "example": 16 }, "contrast_ratio": { "type": [ "number", "null" ], "description": "Contrast ratio.", "example": 16.1 }, "above_submit": { "type": [ "boolean", "null" ], "description": "Above the pay button.", "example": true }, "gap_px": { "type": [ "number", "null" ], "description": "Gap to the pay button.", "example": 12 }, "boxed": { "type": "boolean", "description": "Set off by a border.", "example": true }, "visible": { "type": "boolean", "description": "Visible.", "example": true } }, "required": [ "violations", "fallback_applied", "font_size_px", "contrast_ratio", "above_submit", "gap_px", "boxed", "visible" ], "description": "On-screen measurement summary (null for server-recorded consents).", "example": { "violations": [], "fallback_applied": false, "font_size_px": 16, "contrast_ratio": 16.1, "above_submit": true, "gap_px": 12, "boxed": true, "visible": true } }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Your key/value pairs.", "example": {} }, "evidence": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "description": "ev_… of the evidence record holding the full consent document.", "example": "ev_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "sha256": { "type": [ "string", "null" ], "description": "sha256 of the evidence document.", "example": null }, "chain_hash": { "type": [ "string", "null" ], "description": "Position in the site's hash chain.", "example": null } }, "required": [ "id", "sha256", "chain_hash" ], "description": "Tamper-evident evidence record (verify with verifyEvidenceChain).", "example": { "id": "ev_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "sha256": null, "chain_hash": null } }, "corroborating_capture": { "type": [ "string", "null" ], "description": "Page capture fed to the compliance evaluation from this consent, when a new one was stored.", "example": null }, "next_action": { "$ref": "#/components/schemas/NextAction" } }, "required": [ "id", "object", "livemode", "created", "site", "disclosure", "terms", "checkbox", "page_url", "origin", "user_agent_sha256", "customer_reference", "client_reference", "source", "element_version", "client_timestamp", "presentation", "metadata", "evidence", "next_action" ], "description": "Proof that a subscriber affirmatively consented to the exact automatic-renewal terms shown." }, "ConsentPresentationInput": { "type": "object", "properties": { "font_size_px": { "type": [ "number", "null" ], "description": "Rendered disclosure font size.", "example": 16 }, "body_font_size_px": { "type": "number", "description": "Page body font size.", "example": 16 }, "min_font_size_px": { "type": "number", "description": "Minimum the element enforces.", "example": 16 }, "font_weight": { "type": [ "number", "null" ], "description": "Rendered font weight.", "example": 600 }, "color": { "type": [ "string", "null" ], "maxLength": 64, "description": "Rendered text color.", "example": "rgb(17, 24, 39)" }, "background_color": { "type": [ "string", "null" ], "maxLength": 64, "description": "Effective background color.", "example": "rgb(255, 255, 255)" }, "contrast_ratio": { "type": [ "number", "null" ], "description": "WCAG contrast ratio of the text.", "example": 16.1 }, "opacity": { "type": "number", "description": "Cumulative opacity.", "example": 1 }, "visible": { "type": "boolean", "description": "The disclosure was visible.", "example": true }, "boxed": { "type": "boolean", "description": "The disclosure was set off by a border.", "example": true }, "above_submit": { "type": [ "boolean", "null" ], "description": "The disclosure sat above the pay button.", "example": true }, "gap_px": { "type": [ "number", "null" ], "description": "Vertical gap to the pay button.", "example": 12 }, "rect": { "type": [ "object", "null" ], "properties": { "x": { "type": "number", "description": "Page x (CSS px).", "example": 40 }, "y": { "type": "number", "description": "Page y (CSS px).", "example": 620 }, "width": { "type": "number", "description": "Width (CSS px).", "example": 480 }, "height": { "type": "number", "description": "Height (CSS px).", "example": 120 } }, "required": [ "x", "y", "width", "height" ], "description": "Disclosure box on the page.", "example": { "x": 40, "y": 620, "width": 480, "height": 120 } }, "submit_rect": { "type": [ "object", "null" ], "properties": { "x": { "type": "number", "description": "Page x (CSS px).", "example": 40 }, "y": { "type": "number", "description": "Page y (CSS px).", "example": 620 }, "width": { "type": "number", "description": "Width (CSS px).", "example": 480 }, "height": { "type": "number", "description": "Height (CSS px).", "example": 120 } }, "required": [ "x", "y", "width", "height" ], "description": "Pay button on the page.", "example": { "x": 40, "y": 620, "width": 480, "height": 120 } }, "submit_text": { "type": [ "string", "null" ], "maxLength": 200, "description": "Pay button label.", "example": "Start free trial" }, "viewport": { "type": [ "object", "null" ], "properties": { "width": { "type": "number", "description": "Viewport width (CSS px).", "example": 1280 }, "height": { "type": "number", "description": "Viewport height (CSS px).", "example": 900 } }, "required": [ "width", "height" ], "description": "Viewport size.", "example": { "width": 1280, "height": 900 } }, "violations": { "type": "array", "items": { "type": "string", "maxLength": 40 }, "maxItems": 20, "description": "Guard-rail violations the element detected.", "example": [] }, "fallback_applied": { "type": "boolean", "description": "The element replaced the theme with safe styles.", "example": false } }, "description": "What measured on screen (sent by the element)." }, "ConsentCreateParams": { "type": "object", "properties": { "site": { "type": "string", "maxLength": 100, "description": "site_… the consent belongs to. Optional with a publishable key (resolved from the page Origin); required with a secret key.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "disclosure": { "type": "string", "maxLength": 100, "description": "disc_… of the server-issued disclosure that was shown, if any.", "example": "disc_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "terms": { "allOf": [ { "$ref": "#/components/schemas/DisclosureTerms" }, { "required": [ "merchant_name", "amount", "currency", "interval", "cancel_url" ], "description": "Subscription terms a disclosure states." } ], "example": { "merchant_name": "Joybox", "amount": 1999, "currency": "usd", "interval": "month", "interval_count": 1, "trial_days": 14, "cancel_url": "https://app.checkbox.site/cancel/joybox", "cancel_timing": "period_end" } }, "disclosure_text": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "The exact disclosure text the subscriber saw.", "example": "Your Joybox subscription automatically renews every month at $19.99 (plus applicable taxes) until you cancel. …" }, "consent_label": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "The exact label of the consent checkbox.", "example": "I agree that my Joybox subscription renews automatically every month at $19.99 …" }, "checkbox": { "type": "object", "properties": { "checked": { "type": "boolean", "description": "The box was ticked when the consent was recorded (must be true).", "example": true }, "initially_checked": { "type": "boolean", "description": "The box was ticked before the subscriber touched it (default false).", "example": false }, "required": { "type": "boolean", "description": "Ticking the box was required to subscribe (default true).", "example": true } }, "required": [ "checked" ], "description": "Checkbox state.", "example": { "checked": true, "initially_checked": false, "required": true } }, "page_url": { "type": "string", "maxLength": 2000, "description": "Page the consent was given on (fragment removed).", "example": "https://joybox.example/checkout" }, "customer_reference": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Your id for the subscriber: Stripe customer / Checkout Session / subscription id. Not an email address: no raw personal data is needed.", "example": "cs_test_a1b2c3" }, "client_timestamp": { "type": "integer", "description": "Unix seconds on the subscriber's device (informational; `created` is the server time).", "example": 1793318400 }, "element_version": { "type": "string", "maxLength": 20, "description": "elements.js version that rendered the disclosure.", "example": "1.0.0" }, "presentation": { "$ref": "#/components/schemas/ConsentPresentationInput" }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Up to 20 key/value string pairs you can attach to the object.", "example": { "order_ref": "A-1001" } } }, "required": [ "terms", "disclosure_text", "consent_label", "checkbox" ] }, "ConsentUpdateParams": { "type": "object", "properties": { "customer_reference": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Attach your subscriber reference (only while none is set).", "example": "sub_1Q2w3E" }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Up to 20 key/value string pairs you can attach to the object.", "example": { "order_ref": "A-1001" } } } }, "ConsentList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "String representing the object's type. Always \"list\".", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Consent" }, "description": "Consents, newest first.", "example": [ { "id": "cons_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "consent", "livemode": false, "created": 1793318400, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "disclosure": { "id": null, "text": "Your Joybox subscription automatically renews every month …", "consent_label": "I agree that my Joybox subscription renews automatically …", "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "texts_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "matches_locked_text": true }, "terms": { "merchant_name": "Joybox", "amount": 1999, "currency": "usd", "interval": "month" }, "checkbox": { "checked": true, "initially_checked": false, "required": true }, "page_url": "https://joybox.example/checkout", "origin": "https://joybox.example", "user_agent_sha256": null, "customer_reference": "cs_test_a1b2c3", "client_reference": null, "source": "elements", "element_version": "1.0.0", "client_timestamp": null, "presentation": { "violations": [], "fallback_applied": false, "font_size_px": 16, "contrast_ratio": 16.1, "above_submit": true, "gap_px": 12, "boxed": true, "visible": true }, "metadata": {}, "evidence": { "id": "ev_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "sha256": null, "chain_hash": null }, "corroborating_capture": null, "next_action": { "type": "verify_domain", "message": "Verify your site domain to turn on live mode.", "operation_id": "createDomainVerification", "mcp_tool": "call_api", "url": "https://checkbox.site/docs/api/activation" } } ] }, "has_more": { "type": "boolean", "description": "Whether more items exist after this page. Pass the last id as starting_after to fetch them.", "example": false }, "url": { "type": "string", "description": "The URL of this list.", "example": "/v1/sites" } }, "required": [ "object", "data", "has_more", "url" ], "description": "A page of consents, newest first." }, "TestCredential": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the test credential (tcred_…).", "example": "tcred_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "test_credential" ], "description": "String representing the object's type. Always \"test_credential\".", "example": "test_credential" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "site": { "type": "string", "description": "The site the key belongs to.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "type": { "type": "string", "enum": [ "stripe_test" ], "description": "Kind of key. Always \"stripe_test\" (a Stripe TEST-mode restricted or secret key).", "example": "stripe_test" }, "key_hint": { "type": "string", "description": "The key's prefix and last four characters; the key itself is never returned.", "example": "rk_test_…a1b2" }, "verified": { "type": "boolean", "description": "Whether Stripe accepted the key when it was stored.", "example": true }, "last_used": { "type": [ "integer", "null" ], "description": "When a test run last used the key. Unix timestamp in seconds.", "example": 1793318400 }, "last_error": { "type": [ "string", "null" ], "description": "Last error Stripe returned for the key, if any.", "example": null }, "created": { "type": "integer", "description": "When the key was stored. Unix timestamp in seconds.", "example": 1793318400 } }, "required": [ "id", "object", "livemode", "site", "type", "key_hint", "verified", "last_used", "last_error", "created" ], "description": "A billing-platform TEST-mode key Checkbox uses for synthetic test subscriptions. Stored encrypted; never live mode." }, "TestCredentialList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "String representing the object's type. Always \"list\".", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TestCredential" }, "description": "Stored test-mode keys.", "example": [ { "id": "tcred_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "test_credential", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "type": "stripe_test", "key_hint": "rk_test_…a1b2", "verified": true, "last_used": 1793318400, "last_error": null, "created": 1793318400 } ] }, "has_more": { "type": "boolean", "description": "Whether more items exist after this page. Pass the last id as starting_after to fetch them.", "example": false }, "url": { "type": "string", "description": "The URL of this list.", "example": "/v1/sites" } }, "required": [ "object", "data", "has_more", "url" ], "description": "A page of stored test-mode keys." }, "DeletedTestCredential": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the test credential (tcred_…).", "example": "tcred_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "test_credential" ], "description": "String representing the deleted object's type. Always \"test_credential\".", "example": "test_credential" }, "deleted": { "type": "boolean", "enum": [ true ], "description": "Always true.", "example": true } }, "required": [ "id", "object", "deleted" ], "description": "A deleted test credential." }, "StripeCheckoutConfig": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the stripe checkout config (scc_…).", "example": "scc_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "stripe_checkout_config" ], "description": "String representing the object's type. Always \"stripe_checkout_config\".", "example": "stripe_checkout_config" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "site": { "type": "string", "description": "The site the config belongs to.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "name": { "type": [ "string", "null" ], "description": "Your name for the config.", "example": "Pro monthly with 14-day trial" }, "params": { "type": "object", "additionalProperties": {}, "description": "The mirrored Checkout Session parameters (the subset of what your code passes to stripe.checkout.sessions.create that shapes what customers see).", "example": { "mode": "subscription", "line_items": [ { "price": "price_1Pro", "quantity": 1 } ], "subscription_data": { "trial_period_days": 14 }, "consent_collection": { "terms_of_service": "required" } } }, "params_hash": { "type": "string", "description": "sha256 of the canonical params; changes whenever the registered parameters change.", "example": "9f2c…" }, "ignored_params": { "type": "array", "items": { "type": "string" }, "description": "Parameters that were dropped because they are not mirrored (customer, URLs, metadata…).", "example": [ "success_url", "customer_email" ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Up to 20 key/value string pairs you can attach to the object.", "example": { "order_ref": "A-1001" } }, "created": { "type": "integer", "description": "When the config was registered. Unix timestamp in seconds.", "example": 1793318400 } }, "required": [ "id", "object", "livemode", "site", "name", "params", "params_hash", "ignored_params", "metadata", "created" ], "description": "Checkout Session parameters your code uses, registered so test runs mirror exactly your checkout into Stripe test mode." }, "StripeCheckoutConfigList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "String representing the object's type. Always \"list\".", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/StripeCheckoutConfig" }, "description": "Registered checkout configs, newest first.", "example": [ { "id": "scc_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "stripe_checkout_config", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "name": "Pro monthly with 14-day trial", "params": { "mode": "subscription", "line_items": [ { "price": "price_1Pro", "quantity": 1 } ], "subscription_data": { "trial_period_days": 14 }, "consent_collection": { "terms_of_service": "required" } }, "params_hash": "9f2c…", "ignored_params": [ "success_url", "customer_email" ], "metadata": { "order_ref": "A-1001" }, "created": 1793318400 } ] }, "has_more": { "type": "boolean", "description": "Whether more items exist after this page. Pass the last id as starting_after to fetch them.", "example": false }, "url": { "type": "string", "description": "The URL of this list.", "example": "/v1/sites" } }, "required": [ "object", "data", "has_more", "url" ], "description": "A page of registered checkout configs, newest first." }, "DeletedStripeCheckoutConfig": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the stripe checkout config (scc_…).", "example": "scc_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "stripe_checkout_config" ], "description": "String representing the deleted object's type. Always \"stripe_checkout_config\".", "example": "stripe_checkout_config" }, "deleted": { "type": "boolean", "enum": [ true ], "description": "Always true.", "example": true } }, "required": [ "id", "object", "deleted" ], "description": "A deleted stripe checkout config." }, "TestRunRemediation": { "type": [ "object", "null" ], "properties": { "summary": { "type": "string", "description": "What the law requires and what to change.", "example": "State the renewal terms next to the subscribe button." }, "steps": { "type": "array", "items": { "type": "string" }, "description": "Steps to fix it.", "example": [ "Add the disclosure above the button." ] }, "suggested_copy": { "type": [ "string", "null" ], "description": "Compliant copy to use, when there is one.", "example": "Renews automatically at $19/month until you cancel." }, "snippet": { "type": [ "object", "null" ], "properties": { "language": { "type": "string", "description": "Language of the code.", "example": "typescript" }, "code": { "type": "string", "description": "Code that applies the fix.", "example": "custom_text: { submit: { message: \"…\" } }" } }, "required": [ "language", "code" ], "description": "Code that applies the fix, when there is one.", "example": { "language": "typescript", "code": "custom_text: { submit: { message: \"…\" } }" } } }, "required": [ "summary", "steps", "suggested_copy", "snippet" ], "description": "How to fix a failing check." }, "TestRunFix": { "type": [ "object", "null" ], "properties": { "summary": { "type": "string", "description": "What to change, in one sentence.", "example": "Send the acknowledgment from your checkout.session.completed webhook." }, "steps": { "type": "array", "items": { "type": "string" }, "description": "Ordered instructions for the builder's agent.", "example": [ "Handle checkout.session.completed…" ] }, "where": { "type": "string", "description": "Where the change goes (Stripe Dashboard URL, file, component).", "example": "https://dashboard.stripe.com/test/apikeys" }, "operation_id": { "type": "string", "description": "API call that applies or retries the fix (SDK method name).", "example": "createTestRun" }, "stripe_params": { "type": "object", "additionalProperties": {}, "description": "Exact Stripe parameters to use, when the fix is a Stripe setting or object.", "example": { "features": { "subscription_cancel": { "enabled": true } } } }, "command": { "type": "string", "description": "Shell command that applies the fix (Stripe CLI), when there is one.", "example": "stripe prices create --unit-amount=1900 --currency=usd -d \"recurring[interval]=month\"" }, "docs_url": { "type": "string", "description": "Documentation for the fix.", "example": "https://checkbox.site/docs/test-runs#acknowledgment" } }, "required": [ "summary", "steps" ], "description": "An agent-readable fix: what to change, where, and how to verify (run again)." }, "TestRunStep": { "type": "object", "properties": { "key": { "type": "string", "description": "Stable step key: credentials, checkout_config, checkout_page, subscribe, acknowledgment_email, trial_reminder, renewal, cancel_online, cancellation_email, cleanup.", "example": "acknowledgment_email" }, "title": { "type": "string", "description": "Human-readable step title.", "example": "Acknowledgment email received" }, "status": { "type": "string", "enum": [ "pending", "running", "passed", "failed", "warning", "skipped" ], "description": "passed: observed and compliant; failed: a check failed or the step broke the run; warning: could not be fully observed (see code and fix); skipped: not applicable or turned off.", "example": "passed" }, "summary": { "type": [ "string", "null" ], "description": "What was observed, in one or two sentences.", "example": "1 email(s) arrived after sign-up: \"Welcome to Acme\" (acknowledgment)." }, "started": { "type": [ "integer", "null" ], "description": "When the step started. Unix timestamp in seconds.", "example": 1793318400 }, "finished": { "type": [ "integer", "null" ], "description": "When the step finished. Unix timestamp in seconds.", "example": 1793318400 }, "check_ids": { "type": "array", "items": { "type": "string" }, "description": "Checks this step produces evidence for.", "example": [ "confirmation.email.sent" ] }, "checks": { "type": "array", "items": { "type": "object", "properties": { "check_id": { "type": "string", "description": "Machine check id (see listRules / the legal catalog).", "example": "confirmation.email.terms" }, "status": { "type": "string", "description": "pass, fail, needs_review or not_applicable, judged from this run's observations.", "example": "fail" }, "message": { "type": "string", "description": "What was observed.", "example": "The acknowledgment does not state the renewal price." }, "severity": { "type": [ "string", "null" ], "description": "critical, high, medium or low.", "example": "high" }, "remediation": { "$ref": "#/components/schemas/TestRunRemediation" } }, "required": [ "check_id", "status", "message", "severity", "remediation" ] }, "description": "Check results judged from this run's observations (test-clock time).", "example": [] }, "observations": { "type": "object", "additionalProperties": {}, "description": "Step-specific facts: URLs, ids, timings (e.g. sent_days_before for reminders), hashes.", "example": { "emails": [ { "subject": "Welcome to Acme", "kind": "acknowledgment", "seconds_after_signup": 4 } ] } }, "evidence": { "type": "array", "items": { "type": "string" }, "description": "Evidence records (screenshots, page captures, raw emails) behind the step.", "example": [ "ev_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" ] }, "code": { "type": [ "string", "null" ], "description": "Warning or failure code of the step (stable): key_missing, key_not_test_mode, key_invalid, key_permission_missing, checkout_config_missing, price_not_in_test_mode, checkout_session_failed, checkout_page_unreadable, checkout_not_completed, subscription_create_failed, test_clock_failed, no_email_received_within, reminder_not_received, portal_not_configured, cancel_not_completed, cancellation_email_not_received, scan_config_missing, scanner_failed, stripe_api_error, timeout, canceled, internal_error.", "example": "no_email_received_within" }, "fix": { "$ref": "#/components/schemas/TestRunFix" } }, "required": [ "key", "title", "status", "summary", "started", "finished", "check_ids", "checks", "observations", "evidence", "code", "fix" ], "description": "One observed lifecycle step of a test run." }, "TestRun": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the test run (run_…).", "example": "run_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "test_run" ], "description": "String representing the object's type. Always \"test_run\".", "example": "test_run" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "site": { "type": "string", "description": "The site under test.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "type": { "type": "string", "enum": [ "stripe", "generic" ], "description": "stripe: Stripe test mode with a test clock; generic: any site with a test coupon / test account (no time travel).", "example": "stripe" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "canceled" ], "description": "succeeded means the run finished (steps may still have failing checks); failed means it stopped early (see failure).", "example": "running" }, "phase": { "type": "string", "description": "Internal phase (prepare, checkout, await_ack, advance, settle, cancel, await_cancel_email, finalize, done).", "example": "await_ack" }, "test_mode": { "type": "boolean", "enum": [ true ], "description": "Always true: runs use the billing platform's test mode; nothing is charged.", "example": true }, "inbox_address": { "type": "string", "description": "Email address of the synthetic test subscriber; mail sent there is captured as evidence.", "example": "k3y9+run-3f9a1c2e7b4d@in.checkbox.site" }, "created": { "type": "integer", "description": "When the run was created. Unix timestamp in seconds.", "example": 1793318400 }, "started": { "type": [ "integer", "null" ], "description": "When the worker started it. Unix timestamp in seconds.", "example": 1793318400 }, "finished": { "type": [ "integer", "null" ], "description": "When it finished. Unix timestamp in seconds.", "example": 1793318400 }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/TestRunStep" }, "description": "Lifecycle steps in order.", "example": [] }, "failure": { "type": [ "object", "null" ], "properties": { "code": { "type": "string", "description": "Stable failure code: key_missing, key_not_test_mode, key_invalid, key_permission_missing, checkout_config_missing, price_not_in_test_mode, checkout_session_failed, checkout_page_unreadable, checkout_not_completed, subscription_create_failed, test_clock_failed, no_email_received_within, reminder_not_received, portal_not_configured, cancel_not_completed, cancellation_email_not_received, scan_config_missing, scanner_failed, stripe_api_error, timeout, canceled, internal_error.", "example": "price_not_in_test_mode" }, "message": { "type": "string", "description": "What went wrong.", "example": "Price price_1Live does not exist in Stripe test mode." }, "detail": { "type": "object", "additionalProperties": {}, "description": "Code-specific details (e.g. prices: the exact parameters to create in test mode).", "example": { "prices": [] } }, "fix": { "$ref": "#/components/schemas/TestRunFix" } }, "required": [ "code", "message", "detail", "fix" ], "description": "Why the run stopped (failed / canceled runs).", "example": { "code": "price_not_in_test_mode", "message": "Price price_1Live does not exist in Stripe test mode.", "detail": { "prices": [] }, "fix": { "summary": "Send the acknowledgment from your checkout.session.completed webhook.", "steps": [ "Handle checkout.session.completed…" ], "where": "https://dashboard.stripe.com/test/apikeys", "operation_id": "createTestRun", "stripe_params": { "features": { "subscription_cancel": { "enabled": true } } }, "command": "stripe prices create --unit-amount=1900 --currency=usd -d \"recurring[interval]=month\"", "docs_url": "https://checkbox.site/docs/test-runs#acknowledgment" } } }, "result": { "type": [ "object", "null" ], "properties": { "score": { "type": [ "number", "null" ], "description": "Compliance score (0-100) of the observed steps alone.", "example": 82 }, "summary": { "type": "object", "properties": { "passed": { "type": "integer", "description": "Checks that passed.", "example": 9 }, "failed": { "type": "integer", "description": "Checks that failed.", "example": 2 }, "needs_review": { "type": "integer", "description": "Checks that need review.", "example": 1 }, "warnings": { "type": "integer", "description": "Steps that could not be fully observed.", "example": 1 } }, "required": [ "passed", "failed", "needs_review", "warnings" ], "description": "Counts.", "example": { "passed": 9, "failed": 2, "needs_review": 1, "warnings": 1 } }, "checks": { "type": "array", "items": { "type": "object", "properties": { "check_id": { "type": "string", "description": "Check id.", "example": "reminder.trial_ending" }, "status": { "type": "string", "description": "Result.", "example": "pass" }, "step": { "type": "string", "description": "Step key that observed it.", "example": "trial_reminder" } }, "required": [ "check_id", "status", "step" ] }, "description": "Every check result of the run.", "example": [] }, "monitoring": { "type": "object", "properties": { "checkout_page_counted": { "type": "boolean", "description": "The scanned checkout counts in continuous monitoring (mirrored config matches live).", "example": true }, "cancellation_flow_counted": { "type": "boolean", "description": "The cancellation flow counts in continuous monitoring.", "example": true }, "emails_counted": { "type": "integer", "description": "Emails added to the site's evidence (labelled test_run).", "example": 3 }, "reminder_events": { "type": "integer", "description": "Reminder occasions added with their observed timing.", "example": 1 }, "notes": { "type": "array", "items": { "type": "string" }, "description": "Why something was kept in the run report only.", "example": [] } }, "required": [ "checkout_page_counted", "cancellation_flow_counted", "emails_counted", "reminder_events", "notes" ], "description": "What the run added to the site's continuous monitoring (provenance test_run).", "example": { "checkout_page_counted": true, "cancellation_flow_counted": true, "emails_counted": 3, "reminder_events": 1, "notes": [] } } }, "required": [ "score", "summary", "checks", "monitoring" ], "description": "Outcome of a finished run.", "example": { "score": 82, "summary": { "passed": 9, "failed": 2, "needs_review": 1, "warnings": 1 }, "checks": [], "monitoring": { "checkout_page_counted": true, "cancellation_flow_counted": true, "emails_counted": 3, "reminder_events": 1, "notes": [] } } }, "stripe": { "type": [ "object", "null" ], "properties": { "test_clock": { "type": [ "string", "null" ], "description": "Stripe test clock (deleted at the end).", "example": "clock_1Q…" }, "customer": { "type": [ "string", "null" ], "description": "Test customer (the synthetic subscriber).", "example": "cus_Q…" }, "subscription": { "type": [ "string", "null" ], "description": "Test subscription.", "example": "sub_1Q…" }, "checkout_session": { "type": [ "string", "null" ], "description": "Mirrored test-mode Checkout Session.", "example": "cs_test_a1…" }, "mirrored_from": { "type": [ "string", "null" ], "enum": [ "registered", "live", "request" ], "description": "Where the checkout configuration came from.", "example": "registered" }, "checkout_config": { "type": [ "string", "null" ], "description": "Registered config used (scc_…).", "example": null }, "config_hash": { "type": [ "string", "null" ], "description": "Compliance fingerprint of the mirrored checkout.", "example": "4be1…" }, "matches_live": { "type": [ "boolean", "null" ], "description": "Whether the mirrored checkout matches your latest live checkout (null: no live connection to compare).", "example": true }, "cleaned_up": { "type": "boolean", "description": "Whether the test clock (with its customer and subscription) was deleted.", "example": true } }, "required": [ "test_clock", "customer", "subscription", "checkout_session", "mirrored_from", "checkout_config", "config_hash", "matches_live", "cleaned_up" ], "description": "Stripe test-mode objects of the run (type stripe).", "example": { "test_clock": "clock_1Q…", "customer": "cus_Q…", "subscription": "sub_1Q…", "checkout_session": "cs_test_a1…", "mirrored_from": "registered", "checkout_config": null, "config_hash": "4be1…", "matches_live": true, "cleaned_up": true } }, "next_action": { "$ref": "#/components/schemas/NextAction" } }, "required": [ "id", "object", "livemode", "site", "type", "status", "phase", "test_mode", "inbox_address", "created", "started", "finished", "steps", "failure", "result", "stripe", "next_action" ], "description": "A synthetic test subscription that observes the whole subscription lifecycle in test mode and reports each step with evidence, check results and fixes." }, "TestRunList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "String representing the object's type. Always \"list\".", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TestRun" }, "description": "Test runs, newest first.", "example": [ { "id": "run_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "test_run", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "type": "stripe", "status": "running", "phase": "await_ack", "test_mode": true, "inbox_address": "k3y9+run-3f9a1c2e7b4d@in.checkbox.site", "created": 1793318400, "started": 1793318400, "finished": 1793318400, "steps": [], "failure": { "code": "price_not_in_test_mode", "message": "Price price_1Live does not exist in Stripe test mode.", "detail": { "prices": [] }, "fix": { "summary": "Send the acknowledgment from your checkout.session.completed webhook.", "steps": [ "Handle checkout.session.completed…" ], "where": "https://dashboard.stripe.com/test/apikeys", "operation_id": "createTestRun", "stripe_params": { "features": { "subscription_cancel": { "enabled": true } } }, "command": "stripe prices create --unit-amount=1900 --currency=usd -d \"recurring[interval]=month\"", "docs_url": "https://checkbox.site/docs/test-runs#acknowledgment" } }, "result": { "score": 82, "summary": { "passed": 9, "failed": 2, "needs_review": 1, "warnings": 1 }, "checks": [], "monitoring": { "checkout_page_counted": true, "cancellation_flow_counted": true, "emails_counted": 3, "reminder_events": 1, "notes": [] } }, "stripe": { "test_clock": "clock_1Q…", "customer": "cus_Q…", "subscription": "sub_1Q…", "checkout_session": "cs_test_a1…", "mirrored_from": "registered", "checkout_config": null, "config_hash": "4be1…", "matches_live": true, "cleaned_up": true }, "next_action": { "type": "verify_domain", "message": "Verify your site domain to turn on live mode.", "operation_id": "createDomainVerification", "mcp_tool": "call_api", "url": "https://checkbox.site/docs/api/activation" } } ] }, "has_more": { "type": "boolean", "description": "Whether more items exist after this page. Pass the last id as starting_after to fetch them.", "example": false }, "url": { "type": "string", "description": "The URL of this list.", "example": "/v1/sites" } }, "required": [ "object", "data", "has_more", "url" ], "description": "A page of test runs, newest first." }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the webhook endpoint (we_…).", "example": "we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "webhook_endpoint" ], "description": "String representing the object's type. Always \"webhook_endpoint\".", "example": "webhook_endpoint" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "url": { "type": "string", "description": "HTTPS URL Checkbox POSTs events to.", "example": "https://acme.example/webhooks/checkbox" }, "description": { "type": [ "string", "null" ], "description": "Your description.", "example": "Production listener" }, "enabled_events": { "type": "array", "items": { "type": "string" }, "description": "Event types sent to this endpoint (\"*\" = all).", "example": [ "*" ] }, "status": { "type": "string", "enum": [ "enabled", "disabled" ], "description": "Disabled endpoints receive nothing.", "example": "enabled" }, "api_version": { "type": "string", "description": "API version events are rendered with.", "example": "2026-10-30" }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Up to 20 key/value string pairs you can attach to the object.", "example": { "order_ref": "A-1001" } }, "secret": { "type": "string", "description": "Signing secret (whsec_…). Only returned when the endpoint is created or the secret is rolled; store it.", "example": "whsec_6Jf…" }, "created": { "type": "integer", "description": "When the endpoint was created. Unix timestamp in seconds.", "example": 1793318400 } }, "required": [ "id", "object", "livemode", "url", "description", "enabled_events", "status", "api_version", "metadata", "created" ], "description": "Where Checkbox sends signed event notifications (Checkbox-Signature: t=…,v1=…)." }, "WebhookEndpointList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "String representing the object's type. Always \"list\".", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" }, "description": "Webhook endpoints, newest first.", "example": [ { "id": "we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "webhook_endpoint", "livemode": false, "url": "https://acme.example/webhooks/checkbox", "description": "Production listener", "enabled_events": [ "*" ], "status": "enabled", "api_version": "2026-10-30", "metadata": { "order_ref": "A-1001" }, "secret": "whsec_6Jf…", "created": 1793318400 } ] }, "has_more": { "type": "boolean", "description": "Whether more items exist after this page. Pass the last id as starting_after to fetch them.", "example": false }, "url": { "type": "string", "description": "The URL of this list.", "example": "/v1/sites" } }, "required": [ "object", "data", "has_more", "url" ], "description": "A page of webhook endpoints, newest first." }, "DeletedWebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the webhook endpoint (we_…).", "example": "we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "webhook_endpoint" ], "description": "String representing the deleted object's type. Always \"webhook_endpoint\".", "example": "webhook_endpoint" }, "deleted": { "type": "boolean", "enum": [ true ], "description": "Always true.", "example": true } }, "required": [ "id", "object", "deleted" ], "description": "A deleted webhook endpoint." }, "Event": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the event (evt_…).", "example": "evt_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "event" ], "description": "String representing the object's type. Always \"event\".", "example": "event" }, "type": { "type": "string", "description": "Event type: site.score_changed, site.insurable_changed, finding.created, finding.resolved, scan.completed, scan.failed, law.changed, certificate.issued, certificate.lapsed, certificate.revoked, notice.sent, consent.created, test_run.completed, test_run.failed, plan.updated, site.compliant, task.verified.", "example": "finding.created" }, "api_version": { "type": "string", "description": "API version used to render data.object.", "example": "2026-10-30" }, "created": { "type": "integer", "description": "When the event happened. Unix timestamp in seconds.", "example": 1793318400 }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "data": { "type": "object", "properties": { "object": { "type": "object", "additionalProperties": {}, "description": "The object the event is about (a site, finding, scan, certificate, law_update or notice), as the API returns it.", "example": { "id": "fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "finding" } }, "previous_attributes": { "type": "object", "additionalProperties": {}, "description": "For *_changed events: the previous values of the changed fields.", "example": { "score": 74 } } }, "required": [ "object" ], "description": "Event payload.", "example": { "object": { "id": "fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "finding" }, "previous_attributes": { "score": 74 } } }, "pending_webhooks": { "type": "integer", "description": "Webhook deliveries not yet acknowledged.", "example": 0 }, "request": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "description": "API request that caused the event (null for automatic changes).", "example": null }, "idempotency_key": { "type": [ "string", "null" ], "description": "Idempotency-Key of that request.", "example": null } }, "required": [ "id", "idempotency_key" ], "description": "What caused the event.", "example": { "id": null, "idempotency_key": null } } }, "required": [ "id", "object", "type", "api_version", "created", "livemode", "data", "pending_webhooks", "request" ], "description": "Something that happened in the account. Delivered to webhook endpoints and listed by listEvents (kept 30 days)." }, "EventList": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "list" ], "description": "String representing the object's type. Always \"list\".", "example": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" }, "description": "Events, newest first.", "example": [ { "id": "evt_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "event", "type": "finding.created", "api_version": "2026-10-30", "created": 1793318400, "livemode": false, "data": { "object": { "id": "fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "finding" }, "previous_attributes": { "score": 74 } }, "pending_webhooks": 0, "request": { "id": null, "idempotency_key": null } } ] }, "has_more": { "type": "boolean", "description": "Whether more items exist after this page. Pass the last id as starting_after to fetch them.", "example": false }, "url": { "type": "string", "description": "The URL of this list.", "example": "/v1/sites" } }, "required": [ "object", "data", "has_more", "url" ], "description": "A page of events, newest first." }, "CompliancePlanSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the compliance plan (plan_…).", "example": "plan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "compliance_plan" ], "description": "String representing the object's type. Always \"compliance_plan\".", "example": "compliance_plan" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "site": { "type": "string", "description": "The site.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "status": { "type": "string", "enum": [ "action_required", "verifying", "compliant", "blocked" ], "description": "action_required (an agent can apply open tasks now), verifying (changes applied; waiting for confirming observations), compliant (every applicable check Checkbox could observe passes — an automated assessment, not a legal determination; see coverage for what was not observed), blocked (only human answers or declined critical tasks remain).", "example": "action_required" }, "score": { "type": [ "integer", "null" ], "description": "Compliance score 0-100 of the latest evaluation.", "example": 62 }, "insurable": { "type": [ "boolean", "null" ], "description": "Preview flag the planned Checkbox Warranty will key on (no checks failing at high severity). No warranty or insurance is offered yet; this is not an underwriting decision.", "example": false }, "summary": { "type": "string", "description": "Two or three sentences for an LLM: where the site stands and what comes next.", "example": "StreamMax fails 4 critical checks…" }, "counts": { "type": "object", "properties": { "open": { "type": "integer", "description": "Open tasks.", "example": 3 }, "in_progress": { "type": "integer", "description": "Claimed tasks.", "example": 0 }, "verifying": { "type": "integer", "description": "Tasks waiting for a confirming observation.", "example": 1 }, "manual": { "type": "integer", "description": "Tasks waiting for a human answer.", "example": 1 }, "done": { "type": "integer", "description": "Done tasks.", "example": 2 }, "wont_fix": { "type": "integer", "description": "Declined tasks.", "example": 0 } }, "required": [ "open", "in_progress", "verifying", "manual", "done", "wont_fix" ], "description": "Tasks per status.", "example": { "open": 3, "in_progress": 0, "verifying": 1, "manual": 1, "done": 2, "wont_fix": 0 } }, "next_action": { "$ref": "#/components/schemas/PlanNextAction" }, "coverage": { "type": "object", "properties": { "observed": { "type": "array", "items": { "type": "string" }, "description": "Lifecycle stages Checkbox observed (signup, acknowledgment_email, reminders, cancellation, policies, billing_settings).", "example": [ "signup", "policies" ] }, "not_observed": { "type": "array", "items": { "type": "string" }, "description": "Stages Checkbox has no observation of: their checks cannot fail, so passing says nothing about them.", "example": [ "cancellation", "billing_settings" ] }, "attested": { "type": "array", "items": { "type": "string" }, "description": "Task keys resting on a human confirmation instead of an observation.", "example": [] }, "billing_connected": { "type": "boolean", "description": "A billing platform is connected (dashboard).", "example": false } }, "required": [ "observed", "not_observed", "attested", "billing_connected" ], "description": "What the assessment rests on. Tell the human about not_observed and attested items; never call the site \"compliant\" without them.", "example": { "observed": [ "signup", "policies" ], "not_observed": [ "cancellation", "billing_settings" ], "attested": [], "billing_connected": false } }, "generated": { "type": "integer", "description": "When the plan was computed. Unix timestamp in seconds.", "example": 1793318400 }, "tasks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the task (task_…).", "example": "task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "key": { "type": "string", "description": "Task key.", "example": "signup_disclosure" }, "status": { "type": "string", "enum": [ "open", "in_progress", "verifying", "done", "wont_fix", "manual" ], "description": "Task status.", "example": "open" }, "priority": { "type": "string", "enum": [ "critical", "high", "medium", "low" ], "description": "Priority.", "example": "critical" }, "title": { "type": "string", "description": "Title.", "example": "Show the renewal terms above the purchase button" } }, "required": [ "id", "key", "status", "priority", "title" ] }, "description": "Tasks (id, key, status, priority, title) in plan order.", "example": [ { "id": "task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "key": "signup_disclosure", "status": "open", "priority": "critical", "title": "Show the renewal terms above the purchase button" } ] } }, "required": [ "id", "object", "livemode", "site", "status", "score", "insurable", "summary", "counts", "next_action", "coverage", "generated", "tasks" ], "description": "A compliance plan without task content (webhook payload)." }, "Notice": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the notice (ntc_…).", "example": "ntc_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "object": { "type": "string", "enum": [ "notice" ], "description": "String representing the object's type. Always \"notice\".", "example": "notice" }, "livemode": { "type": "boolean", "description": "true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).", "example": false }, "site": { "type": "string", "description": "The site.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "kind": { "type": "string", "enum": [ "acknowledgment", "trial_ending", "renewal_reminder", "annual_terms", "price_change" ], "description": "Notice kind.", "example": "renewal_reminder" }, "status": { "type": "string", "enum": [ "claimed", "sent", "failed", "bounced", "skipped" ], "description": "Delivery status.", "example": "sent" }, "platform": { "type": "string", "description": "Billing platform of the subscription.", "example": "stripe" }, "subscription": { "type": "string", "description": "Billing-platform subscription id.", "example": "sub_1Q…" }, "recipient": { "type": [ "string", "null" ], "description": "Masked recipient address.", "example": "j***@example.com" }, "subject": { "type": [ "string", "null" ], "description": "Subject line.", "example": "Your Acme Coffee Club subscription renews on 1 December" }, "sent": { "type": [ "integer", "null" ], "description": "When it was sent. Unix timestamp in seconds.", "example": 1793318400 }, "late": { "type": "boolean", "description": "Sent after the legal window opened late (e.g. the subscription was imported late).", "example": false }, "evidence": { "type": [ "string", "null" ], "description": "Evidence record of the sent email.", "example": "ev_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" } }, "required": [ "id", "object", "livemode", "site", "kind", "status", "platform", "subscription", "recipient", "subject", "sent", "late", "evidence" ], "description": "A legally required notice Checkbox sent for the merchant." } }, "parameters": {} }, "paths": { "/v1/device/authorize": { "post": { "operationId": "createDeviceAuthorization", "summary": "Start a device login (setup_checkbox)", "description": "Public (no API key). Returns a device_code (keep it private), a user_code and verification_uri_complete. Show the human ONE line (\"Open and click Approve\"), open it in their browser when possible, then poll createDeviceToken every `interval` seconds. New users sign up on that page with an email link or GitHub / Google; nothing is created until they click Approve.", "tags": [ "Agent setup" ], "security": [], "x-checkbox-scope": "none", "parameters": [ { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceAuthorizationParams" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceAuthorization" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/device/token": { "post": { "operationId": "createDeviceToken", "summary": "Poll a device login for its keys", "description": "Public (no API key). Poll every `interval` seconds with the device_code. Errors (stable codes): authorization_pending (keep polling), slow_down (add 5 s), access_denied (the human clicked Deny: stop), expired_token (start again). On approval returns the keys exactly once, the setup session and the next action.", "tags": [ "Agent setup" ], "security": [], "x-checkbox-scope": "none", "parameters": [ { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "device_code": { "type": "string", "minLength": 10, "maxLength": 200, "description": "The device_code from createDeviceAuthorization.", "example": "cbdev_Q2hlY2tib3g…" } }, "required": [ "device_code" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceToken" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/setup_sessions": { "post": { "operationId": "createSetupSession", "summary": "Start a setup session (agents that already have a key)", "description": "For agents that already hold a secret key (no device login): starts a setup session for a project with the same fields as updateSetupSession. `checkbox init` creates the session during the device login instead.", "tags": [ "Agent setup" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "setup_sessions:write", "x-checkbox-min-role": "admin", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupSessionUpdate" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupSession" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listSetupSessions", "summary": "List setup sessions", "description": "Setup sessions of the account, newest first. Test keys see the sessions created in test mode (device login, test keys); live keys see all.", "tags": [ "Agent setup" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "setup_sessions:read", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of objects to return, 1-100 (default 10).", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects after it (older).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects before it (newer).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "ending_before", "in": "query" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupSessionList" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/setup_sessions/{setup_session}": { "get": { "operationId": "retrieveSetupSession", "summary": "Retrieve a setup session", "description": "The setup checklist with one next_action. Agents: do next_action, then call verifySetupSession; stop when next_action.type is \"done\".", "tags": [ "Agent setup" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "setup_sessions:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the setup session (setup_…).", "example": "setup_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "setup_session", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupSession" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "updateSetupSession", "summary": "Report what the agent learned or changed", "description": "Reports project facts and business URLs: site_url (creates the test-mode site), checkout_url, terms_url / refund_url / cancellation_url / privacy_url (fetched now, stored as evidence and checked against the law), plans, where checkout code lives, snippet_installed_in, env_written. Returns the updated checklist.", "tags": [ "Agent setup" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "setup_sessions:write", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the setup session (setup_…).", "example": "setup_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "setup_session", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupSessionUpdate" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupSession" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/setup_sessions/{setup_session}/verify": { "post": { "operationId": "verifySetupSession", "summary": "Re-check the site now", "description": "Loads the site (is the snippet live? which policy links does it have?), re-fetches the Terms and policies, re-evaluates compliance and queues the first synthetic-shopper scan. Call it after every change the agent made (and after deploying). Returns what was seen plus the updated session.", "tags": [ "Agent setup" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "setup_sessions:write", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the setup session (setup_…).", "example": "setup_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "setup_session", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupVerification" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/setup_sessions/{setup_session}/complete": { "post": { "operationId": "completeSetupSession", "summary": "Finish the setup and notify the human", "description": "Marks the setup finished and emails the person who approved it a summary (\" set up Checkbox for \") with what was created, what is still open and a review link. Idempotent: the email is sent once. Checks keep running afterwards.", "tags": [ "Agent setup" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "setup_sessions:write", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the setup session (setup_…).", "example": "setup_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "setup_session", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetupSession" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/account": { "get": { "operationId": "retrieveAccount", "summary": "Retrieve the account", "description": "Returns the account behind the key: test or live mode, whether live mode is activated, fair-use limits, the publishable key, and `next_action`. Call this first to check a key.", "tags": [ "Account" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "account:read", "parameters": [ { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "updateAccount", "summary": "Update the account", "description": "Pins the account to an API version (requests without a Checkbox-Version header use it). Known versions: 2026-10-30.", "tags": [ "Account" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "account:write", "x-checkbox-min-role": "admin", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "api_version": { "type": "string", "description": "API version to pin.", "example": "2026-10-30" } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sites": { "get": { "operationId": "listSites", "summary": "List sites", "description": "Returns the sites of the account in the current mode, newest first. Archived sites are included only with archived=true.", "tags": [ "Sites" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "sites:read", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of objects to return, 1-100 (default 10).", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects after it (older).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects before it (newer).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "ending_before", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "description": "true lists only archived sites.", "example": "false" }, "required": false, "name": "archived", "in": "query" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteList" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createSite", "summary": "Create a site", "description": "Registers a subscription business. Only `url` is required; Checkbox derives the name and uses the URL as the checkout entry page. The response includes `install` (snippet tag, inbound email, platform webhook URLs). Next: install the snippet, then run createScan (or let `checkbox init` do both). In live mode before activation, monitoring is held until a domain is verified; in test mode, monitoring of a host that is not localhost or a domain the account verified is held the same way, and on-demand scans of such hosts are limited to a few a day.", "tags": [ "Sites" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "sites:write", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSiteParams" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Site" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sites/{site}": { "get": { "operationId": "retrieveSite", "summary": "Retrieve a site", "description": "Returns a site with its latest compliance verdict (score, insurable) and install details.", "tags": [ "Sites" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "sites:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "latest_scan", "domain_verification" ] }, "description": "Related objects to include inline: latest_scan, domain_verification. Pass as expand[]=name.", "example": [ "latest_scan" ] }, "required": false, "name": "expand[]", "in": "query" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Site" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "updateSite", "summary": "Update a site", "description": "Updates the given fields; omitted fields keep their values. Changing `url` to another domain forgets the domain verification and ends the active certificate.", "tags": [ "Sites" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "sites:write", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSiteParams" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Site" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteSite", "summary": "Archive a site", "description": "Archives (soft-deletes) the site: monitoring stops and it disappears from lists, but evidence and findings are retained for the warranty. Undo with restoreSite.", "tags": [ "Sites" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "sites:write", "x-checkbox-min-role": "admin", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Site" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sites/{site}/restore": { "post": { "operationId": "restoreSite", "summary": "Restore an archived site", "description": "Un-archives a site (counts against the fair-use site limit again).", "tags": [ "Sites" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "sites:write", "x-checkbox-min-role": "admin", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Site" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sites/{site}/domain_verification": { "get": { "operationId": "retrieveDomainVerification", "summary": "Retrieve domain verification", "description": "Status of the site domain verification, with the DNS record / file to publish.", "tags": [ "Sites" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "sites:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/DomainVerification" }, { "description": "Proof that the account controls the site domain. Verifying any live site activates live mode." } ] } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createDomainVerification", "summary": "Start domain verification", "description": "Starts verification of the site domain and returns a DNS TXT record and a /.well-known file; publishing either proves control. Then call checkDomainVerification. Verifying a live-mode site activates live mode for the account (instant, self-serve).", "tags": [ "Sites" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "sites:write", "x-checkbox-min-role": "admin", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rotate": { "type": "boolean", "description": "Issue a new token (invalidates the old one).", "example": false } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/DomainVerification" }, { "description": "Proof that the account controls the site domain. Verifying any live site activates live mode." } ] } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sites/{site}/domain_verification/check": { "post": { "operationId": "checkDomainVerification", "summary": "Check domain verification now", "description": "Looks for the DNS TXT record and the /.well-known file now. On success in live mode, the account is activated and held monitoring starts.", "tags": [ "Sites" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "sites:write", "x-checkbox-min-role": "admin", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/DomainVerification" }, { "description": "Proof that the account controls the site domain. Verifying any live site activates live mode." } ] } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sites/{site}/scans": { "post": { "operationId": "createScan", "summary": "Run a scan", "description": "Queues a synthetic-shopper scan of the site. Poll retrieveScan (or wait for the scan.completed webhook); a scan takes 1-3 minutes. When it completes, the evaluation and findings are updated. In live mode the account must be activated.", "tags": [ "Scans" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "scans:write", "x-checkbox-requires-activation": true, "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "regions": { "type": "array", "items": { "type": "string", "enum": [ "US-FED", "US-AL", "US-AK", "US-AZ", "US-AR", "US-CA", "US-CO", "US-CT", "US-DE", "US-DC", "US-FL", "US-GA", "US-HI", "US-ID", "US-IL", "US-IN", "US-IA", "US-KS", "US-KY", "US-LA", "US-ME", "US-MD", "US-MA", "US-MI", "US-MN", "US-MS", "US-MO", "US-MT", "US-NE", "US-NV", "US-NH", "US-NJ", "US-NM", "US-NY", "US-NC", "US-ND", "US-OH", "US-OK", "US-OR", "US-PA", "US-RI", "US-SC", "US-SD", "US-TN", "US-TX", "US-UT", "US-VT", "US-VA", "US-WA", "US-WV", "US-WI", "US-WY" ] }, "minItems": 1, "description": "States to scan from (default: the site configuration).", "example": [ "US-CA" ] } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Scan" }, { "description": "One synthetic-shopper run (checkout per state and device, optional sign-up and cancellation attempt) or evaluation-only run." } ] } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/scans": { "get": { "operationId": "listScans", "summary": "List scans", "description": "Scans newest first, optionally for one site.", "tags": [ "Scans" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "scans:read", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of objects to return, 1-100 (default 10).", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects after it (older).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects before it (newer).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "ending_before", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Only objects of this site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "site", "in": "query" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanList" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/scans/{scan}": { "get": { "operationId": "retrieveScan", "summary": "Retrieve a scan", "description": "Returns a scan. When status is completed, `evaluation` names the verdict (retrieveEvaluation).", "tags": [ "Scans" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "scans:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the scan (scan_…).", "example": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "scan", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Scan" }, { "description": "One synthetic-shopper run (checkout per state and device, optional sign-up and cancellation attempt) or evaluation-only run." } ] } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sites/{site}/evaluations": { "post": { "operationId": "createEvaluation", "summary": "Re-evaluate a site now", "description": "Re-runs the legal rules against the evidence already collected (no new scan) and returns the verdict synchronously. Use after changing site facts, or to get a verdict right after evidence arrived.", "tags": [ "Evaluations" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "evaluations:write", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Evaluation" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/evaluations": { "get": { "operationId": "listEvaluations", "summary": "List evaluations", "description": "Verdicts newest first (score history), optionally for one site.", "tags": [ "Evaluations" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "evaluations:read", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of objects to return, 1-100 (default 10).", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects after it (older).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects before it (newer).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "ending_before", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Only objects of this site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "site", "in": "query" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationList" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/evaluations/{evaluation}": { "get": { "operationId": "retrieveEvaluation", "summary": "Retrieve an evaluation", "description": "Returns one verdict with all checks and the insurability blockers.", "tags": [ "Evaluations" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "evaluations:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the evaluation (eval_…).", "example": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "evaluation", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Evaluation" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sites/{site}/evaluation": { "get": { "operationId": "retrieveLatestEvaluation", "summary": "Get the current verdict of a site", "description": "The latest evaluation of the site: is it compliant (score) and insurable, and what blocks it. 404 resource_missing with next_action createScan when the site was never evaluated.", "tags": [ "Evaluations" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "evaluations:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Evaluation" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/findings": { "get": { "operationId": "listFindings", "summary": "List findings", "description": "Findings ordered by urgency (failing first, then by severity). Filter by site, status (fail, needs_review, pass, not_applicable) and state (open, acknowledged, resolved, accepted_risk). Fix the open `fail` findings to become compliant.", "tags": [ "Findings" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "findings:read", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of objects to return, 1-100 (default 10).", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects after it (older).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects before it (newer).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "ending_before", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Only objects of this site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "site", "in": "query" }, { "schema": { "type": "string", "enum": [ "pass", "fail", "needs_review", "not_applicable" ], "description": "Only this check status.", "example": "fail" }, "required": false, "name": "status", "in": "query" }, { "schema": { "type": "string", "enum": [ "open", "acknowledged", "resolved", "accepted_risk" ], "description": "Only this triage state.", "example": "open" }, "required": false, "name": "state", "in": "query" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FindingList" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/findings/{finding}": { "get": { "operationId": "retrieveFinding", "summary": "Retrieve a finding", "description": "One finding with its legal requirements (citations), evidence references and remediation.", "tags": [ "Findings" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "findings:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the finding (fnd_…).", "example": "fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "finding", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Finding" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "updateFinding", "summary": "Triage a finding", "description": "Sets the triage state (open, acknowledged, accepted_risk, resolved) and an optional note. Triage does not change the check result; fixing the issue and re-scanning does.", "tags": [ "Findings" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "findings:write", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the finding (fnd_…).", "example": "fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "finding", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "open", "acknowledged", "resolved", "accepted_risk" ], "description": "New triage state.", "example": "acknowledged" }, "note": { "type": "string", "maxLength": 5000, "description": "Why (kept with the finding).", "example": "Fix scheduled for the next release." } }, "required": [ "state" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Finding" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sites/{site}/plan": { "get": { "operationId": "retrieveCompliancePlan", "summary": "Get the compliance plan for a site", "description": "Ordered tasks that make the site compliant, recomputed from its latest evaluation: each with the requirement and citation, where to change (file / URL / selector / Stripe object), the exact change (unified-diff template with machine-applicable edits, copy, or Stripe params) and how to verify it. Do plan.next_action: apply the first open task, call verifyTask, repeat until status is compliant. Tasks with status manual hold a question for the human (answerTask); they never block the others.", "tags": [ "Compliance plans" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "compliance_plans:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompliancePlan" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tasks/{task}": { "get": { "operationId": "retrieveTask", "summary": "Get one task of a compliance plan", "description": "The task as in the current plan (recomputed): the change to apply, how to verify, its last verification and next_action.", "tags": [ "Compliance plans" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "compliance_plans:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the task (task_…).", "example": "task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "task", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "updateTask", "summary": "Claim, decline or reopen a task", "description": "status in_progress claims the task (shown to other agents and the dashboard); wont_fix declines it with a reason (the merchant's decision, recorded; a declined critical or high task keeps the plan blocked); open clears the decision. Applying a change does not need this call: call verifyTask.", "tags": [ "Compliance plans" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "compliance_plans:write", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the task (task_…).", "example": "task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "task", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateTaskParams" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tasks/{task}/answer": { "post": { "operationId": "answerTask", "summary": "Record the human answer to a manual task", "description": "For tasks with status manual: record the human's answer to task.question (ask them; never answer on their behalf). Answers that assert a legal fact (yes, confirmed) are stored as a proposal and return next_action.type \"ask_human_to_confirm\" with a link the human opens while signed in to Checkbox; only their confirmation writes the attestation, sets the site fact and re-evaluates. no / needs_change turn the task into a change for the agent; done (after a dashboard-only step) re-checks at once. Every answer is stored in the evidence vault.", "tags": [ "Compliance plans" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "compliance_plans:write", "x-checkbox-min-role": "admin", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the task (task_…).", "example": "task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "task", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnswerTaskParams" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Task" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/tasks/{task}/verify": { "post": { "operationId": "verifyTask", "summary": "Verify a task after applying its change", "description": "Runs the fastest re-check that can confirm the task (static fetch of the live checkout or the html you send, the Stripe params you send, the email copy you send, a re-fetch of the Terms) and queues the confirming observation (a scan, a billing-platform sync, the next email). A failing pre-check fails the verification at once with a diff. Pass ?wait=30 to long-poll; otherwise poll retrieveVerification or wait for the task.verified webhook. Then follow next_action.", "tags": [ "Compliance plans" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "compliance_plans:write", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the task (task_…).", "example": "task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "task", "in": "path" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 30, "description": "Long-poll: wait up to this many seconds (0-30) for the verification to resolve before answering.", "example": 30 }, "required": false, "name": "wait", "in": "query" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyTaskParams" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sites/{site}/verify": { "post": { "operationId": "verifySite", "summary": "Re-check the whole site now", "description": "Re-fetches the registered policies, pre-checks the checkout, re-evaluates and queues a scan. Use it for the first check after setup, or after applying several tasks. Pass ?wait=30 to long-poll; then get the plan (retrieveCompliancePlan).", "tags": [ "Compliance plans" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "compliance_plans:write", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 30, "description": "Long-poll: wait up to this many seconds (0-30) for the verification to resolve before answering.", "example": 30 }, "required": false, "name": "wait", "in": "query" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/verifications/{verification}": { "get": { "operationId": "retrieveVerification", "summary": "Get a verification (long-poll with ?wait=30)", "description": "The verification's status (pending, passed, failed), expected vs observed per check, the diff and next_action. ?wait=N (≤ 30) holds the request until it resolves or N seconds pass.", "tags": [ "Compliance plans" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "compliance_plans:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the verification (ver_…).", "example": "ver_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "verification", "in": "path" }, { "schema": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 30, "description": "Long-poll: wait up to this many seconds (0-30) for the verification to resolve before answering.", "example": 30 }, "required": false, "name": "wait", "in": "query" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Verification" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sites/{site}/verifications": { "get": { "operationId": "listVerifications", "summary": "List verifications of a site", "description": "Verifications newest first (optionally for one task).", "tags": [ "Compliance plans" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "compliance_plans:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of objects to return, 1-100 (default 10).", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects after it (older).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects before it (newer).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "ending_before", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Only this task (task_…).", "example": "task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "task", "in": "query" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationList" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/findings/{finding}/fix": { "get": { "operationId": "retrieveFindingFix", "summary": "Get the fix for a finding", "description": "The concrete change that makes the finding pass: verified disclosure text and code for the detected platform, or the generic remediation. Apply it, then re-scan (createScan) or re-evaluate.", "tags": [ "Fixes" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "fixes:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the finding (fnd_…).", "example": "fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "finding", "in": "path" }, { "schema": { "type": "string", "maxLength": 200, "description": "Billing-platform plan/price id to write the disclosure for.", "example": "price_1Q…" }, "required": false, "name": "plan", "in": "query" }, { "schema": { "type": "string", "maxLength": 2048, "description": "Cancellation URL to state (defaults to the hosted page or billing portal).", "example": "https://acme.example/account/cancel" }, "required": false, "name": "cancel_url", "in": "query" }, { "schema": { "type": "string", "enum": [ "stripe_checkout", "stripe_payment_link", "shopify", "html" ], "description": "Where the sign-up happens (default: detected).", "example": "stripe_checkout" }, "required": false, "name": "target", "in": "query" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Fix" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sites/{site}/fixes": { "get": { "operationId": "listSiteFixes", "summary": "List fix plans for a site", "description": "Site-level fix plans: the sign-up disclosure fix and the cancellation fix (hosted cancellation page), each with the checks it covers.", "tags": [ "Fixes" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "fixes:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "string", "maxLength": 200, "description": "Billing-platform plan/price id to write the disclosure for.", "example": "price_1Q…" }, "required": false, "name": "plan", "in": "query" }, { "schema": { "type": "string", "maxLength": 2048, "description": "Cancellation URL to state (defaults to the hosted page or billing portal).", "example": "https://acme.example/account/cancel" }, "required": false, "name": "cancel_url", "in": "query" }, { "schema": { "type": "string", "enum": [ "stripe_checkout", "stripe_payment_link", "shopify", "html" ], "description": "Where the sign-up happens (default: detected).", "example": "stripe_checkout" }, "required": false, "name": "target", "in": "query" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixList" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/evidence": { "get": { "operationId": "listEvidence", "summary": "List evidence", "description": "Evidence records of a site, newest first. Use downloadEvidenceContent for the raw bytes.", "tags": [ "Evidence" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "evidence:read", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of objects to return, 1-100 (default 10).", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects after it (older).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects before it (newer).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "ending_before", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Site (site_…). Required.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "query" }, { "schema": { "type": "string", "enum": [ "screenshot", "html", "page_capture", "email_raw", "platform_config", "lifecycle_event", "evaluation" ], "description": "Only this kind.", "example": "screenshot" }, "required": false, "name": "kind", "in": "query" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceList" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/evidence/{evidence}": { "get": { "operationId": "retrieveEvidence", "summary": "Retrieve evidence metadata", "description": "One evidence record (hashes, metadata, content URL).", "tags": [ "Evidence" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "evidence:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the evidence (ev_…).", "example": "ev_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "evidence", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Evidence" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/evidence/{evidence}/content": { "get": { "operationId": "downloadEvidenceContent", "summary": "Download evidence content", "description": "The raw stored bytes (screenshot, HTML, raw email…). The X-Evidence-Sha256 header carries the hash to check.", "tags": [ "Evidence" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "evidence:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the evidence (ev_…).", "example": "ev_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "evidence", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "The file.", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "Raw content.", "example": "" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sites/{site}/evidence/verify": { "post": { "operationId": "verifyEvidenceChain", "summary": "Verify the evidence chain", "description": "Re-reads and re-hashes every evidence record of the site and checks the hash chain and signed anchors.", "tags": [ "Evidence" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "evidence:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvidenceChainVerification" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/certificates": { "get": { "operationId": "listCertificates", "summary": "List certificates", "description": "Certificates newest first, optionally for one site.", "tags": [ "Certificates" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "certificates:read", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of objects to return, 1-100 (default 10).", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects after it (older).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects before it (newer).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "ending_before", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Only objects of this site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "site", "in": "query" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateList" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/certificates/{certificate}": { "get": { "operationId": "retrieveCertificate", "summary": "Retrieve a certificate", "description": "One certificate with its verification URL and badge embed code.", "tags": [ "Certificates" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "certificates:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the certificate (cert_…).", "example": "cert_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "certificate", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Certificate" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sites/{site}/certificates": { "post": { "operationId": "createCertificate", "summary": "Issue a certificate", "description": "Issues a signed monitoring certificate once the site has been insurable for the required streak of days with a verified domain and fresh scans. Otherwise fails with resource_conflict and next_action describing what is missing.", "tags": [ "Certificates" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "certificates:write", "x-checkbox-min-role": "admin", "x-checkbox-requires-activation": true, "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Certificate" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/certificates/{certificate}/revoke": { "post": { "operationId": "revokeCertificate", "summary": "Revoke a certificate", "description": "Revokes an active certificate. The reason stays private; the verification page shows \"revoked by merchant\".", "tags": [ "Certificates" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "certificates:write", "x-checkbox-min-role": "admin", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the certificate (cert_…).", "example": "cert_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "certificate", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 3, "maxLength": 1000, "description": "Private reason.", "example": "Site rebuilt; re-certify later." } }, "required": [ "reason" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Certificate" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sites/{site}/notice_settings": { "get": { "operationId": "retrieveNoticeSettings", "summary": "Retrieve notice settings", "description": "Which notices Checkbox sends for the site and what is missing before they can go out (next_action).", "tags": [ "Notices" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "notices:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoticeSettings" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "updateNoticeSettings", "summary": "Update notice settings", "description": "Turns notices on or off and sets branding, cancel_url and the confirmed cancellation policy. Turning a notice on requires cancel_url, a confirmed policy, a connected Stripe or Recharge account and a sending address; otherwise resource_conflict explains what is missing.", "tags": [ "Notices" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "notices:write", "x-checkbox-min-role": "admin", "x-checkbox-requires-activation": true, "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNoticeSettingsParams" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoticeSettings" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/law_updates": { "get": { "operationId": "listLawUpdates", "summary": "List law updates", "description": "Law changes newest first, each with its effect on this account's sites.", "tags": [ "Law updates" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "law_updates:read", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of objects to return, 1-100 (default 10).", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects after it (older).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects before it (newer).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "ending_before", "in": "query" }, { "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Only changes on or after this date (YYYY-MM-DD).", "example": "2026-01-01" }, "required": false, "name": "since", "in": "query" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LawUpdateList" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/law_updates/{law_update}": { "get": { "operationId": "retrieveLawUpdate", "summary": "Retrieve a law update", "description": "One law change with its effect on this account's sites.", "tags": [ "Law updates" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "law_updates:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the law update (law_…).", "example": "law_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "law_update", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LawUpdate" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/checks/disclosure": { "post": { "operationId": "checkDisclosure", "summary": "Check checkout disclosure text", "description": "Checks the automatic-renewal disclosure you are about to show next to a subscribe button: what it says (renewal until canceled, price, frequency, trial, term, how to cancel), where it sits (above the button, same page) and how it looks (size, contrast, set off), and the consent checkbox (present, not pre-checked). Returns the verdict per check and per legal requirement, plus `replacement`: compliant text and drop-in HTML generated from your price/interval/trial/cancel_url and verified by the engine. Call it whenever you write or change checkout copy. Stateless and deterministic: nothing is stored, the same input on the same as_of date gives the same verdicts. Every verdict comes from the Checkbox rules engine over the legal catalog (federal ROSCA / EFTA plus the state automatic-renewal laws); the response carries rules_version, catalog_version and a disclaimer (not legal advice). Read `verdict`, then `next_action`: it tells you exactly what to change and to call the check again until verdict is pass.", "tags": [ "Checks" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "checks:read", "x-checkbox-min-role": "viewer", "parameters": [ { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisclosureCheckParams" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisclosureCheckResult" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/checks/stripe_checkout_session": { "post": { "operationId": "checkStripeCheckoutSession", "summary": "Check Stripe Checkout Session params", "description": "Pass exactly the object your code gives stripe.checkout.sessions.create (plus merchant.merchant_name and merchant.cancel_url, and merchant.price/interval when line_items use a Price id). Checkbox models the Stripe-hosted page those params render and returns findings plus `correction`: a JSON Patch (RFC 6902) and the full corrected params (custom_text.submit with the renewal terms, consent_collection.terms_of_service = \"required\", custom_text.terms_of_service_acceptance as the consent label), verified by the engine. Stripe's own small grey styling keeps \"clear and conspicuous\" at needs_review on any Stripe-hosted page; also show the terms on your page before redirecting. Stateless and deterministic: nothing is stored, the same input on the same as_of date gives the same verdicts. Every verdict comes from the Checkbox rules engine over the legal catalog (federal ROSCA / EFTA plus the state automatic-renewal laws); the response carries rules_version, catalog_version and a disclaimer (not legal advice). Read `verdict`, then `next_action`: it tells you exactly what to change and to call the check again until verdict is pass.", "tags": [ "Checks" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "checks:read", "x-checkbox-min-role": "viewer", "parameters": [ { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeCheckParams" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeCheckoutSessionCheckResult" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/checks/stripe_payment_link": { "post": { "operationId": "checkStripePaymentLink", "summary": "Check Stripe Payment Link params", "description": "Like checkStripeCheckoutSession, for stripe.paymentLinks.create params or a retrieved Payment Link object. For an existing link (params.id) the correction also gives update_params for stripe.paymentLinks.update (same URL); Stripe cannot add a consent checkbox to an existing link, so needs_new_link_for_consent says when a new link (corrected_params) is required. Stateless and deterministic: nothing is stored, the same input on the same as_of date gives the same verdicts. Every verdict comes from the Checkbox rules engine over the legal catalog (federal ROSCA / EFTA plus the state automatic-renewal laws); the response carries rules_version, catalog_version and a disclaimer (not legal advice). Read `verdict`, then `next_action`: it tells you exactly what to change and to call the check again until verdict is pass.", "tags": [ "Checks" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "checks:read", "x-checkbox-min-role": "viewer", "parameters": [ { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeCheckParams" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripePaymentLinkCheckResult" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/checks/email": { "post": { "operationId": "checkEmail", "summary": "Check a subscription lifecycle email", "description": "Checks the content of an acknowledgment (welcome) email, trial-ending reminder, renewal reminder, price-change notice, yearly terms reminder or cancellation confirmation against the requirements for that notice (renewal terms, amount, frequency, how to cancel, trial cancellation). The email is modelled as sent on time, so the verdict is about content; get send dates from checkNoticeSchedule. Returns `required_by` (requirements that make the email mandatory for this plan) and a compliant `template` with {{merge_tags}}, verified by the engine. Stateless and deterministic: nothing is stored, the same input on the same as_of date gives the same verdicts. Every verdict comes from the Checkbox rules engine over the legal catalog (federal ROSCA / EFTA plus the state automatic-renewal laws); the response carries rules_version, catalog_version and a disclaimer (not legal advice). Read `verdict`, then `next_action`: it tells you exactly what to change and to call the check again until verdict is pass.", "tags": [ "Checks" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "checks:read", "x-checkbox-min-role": "viewer", "parameters": [ { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailCheckParams" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailCheckResult" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/checks/page": { "post": { "operationId": "checkPage", "summary": "Check a checkout page (HTML or URL)", "description": "Reads a checkout page's HTML (send the rendered HTML of client-side apps) with Checkbox's static extractor — purchase buttons, terms blocks, consent checkboxes, terms links — and runs the sign-up checks on it. Without a browser, placement and conspicuousness are estimates: a passing estimate is reported as needs_review (with static_estimate), never as pass; install the snippet or run a scan after deploying for rendered measurements. `url` (instead of html) fetches a public page and needs a live-mode key on an activated account. Pass terms to compare the disclosed price with your real one and get a verified replacement. Stateless and deterministic: nothing is stored, the same input on the same as_of date gives the same verdicts. Every verdict comes from the Checkbox rules engine over the legal catalog (federal ROSCA / EFTA plus the state automatic-renewal laws); the response carries rules_version, catalog_version and a disclaimer (not legal advice). Read `verdict`, then `next_action`: it tells you exactly what to change and to call the check again until verdict is pass.", "tags": [ "Checks" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "checks:read", "x-checkbox-min-role": "viewer", "parameters": [ { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageCheckParams" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PageCheckResult" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/checks/notice_schedule": { "post": { "operationId": "checkNoticeSchedule", "summary": "Get the dates each required notice must be sent", "description": "For a subscription plan (price, interval, trial) and where you sell, returns every legally required notice — acknowledgment, trial-ending reminder, renewal reminders, yearly terms reminder, price-change notice — with the recommended send time and the compliant window (opens / closes), the jurisdictions each send satisfies and the citations. Uses the same timing as Checkbox Notices: per-state windows intersected, or the fewest sends that cover conflicting windows. Stateless. Check each email's content with checkEmail, or let Checkbox Notices send them.", "tags": [ "Checks" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "checks:read", "x-checkbox-min-role": "viewer", "parameters": [ { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoticeScheduleParams" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoticeScheduleResult" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/elements.js": { "get": { "operationId": "getElementsBundle", "summary": "Load the Elements browser bundle", "description": "The current elements.js (registers ). For production pin a version with SRI: use the script_tag from getElementsManifest or createDisclosure.", "tags": [ "Elements" ], "security": [], "x-checkbox-scope": "none", "parameters": [ { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "The file.", "content": { "application/javascript": { "schema": { "type": "string", "description": "JavaScript.", "example": "" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/elements/manifest.json": { "get": { "operationId": "getElementsManifest", "summary": "List Elements bundle versions and SRI hashes", "description": "Released elements.js versions with their immutable URLs and Subresource Integrity hashes, plus a ready-to-paste script tag for the latest one.", "tags": [ "Elements" ], "security": [], "x-checkbox-scope": "none", "parameters": [ { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ElementsManifest" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/elements/{version}/elements.js": { "get": { "operationId": "getElementsBundleVersion", "summary": "Load a pinned Elements bundle version", "description": "An immutable elements.js release (cached for a year). Its integrity hash is in getElementsManifest.", "tags": [ "Elements" ], "security": [], "x-checkbox-scope": "none", "parameters": [ { "schema": { "type": "string", "description": "Semver, e.g. 1.0.0.", "example": "1.0.0" }, "required": true, "name": "version", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "The file.", "content": { "application/javascript": { "schema": { "type": "string", "description": "JavaScript.", "example": "" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/disclosures": { "post": { "operationId": "createDisclosure", "summary": "Create a locked disclosure for a site", "description": "Generates the locked automatic-renewal disclosure and consent label for the site's terms (from the billing connection, the given terms, or both), verifies with the rules engine that the element passes the sign-up checks on your checkout, and returns the markup to paste above your pay button. Next: put script_tag in and element_html directly above the pay button, then call listConsents after a test sign-up.", "tags": [ "Elements" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "consents:write", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisclosureCreateParams" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Disclosure" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/disclosures/{disclosure}": { "get": { "operationId": "retrieveDisclosure", "summary": "Retrieve a disclosure", "description": "The locked disclosure text, consent label and terms. Works with the publishable key from the site's own pages (this is how loads its text).", "tags": [ "Elements" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "publishable", "x-checkbox-secret-key-scope": "consents:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the disclosure (disc_…).", "example": "disc_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "disclosure", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Disclosure" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/consents": { "post": { "operationId": "createConsent", "summary": "Record a consent", "description": "Records that a subscriber ticked the consent checkbox for the exact disclosure shown: stored with the text, its hashes, the terms, the page, a hash of the user agent and your customer reference, written to the site's hash-chained evidence vault, and fed to the compliance evaluation as corroborating evidence. calls this with the publishable key (Origin-checked); servers may call it with a secret key and site. Next: attach the returned cons_… id to the subscription (metadata.checkbox_consent) or call updateConsent.", "tags": [ "Elements" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "publishable", "x-checkbox-secret-key-scope": "consents:write", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentCreateParams" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Consent" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listConsents", "summary": "List consents", "description": "Consents, newest first. Filter by site, customer_reference (e.g. find the consent behind a disputed Stripe subscription), disclosure or creation time.", "tags": [ "Elements" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "consents:read", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of objects to return, 1-100 (default 10).", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects after it (older).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects before it (newer).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "ending_before", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Only this site's consents.", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "site", "in": "query" }, { "schema": { "type": "string", "maxLength": 255, "description": "Only consents with this customer reference.", "example": "cus_123" }, "required": false, "name": "customer_reference", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Only consents to this disclosure.", "example": "disc_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "disclosure", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "description": "Created at or after (unix seconds).", "example": 1793318400 }, "required": false, "name": "created_gte", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "description": "Created at or before (unix seconds).", "example": 1793404800 }, "required": false, "name": "created_lte", "in": "query" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentList" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/consents/{consent}": { "get": { "operationId": "retrieveConsent", "summary": "Retrieve a consent", "description": "A consent record: what the subscriber saw and agreed to, when, where, and its evidence record. Use it to answer a chargeback or a regulator: the evidence id verifies against the site's hash chain (verifyEvidenceChain) and downloads with downloadEvidenceContent.", "tags": [ "Elements" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "consents:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the consent (cons_…).", "example": "cons_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "consent", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Consent" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "updateConsent", "summary": "Attach a customer reference to a consent", "description": "Sets customer_reference once (e.g. the Stripe subscription id created after the consent) and merges metadata. A different reference on a consent that already has one answers 409 consent_reference_locked. The change is appended to the evidence chain.", "tags": [ "Elements" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "consents:write", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the consent (cons_…).", "example": "cons_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "consent", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConsentUpdateParams" } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Consent" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sites/{site}/test_credentials": { "post": { "operationId": "createTestCredential", "summary": "Store a billing test-mode key", "description": "Stores the site's Stripe TEST-mode key (rk_test_… preferred) used by test runs, after checking it with Stripe. Live keys are refused (test_key_not_test_mode). Least privilege: Write on Customers, Checkout Sessions, Subscriptions, Test clocks and Customer portal; Read on Prices, Products and Billing portal configuration. Replaces an existing key. Next: createTestRun.", "tags": [ "Test runs" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "test_runs:write", "x-checkbox-min-role": "admin", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "stripe_test" ], "description": "Kind of key. Only \"stripe_test\".", "example": "stripe_test" }, "secret_key": { "type": "string", "minLength": 10, "maxLength": 255, "description": "The Stripe test-mode restricted (rk_test_…) or secret (sk_test_…) key. Stored encrypted; never returned.", "example": "rk_test_51Hx…" } }, "required": [ "type", "secret_key" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestCredential" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listTestCredentials", "summary": "List billing test-mode keys of a site", "description": "The site's stored test-mode keys (hints only).", "tags": [ "Test runs" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "test_runs:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestCredentialList" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sites/{site}/test_credentials/{test_credential}": { "delete": { "operationId": "deleteTestCredential", "summary": "Delete a billing test-mode key", "description": "Deletes the stored key. Running test runs fail at their next Stripe call.", "tags": [ "Test runs" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "test_runs:write", "x-checkbox-min-role": "admin", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "string", "description": "Unique identifier of the test credential (tcred_…).", "example": "tcred_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "test_credential", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedTestCredential" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sites/{site}/stripe_checkout_configs": { "post": { "operationId": "createStripeCheckoutConfig", "summary": "Register the Checkout Session params your code uses", "description": "Registers exactly the object your code passes to stripe.checkout.sessions.create (customer, URLs and secrets are not needed and are ignored). Test runs mirror it into Stripe test mode; when it matches your latest live checkout, the scanned test page counts as an observation of your live checkout. Re-register after changing your checkout code, then call createTestRun.", "tags": [ "Test runs" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "test_runs:write", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "params": { "type": "object", "additionalProperties": {}, "description": "The Checkout Session parameters (mode \"subscription\", line_items, custom_text, consent_collection, subscription_data…).", "example": { "mode": "subscription", "line_items": [ { "price": "price_1Pro", "quantity": 1 } ], "subscription_data": { "trial_period_days": 14 } } }, "name": { "type": "string", "maxLength": 200, "description": "Your name for it.", "example": "Pro monthly" }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Up to 20 key/value string pairs you can attach to the object.", "example": { "order_ref": "A-1001" } } }, "required": [ "params" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeCheckoutConfig" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listStripeCheckoutConfigs", "summary": "List registered checkout configs", "description": "Registered Checkout Session configs of the site, newest first (test runs mirror the newest by default).", "tags": [ "Test runs" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "test_runs:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of objects to return, 1-100 (default 10).", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects after it (older).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects before it (newer).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "ending_before", "in": "query" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeCheckoutConfigList" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/stripe_checkout_configs/{stripe_checkout_config}": { "get": { "operationId": "retrieveStripeCheckoutConfig", "summary": "Retrieve a registered checkout config", "description": "One registered Checkout Session config.", "tags": [ "Test runs" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "test_runs:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the stripe checkout config (scc_…).", "example": "scc_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "stripe_checkout_config", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StripeCheckoutConfig" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteStripeCheckoutConfig", "summary": "Delete a registered checkout config", "description": "Deletes the config; later runs mirror the next newest one (or your live checkout).", "tags": [ "Test runs" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "test_runs:write", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the stripe checkout config (scc_…).", "example": "scc_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "stripe_checkout_config", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedStripeCheckoutConfig" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sites/{site}/test_runs": { "post": { "operationId": "createTestRun", "summary": "Start a lifecycle test run", "description": "Starts a synthetic test subscription in TEST mode and returns it queued. Stripe runs mirror your checkout into a test-mode Checkout Session, subscribe a test customer (card 4242) whose email is a Checkbox inbox, wait for your acknowledgment, advance a test clock through every legal notice window before trial end and renewal, cancel online in the customer portal and wait for the confirmation; then delete the test clock. Takes about 5-20 minutes: poll retrieveTestRun (next_action says when) or listen for test_run.completed. Each step reports observations, check results and agent-readable fixes; apply them and run again to verify.", "tags": [ "Test runs" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "test_runs:write", "x-checkbox-requires-activation": true, "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "stripe", "generic" ], "description": "stripe (default when a Stripe test key is stored or the site uses Stripe) or generic (test coupon / test account, no time travel).", "example": "stripe" }, "email_wait_seconds": { "type": "integer", "minimum": 15, "maximum": 900, "description": "How long to wait for each email (acknowledgment, reminders, cancellation), 15-900 seconds (default 120).", "example": 120 }, "advance_time": { "type": "boolean", "description": "Advance a Stripe test clock through the trial end and the first renewal (default true).", "example": true }, "cancel": { "type": "boolean", "description": "Cancel online at the end (default true).", "example": true }, "region": { "type": "string", "enum": [ "US-FED", "US-AL", "US-AK", "US-AZ", "US-AR", "US-CA", "US-CO", "US-CT", "US-DE", "US-DC", "US-FL", "US-GA", "US-HI", "US-ID", "US-IL", "US-IN", "US-IA", "US-KS", "US-KY", "US-LA", "US-ME", "US-MD", "US-MA", "US-MI", "US-MN", "US-MS", "US-MO", "US-MT", "US-NE", "US-NV", "US-NH", "US-NJ", "US-NM", "US-NY", "US-NC", "US-ND", "US-OH", "US-OK", "US-OR", "US-PA", "US-RI", "US-SC", "US-SD", "US-TN", "US-TX", "US-UT", "US-VT", "US-VA", "US-WA", "US-WV", "US-WI", "US-WY" ], "description": "State the synthetic shopper visits from (default: the site's first scan region).", "example": "US-CA" }, "stripe": { "type": "object", "properties": { "checkout_config": { "type": "string", "maxLength": 100, "description": "Registered checkout config (scc_…) to mirror; default: the newest one, else your latest live Checkout Session.", "example": "scc_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "price": { "type": "string", "pattern": "^price_[A-Za-z0-9_]+$", "description": "A test-mode price to subscribe to when nothing is registered.", "example": "price_1PTestPro" }, "trial_period_days": { "type": "integer", "minimum": 1, "maximum": 730, "description": "Trial for `price` (registered configs carry their own).", "example": 14 }, "price_map": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^price_[A-Za-z0-9_]+$" }, "description": "Live price id -> test-mode price id, when they differ.", "example": { "price_1LivePro": "price_1TestPro" } }, "checkout_steps": { "type": "array", "items": { "$ref": "#/components/schemas/ScanStep" }, "maxItems": 30, "description": "Steps that complete your hosted checkout with card 4242 4242 4242 4242 when it differs from Stripe's default page.", "example": [] }, "cancel_url": { "type": "string", "maxLength": 2000, "format": "uri", "description": "Cancel on your own page instead of the Stripe customer portal (it must work for the test subscriber).", "example": "https://acme.example/account/cancel" } }, "additionalProperties": false, "description": "Stripe options.", "example": { "checkout_config": "scc_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "price": "price_1PTestPro", "trial_period_days": 14, "price_map": { "price_1LivePro": "price_1TestPro" }, "checkout_steps": [], "cancel_url": "https://acme.example/account/cancel" } }, "generic": { "type": "object", "properties": { "checkout_url": { "type": "string", "maxLength": 2000, "format": "uri", "description": "Checkout page (default: the site's scan settings).", "example": "https://acme.example/join" }, "checkout_steps": { "type": "array", "items": { "$ref": "#/components/schemas/ScanStep" }, "maxItems": 30, "description": "Steps to reach the final pre-payment screen.", "example": [] }, "complete_purchase": { "type": "object", "properties": { "steps": { "type": "array", "items": { "$ref": "#/components/schemas/ScanStep" }, "minItems": 1, "maxItems": 30, "description": "Steps that complete a sign-up ({{email}} is the run inbox, {{promoCode}} the code).", "example": [ { "action": "fill", "selector": "#promo", "value": "{{promoCode}}" } ] }, "promo_code": { "type": "string", "maxLength": 200, "description": "100%-off test coupon (stored encrypted, never returned).", "example": "CHECKBOX100" } }, "required": [ "steps" ], "description": "Complete a real sign-up with a test coupon.", "example": { "steps": [ { "action": "fill", "selector": "#promo", "value": "{{promoCode}}" } ], "promo_code": "CHECKBOX100" } }, "account": { "type": "object", "properties": { "login_url": { "type": "string", "maxLength": 2000, "format": "uri", "description": "Login page of the test account.", "example": "https://acme.example/login" }, "email": { "type": "string", "maxLength": 320, "description": "Test account email; \"{{inbox}}\" = the run inbox (use it when the sign-up creates the account).", "example": "{{inbox}}" }, "password": { "type": "string", "maxLength": 500, "description": "Test account password (stored encrypted, never returned); default: the site's scan settings.", "example": "correct-horse-battery" }, "login_steps": { "type": "array", "items": { "$ref": "#/components/schemas/ScanStep" }, "maxItems": 30, "description": "Custom login steps.", "example": [] } }, "required": [ "login_url", "email" ], "description": "Test account used to cancel online.", "example": { "login_url": "https://acme.example/login", "email": "{{inbox}}", "password": "correct-horse-battery", "login_steps": [] } }, "cancel_steps": { "type": "array", "items": { "$ref": "#/components/schemas/ScanStep" }, "maxItems": 30, "description": "Explicit cancellation steps (otherwise auto-discovered).", "example": [] } }, "additionalProperties": false, "description": "Generic (non-Stripe) options.", "example": { "checkout_url": "https://acme.example/join", "checkout_steps": [], "complete_purchase": { "steps": [ { "action": "fill", "selector": "#promo", "value": "{{promoCode}}" } ], "promo_code": "CHECKBOX100" }, "account": { "login_url": "https://acme.example/login", "email": "{{inbox}}", "password": "correct-horse-battery", "login_steps": [] }, "cancel_steps": [] } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestRun" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listTestRuns", "summary": "List test runs of a site", "description": "Test runs of the site, newest first.", "tags": [ "Test runs" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "test_runs:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the site (site_…).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "site", "in": "path" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of objects to return, 1-100 (default 10).", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects after it (older).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects before it (newer).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "ending_before", "in": "query" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestRunList" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/test_runs/{test_run}": { "get": { "operationId": "retrieveTestRun", "summary": "Retrieve a test run", "description": "The run with every step's status, observations, check results and fixes. While it runs, next_action.type is \"wait\"; when it finished, next_action says what to fix (apply_fixes / review_warnings) or \"none\".", "tags": [ "Test runs" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "test_runs:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the test run (run_…).", "example": "run_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "test_run", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestRun" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/test_runs/{test_run}/cancel": { "post": { "operationId": "cancelTestRun", "summary": "Cancel a test run", "description": "Stops a queued or running test run; the worker deletes its Stripe test clock (and with it the test customer and subscription). Finished runs cannot be canceled (resource_conflict).", "tags": [ "Test runs" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "test_runs:write", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the test run (run_…).", "example": "run_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "test_run", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestRun" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook_endpoints": { "post": { "operationId": "createWebhookEndpoint", "summary": "Create a webhook endpoint", "description": "Registers an HTTPS endpoint for the given event types. The response contains the signing `secret` (only now). Respond 2xx quickly; do slow work asynchronously.", "tags": [ "Webhook endpoints" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "webhook_endpoints:write", "x-checkbox-min-role": "admin", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2000, "description": "HTTPS URL.", "example": "https://acme.example/webhooks/checkbox" }, "enabled_events": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Event types to send, or [\"*\"] for all: site.score_changed, site.insurable_changed, finding.created, finding.resolved, scan.completed, scan.failed, law.changed, certificate.issued, certificate.lapsed, certificate.revoked, notice.sent, consent.created, test_run.completed, test_run.failed, plan.updated, site.compliant, task.verified.", "example": [ "finding.created", "site.insurable_changed" ] }, "description": { "type": "string", "maxLength": 500, "description": "Description.", "example": "Production listener" }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Up to 20 key/value string pairs you can attach to the object.", "example": { "order_ref": "A-1001" } } }, "required": [ "url", "enabled_events" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "listWebhookEndpoints", "summary": "List webhook endpoints", "description": "Webhook endpoints of this mode, newest first.", "tags": [ "Webhook endpoints" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "webhook_endpoints:read", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of objects to return, 1-100 (default 10).", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects after it (older).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects before it (newer).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "ending_before", "in": "query" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointList" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook_endpoints/{webhook_endpoint}": { "get": { "operationId": "retrieveWebhookEndpoint", "summary": "Retrieve a webhook endpoint", "description": "One webhook endpoint (without its secret).", "tags": [ "Webhook endpoints" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "webhook_endpoints:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the webhook endpoint (we_…).", "example": "we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "webhook_endpoint", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "updateWebhookEndpoint", "summary": "Update a webhook endpoint", "description": "Changes the URL, event types, description, metadata, or disables / re-enables the endpoint.", "tags": [ "Webhook endpoints" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "webhook_endpoints:write", "x-checkbox-min-role": "admin", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the webhook endpoint (we_…).", "example": "we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "webhook_endpoint", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2000, "description": "HTTPS URL.", "example": "https://acme.example/webhooks/checkbox" }, "enabled_events": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 50, "description": "Event types to send, or [\"*\"] for all: site.score_changed, site.insurable_changed, finding.created, finding.resolved, scan.completed, scan.failed, law.changed, certificate.issued, certificate.lapsed, certificate.revoked, notice.sent, consent.created, test_run.completed, test_run.failed, plan.updated, site.compliant, task.verified.", "example": [ "finding.created", "site.insurable_changed" ] }, "description": { "type": [ "string", "null" ], "maxLength": 500, "description": "Description (null clears it).", "example": null }, "disabled": { "type": "boolean", "description": "true disables the endpoint, false enables it.", "example": false }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 }, "description": "Up to 20 key/value string pairs you can attach to the object.", "example": { "order_ref": "A-1001" } } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteWebhookEndpoint", "summary": "Delete a webhook endpoint", "description": "Deletes the endpoint; pending deliveries to it are dropped.", "tags": [ "Webhook endpoints" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "webhook_endpoints:write", "x-checkbox-min-role": "admin", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the webhook endpoint (we_…).", "example": "we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "webhook_endpoint", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedWebhookEndpoint" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook_endpoints/{webhook_endpoint}/roll_secret": { "post": { "operationId": "rollWebhookEndpointSecret", "summary": "Roll a webhook signing secret", "description": "Replaces the signing secret immediately and returns the new one (only now).", "tags": [ "Webhook endpoints" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "webhook_endpoints:write", "x-checkbox-min-role": "admin", "x-checkbox-idempotent": true, "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the webhook endpoint (we_…).", "example": "we_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "webhook_endpoint", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" }, { "schema": { "type": "string", "maxLength": 255, "description": "Makes the POST safe to retry: the same key and body within 24 hours return the stored response.", "example": "7f8c3b0e-setup-site-1" }, "required": false, "name": "Idempotency-Key", "in": "header" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/events": { "get": { "operationId": "listEvents", "summary": "List events", "description": "Events newest first. Poll with ending_before= to get only new events (an alternative to webhooks).", "tags": [ "Events" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "events:read", "parameters": [ { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of objects to return, 1-100 (default 10).", "example": 10 }, "required": false, "name": "limit", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects after it (older).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "starting_after", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Cursor: an object id; returns the objects before it (newer).", "example": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": false, "name": "ending_before", "in": "query" }, { "schema": { "type": "string", "maxLength": 100, "description": "Only this type; a trailing * matches a prefix (finding.*).", "example": "finding.*" }, "required": false, "name": "type", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "description": "Only events created at or after this unix time.", "example": 1793318400 }, "required": false, "name": "created_gte", "in": "query" }, { "schema": { "type": [ "integer", "null" ], "description": "Only events created at or before this unix time.", "example": 1793404800 }, "required": false, "name": "created_lte", "in": "query" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/events/{event}": { "get": { "operationId": "retrieveEvent", "summary": "Retrieve an event", "description": "One event with its payload (data.object) and the number of webhook deliveries still pending.", "tags": [ "Events" ], "security": [ { "bearerAuth": [] }, { "basicAuth": [] } ], "x-checkbox-scope": "events:read", "parameters": [ { "schema": { "type": "string", "description": "Unique identifier of the event (evt_…).", "example": "evt_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "required": true, "name": "event", "in": "path" }, { "schema": { "type": "string", "description": "API version (date). Defaults to the version your account is pinned to. Known: 2026-10-30.", "example": "2026-10-30" }, "required": false, "name": "Checkbox-Version", "in": "header" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "4XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "5XX": { "description": "Error. See error.code (stable) and error.next_action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "plan.updated": { "post": { "operationId": "webhook_plan_updated", "summary": "plan.updated", "description": "A site's compliance plan changed (its status or a task's status); data.object is the plan without task content — GET the plan and follow next_action.", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "plan.updated" ], "description": "Event type.", "example": "plan.updated" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/CompliancePlanSummary" }, "previous_attributes": { "type": "object", "additionalProperties": {}, "description": "plan.updated: the previous status and score.", "example": { "status": "action_required" } } }, "required": [ "object" ], "example": { "object": { "id": "plan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "compliance_plan", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "status": "action_required", "score": 62, "insurable": false, "summary": "StreamMax fails 4 critical checks…", "counts": { "open": 3, "in_progress": 0, "verifying": 1, "manual": 1, "done": 2, "wont_fix": 0 }, "next_action": { "type": "apply_task", "description": "Apply task_… (add the renewal terms above the Subscribe button in app/checkout/page.tsx), then call verifyTask.", "task": "task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "operation_id": "verifyTask", "mcp_tool": "verify_task", "endpoint": "POST /v1/tasks/task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/verify", "command": "checkbox fix task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "coverage": { "observed": [ "signup", "policies" ], "not_observed": [ "cancellation", "billing_settings" ], "attested": [], "billing_connected": false }, "generated": 1793318400, "tasks": [ { "id": "task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "key": "signup_disclosure", "status": "open", "priority": "critical", "title": "Show the renewal terms above the purchase button" } ] }, "previous_attributes": { "status": "action_required" } } } } } ], "description": "Something that happened in the account. Delivered to webhook endpoints and listed by listEvents (kept 30 days)." } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge the event." } } } }, "task.verified": { "post": { "operationId": "webhook_task_verified", "summary": "task.verified", "description": "A compliance-plan task verification resolved (passed or failed); data.object is the verification with expected vs observed per check.", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "task.verified" ], "description": "Event type.", "example": "task.verified" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Verification" }, "previous_attributes": { "type": "object", "additionalProperties": {}, "description": "plan.updated: the previous status and score.", "example": { "status": "action_required" } } }, "required": [ "object" ], "example": { "object": { "id": "ver_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "verification", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "task": "task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "scope": "task", "status": "pending", "method": "page_fetch", "precheck": { "source": "static_fetch", "verdict": "pass", "url": "https://shop.example/checkout", "note": "Static fetch: text checks are exact; layout is estimated until the confirming scan." }, "scan": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "checks": [ { "check_id": "signup.disclosure.price", "expected": "pass", "observed": "fail", "source": "static_fetch", "detail": "No recurring price near the purchase button." } ], "diff": [ { "check_id": "signup.disclosure.price", "expected": "pass", "observed": "fail", "source": "static_fetch", "detail": "No recurring price near the purchase button." } ], "plan_status": "action_required", "next_action": { "type": "apply_task", "description": "Apply task_… (add the renewal terms above the Subscribe button in app/checkout/page.tsx), then call verifyTask.", "task": "task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "operation_id": "verifyTask", "mcp_tool": "verify_task", "endpoint": "POST /v1/tasks/task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/verify", "command": "checkbox fix task_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "created": 1793318400, "completed": 1793318400, "expires": 1793318400 }, "previous_attributes": { "status": "action_required" } } } } } ], "description": "Something that happened in the account. Delivered to webhook endpoints and listed by listEvents (kept 30 days)." } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge the event." } } } }, "test_run.completed": { "post": { "operationId": "webhook_test_run_completed", "summary": "test_run.completed", "description": "A lifecycle test run finished; data.object is the test_run with every step's observations, check results and fixes.", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "test_run.completed" ], "description": "Event type.", "example": "test_run.completed" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/TestRun" }, "previous_attributes": { "type": "object", "additionalProperties": {}, "description": "Not used for test_run events.", "example": {} } }, "required": [ "object" ], "example": { "object": { "id": "run_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "test_run", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "type": "stripe", "status": "running", "phase": "await_ack", "test_mode": true, "inbox_address": "k3y9+run-3f9a1c2e7b4d@in.checkbox.site", "created": 1793318400, "started": 1793318400, "finished": 1793318400, "steps": [], "failure": { "code": "price_not_in_test_mode", "message": "Price price_1Live does not exist in Stripe test mode.", "detail": { "prices": [] }, "fix": { "summary": "Send the acknowledgment from your checkout.session.completed webhook.", "steps": [ "Handle checkout.session.completed…" ], "where": "https://dashboard.stripe.com/test/apikeys", "operation_id": "createTestRun", "stripe_params": { "features": { "subscription_cancel": { "enabled": true } } }, "command": "stripe prices create --unit-amount=1900 --currency=usd -d \"recurring[interval]=month\"", "docs_url": "https://checkbox.site/docs/test-runs#acknowledgment" } }, "result": { "score": 82, "summary": { "passed": 9, "failed": 2, "needs_review": 1, "warnings": 1 }, "checks": [], "monitoring": { "checkout_page_counted": true, "cancellation_flow_counted": true, "emails_counted": 3, "reminder_events": 1, "notes": [] } }, "stripe": { "test_clock": "clock_1Q…", "customer": "cus_Q…", "subscription": "sub_1Q…", "checkout_session": "cs_test_a1…", "mirrored_from": "registered", "checkout_config": null, "config_hash": "4be1…", "matches_live": true, "cleaned_up": true }, "next_action": { "type": "verify_domain", "message": "Verify your site domain to turn on live mode.", "operation_id": "createDomainVerification", "mcp_tool": "call_api", "url": "https://checkbox.site/docs/api/activation" } }, "previous_attributes": {} } } } } ], "description": "Something that happened in the account. Delivered to webhook endpoints and listed by listEvents (kept 30 days)." } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge the event." } } } }, "test_run.failed": { "post": { "operationId": "webhook_test_run_failed", "summary": "test_run.failed", "description": "A lifecycle test run stopped early; data.object.failure has the code, message and fix.", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "test_run.failed" ], "description": "Event type.", "example": "test_run.failed" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/TestRun" }, "previous_attributes": { "type": "object", "additionalProperties": {}, "description": "Not used for test_run events.", "example": {} } }, "required": [ "object" ], "example": { "object": { "id": "run_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "test_run", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "type": "stripe", "status": "running", "phase": "await_ack", "test_mode": true, "inbox_address": "k3y9+run-3f9a1c2e7b4d@in.checkbox.site", "created": 1793318400, "started": 1793318400, "finished": 1793318400, "steps": [], "failure": { "code": "price_not_in_test_mode", "message": "Price price_1Live does not exist in Stripe test mode.", "detail": { "prices": [] }, "fix": { "summary": "Send the acknowledgment from your checkout.session.completed webhook.", "steps": [ "Handle checkout.session.completed…" ], "where": "https://dashboard.stripe.com/test/apikeys", "operation_id": "createTestRun", "stripe_params": { "features": { "subscription_cancel": { "enabled": true } } }, "command": "stripe prices create --unit-amount=1900 --currency=usd -d \"recurring[interval]=month\"", "docs_url": "https://checkbox.site/docs/test-runs#acknowledgment" } }, "result": { "score": 82, "summary": { "passed": 9, "failed": 2, "needs_review": 1, "warnings": 1 }, "checks": [], "monitoring": { "checkout_page_counted": true, "cancellation_flow_counted": true, "emails_counted": 3, "reminder_events": 1, "notes": [] } }, "stripe": { "test_clock": "clock_1Q…", "customer": "cus_Q…", "subscription": "sub_1Q…", "checkout_session": "cs_test_a1…", "mirrored_from": "registered", "checkout_config": null, "config_hash": "4be1…", "matches_live": true, "cleaned_up": true }, "next_action": { "type": "verify_domain", "message": "Verify your site domain to turn on live mode.", "operation_id": "createDomainVerification", "mcp_tool": "call_api", "url": "https://checkbox.site/docs/api/activation" } }, "previous_attributes": {} } } } } ], "description": "Something that happened in the account. Delivered to webhook endpoints and listed by listEvents (kept 30 days)." } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge the event." } } } }, "site.score_changed": { "post": { "operationId": "webhook_site_score_changed", "summary": "site.score_changed", "description": "A site's compliance score changed (data.previous_attributes.score has the old score).", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "site.score_changed" ], "description": "Event type.", "example": "site.score_changed" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Site" }, "previous_attributes": { "type": "object", "additionalProperties": {}, "description": "Previous values of changed fields.", "example": {} } }, "required": [ "object" ], "example": { "object": { "id": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "site", "livemode": false, "name": "Acme Coffee Club", "url": "https://acme.example", "platform": "stripe", "jurisdictions": [], "facts": { "has_free_trial": true, "trial_days": 14, "term_months": 1, "online_signup": true, "sells_goods": false, "notice_channel_email": true, "price_increase_consent_or_refund": false, "payment_methods": [ "card" ] }, "checkout": { "url": "https://acme.example/pricing", "regions": [ "US-CA", "US-NY" ], "devices": [ "desktop", "mobile" ], "checkout_steps": 0, "completes_purchase": false, "has_test_account": false, "test_account": { "login_url": "https://acme.example/login", "email": "test-subscriber@acme.example" }, "cancel_steps": 0 }, "monitoring": { "enabled": true, "interval_minutes": 1440, "held_for_activation": false, "last_scanned": 1793318400 }, "compliance": { "score": 82, "insurable": false, "evaluated": 1793318400, "open_findings": 2, "needs_review": 1 }, "install": { "script_tag": "", "snippet_key": "ab12cd34ef56", "inbound_email": "ab12cd34ef56@in.checkbox.site", "webhook_urls": { "stripe": "https://app.checkbox.site/webhooks/stripe/…" } }, "archived": false, "created": 1793318400, "latest_scan": { "id": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "scan", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "status": "completed", "trigger": "api", "regions": [ "US-CA", "US-NY" ], "error": null, "warnings": [], "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "score": 82, "insurable": false, "started": 1793318400, "finished": 1793318400, "created": 1793318400 }, "domain_verification": { "id": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "domain_verification", "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "domain": "acme.example", "status": "pending", "method": null, "verified_at": 1793318400, "last_checked": 1793318400, "last_error": "TXT record not found", "dns_record": { "type": "TXT", "name": "_checkbox-verify.acme.example", "value": "checkbox-verify=Xy…" }, "file": { "url": "https://acme.example/.well-known/checkbox-verify.txt", "contents": "Xy…" }, "scan_target_problems": [], "account_activated": false, "next_action": { "type": "publish_dns_record", "message": "Publish the TXT record, then call checkDomainVerification.", "operation_id": "checkDomainVerification", "mcp_tool": "call_api" } } }, "previous_attributes": {} } } } } ], "description": "Something that happened in the account. Delivered to webhook endpoints and listed by listEvents (kept 30 days)." } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge the event." } } } }, "site.insurable_changed": { "post": { "operationId": "webhook_site_insurable_changed", "summary": "site.insurable_changed", "description": "A site became insurable or stopped being insurable.", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "site.insurable_changed" ], "description": "Event type.", "example": "site.insurable_changed" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Site" }, "previous_attributes": { "type": "object", "additionalProperties": {}, "description": "Previous values of changed fields.", "example": {} } }, "required": [ "object" ], "example": { "object": { "id": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "site", "livemode": false, "name": "Acme Coffee Club", "url": "https://acme.example", "platform": "stripe", "jurisdictions": [], "facts": { "has_free_trial": true, "trial_days": 14, "term_months": 1, "online_signup": true, "sells_goods": false, "notice_channel_email": true, "price_increase_consent_or_refund": false, "payment_methods": [ "card" ] }, "checkout": { "url": "https://acme.example/pricing", "regions": [ "US-CA", "US-NY" ], "devices": [ "desktop", "mobile" ], "checkout_steps": 0, "completes_purchase": false, "has_test_account": false, "test_account": { "login_url": "https://acme.example/login", "email": "test-subscriber@acme.example" }, "cancel_steps": 0 }, "monitoring": { "enabled": true, "interval_minutes": 1440, "held_for_activation": false, "last_scanned": 1793318400 }, "compliance": { "score": 82, "insurable": false, "evaluated": 1793318400, "open_findings": 2, "needs_review": 1 }, "install": { "script_tag": "", "snippet_key": "ab12cd34ef56", "inbound_email": "ab12cd34ef56@in.checkbox.site", "webhook_urls": { "stripe": "https://app.checkbox.site/webhooks/stripe/…" } }, "archived": false, "created": 1793318400, "latest_scan": { "id": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "scan", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "status": "completed", "trigger": "api", "regions": [ "US-CA", "US-NY" ], "error": null, "warnings": [], "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "score": 82, "insurable": false, "started": 1793318400, "finished": 1793318400, "created": 1793318400 }, "domain_verification": { "id": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "domain_verification", "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "domain": "acme.example", "status": "pending", "method": null, "verified_at": 1793318400, "last_checked": 1793318400, "last_error": "TXT record not found", "dns_record": { "type": "TXT", "name": "_checkbox-verify.acme.example", "value": "checkbox-verify=Xy…" }, "file": { "url": "https://acme.example/.well-known/checkbox-verify.txt", "contents": "Xy…" }, "scan_target_problems": [], "account_activated": false, "next_action": { "type": "publish_dns_record", "message": "Publish the TXT record, then call checkDomainVerification.", "operation_id": "checkDomainVerification", "mcp_tool": "call_api" } } }, "previous_attributes": {} } } } } ], "description": "Something that happened in the account. Delivered to webhook endpoints and listed by listEvents (kept 30 days)." } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge the event." } } } }, "finding.created": { "post": { "operationId": "webhook_finding_created", "summary": "finding.created", "description": "A check started failing (new finding, or a resolved / passing one failing again).", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "finding.created" ], "description": "Event type.", "example": "finding.created" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Finding" }, "previous_attributes": { "type": "object", "additionalProperties": {}, "description": "Previous values of changed fields.", "example": {} } }, "required": [ "object" ], "example": { "object": { "id": "fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "finding", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "check_id": "signup.disclosure_clear_conspicuous", "title": "Auto-renewal terms are not shown before purchase", "detail": "The checkout page in US-CA (mobile) shows no renewal terms near the subscribe button.", "stage": "signup", "severity": "high", "status": "fail", "state": "open", "note": null, "jurisdictions": [ "US-CA", "US-NY" ], "requirements": [ { "id": "US-CA.17602.a.1", "jurisdiction": "US-CA", "citation": "Cal. Bus. & Prof. Code § 17602(a)(1)", "title": "Clear and conspicuous auto-renewal terms before purchase", "source_url": "https://leginfo.legislature.ca.gov/…" } ], "remediation": { "summary": "Show the auto-renewal terms next to the subscribe button.", "steps": [ "Add the disclosure above the button" ], "platform": "stripe", "suggested_copy": "Your subscription renews automatically every month at $9.99 until you cancel.", "snippet": { "language": "html", "code": "

…

" } }, "confidence": 0.9, "evidence_refs": [], "details": { "failingRegions": [ "US-CA" ] }, "scan": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "first_seen": 1793318400, "last_seen": 1793318400, "resolved_at": 1793318400 }, "previous_attributes": {} } } } } ], "description": "Something that happened in the account. Delivered to webhook endpoints and listed by listEvents (kept 30 days)." } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge the event." } } } }, "finding.resolved": { "post": { "operationId": "webhook_finding_resolved", "summary": "finding.resolved", "description": "A failing or undecided check now passes or no longer applies.", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "finding.resolved" ], "description": "Event type.", "example": "finding.resolved" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Finding" }, "previous_attributes": { "type": "object", "additionalProperties": {}, "description": "Previous values of changed fields.", "example": {} } }, "required": [ "object" ], "example": { "object": { "id": "fnd_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "finding", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "check_id": "signup.disclosure_clear_conspicuous", "title": "Auto-renewal terms are not shown before purchase", "detail": "The checkout page in US-CA (mobile) shows no renewal terms near the subscribe button.", "stage": "signup", "severity": "high", "status": "fail", "state": "open", "note": null, "jurisdictions": [ "US-CA", "US-NY" ], "requirements": [ { "id": "US-CA.17602.a.1", "jurisdiction": "US-CA", "citation": "Cal. Bus. & Prof. Code § 17602(a)(1)", "title": "Clear and conspicuous auto-renewal terms before purchase", "source_url": "https://leginfo.legislature.ca.gov/…" } ], "remediation": { "summary": "Show the auto-renewal terms next to the subscribe button.", "steps": [ "Add the disclosure above the button" ], "platform": "stripe", "suggested_copy": "Your subscription renews automatically every month at $9.99 until you cancel.", "snippet": { "language": "html", "code": "

…

" } }, "confidence": 0.9, "evidence_refs": [], "details": { "failingRegions": [ "US-CA" ] }, "scan": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "first_seen": 1793318400, "last_seen": 1793318400, "resolved_at": 1793318400 }, "previous_attributes": {} } } } } ], "description": "Something that happened in the account. Delivered to webhook endpoints and listed by listEvents (kept 30 days)." } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge the event." } } } }, "scan.completed": { "post": { "operationId": "webhook_scan_completed", "summary": "scan.completed", "description": "A scan finished (the evaluation may follow in a separate site.score_changed event).", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "scan.completed" ], "description": "Event type.", "example": "scan.completed" }, "data": { "type": "object", "properties": { "object": { "allOf": [ { "$ref": "#/components/schemas/Scan" }, { "description": "One synthetic-shopper run (checkout per state and device, optional sign-up and cancellation attempt) or evaluation-only run." } ], "example": { "id": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "scan", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "status": "completed", "trigger": "api", "regions": [ "US-CA", "US-NY" ], "error": null, "warnings": [], "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "score": 82, "insurable": false, "started": 1793318400, "finished": 1793318400, "created": 1793318400 } }, "previous_attributes": { "type": "object", "additionalProperties": {}, "description": "Previous values of changed fields.", "example": {} } }, "required": [ "object" ], "example": { "object": { "id": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "scan", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "status": "completed", "trigger": "api", "regions": [ "US-CA", "US-NY" ], "error": null, "warnings": [], "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "score": 82, "insurable": false, "started": 1793318400, "finished": 1793318400, "created": 1793318400 }, "previous_attributes": {} } } } } ], "description": "Something that happened in the account. Delivered to webhook endpoints and listed by listEvents (kept 30 days)." } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge the event." } } } }, "scan.failed": { "post": { "operationId": "webhook_scan_failed", "summary": "scan.failed", "description": "A scan failed; data.object.error says why.", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "scan.failed" ], "description": "Event type.", "example": "scan.failed" }, "data": { "type": "object", "properties": { "object": { "allOf": [ { "$ref": "#/components/schemas/Scan" }, { "description": "One synthetic-shopper run (checkout per state and device, optional sign-up and cancellation attempt) or evaluation-only run." } ], "example": { "id": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "scan", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "status": "completed", "trigger": "api", "regions": [ "US-CA", "US-NY" ], "error": null, "warnings": [], "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "score": 82, "insurable": false, "started": 1793318400, "finished": 1793318400, "created": 1793318400 } }, "previous_attributes": { "type": "object", "additionalProperties": {}, "description": "Previous values of changed fields.", "example": {} } }, "required": [ "object" ], "example": { "object": { "id": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "scan", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "status": "completed", "trigger": "api", "regions": [ "US-CA", "US-NY" ], "error": null, "warnings": [], "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "score": 82, "insurable": false, "started": 1793318400, "finished": 1793318400, "created": 1793318400 }, "previous_attributes": {} } } } } ], "description": "Something that happened in the account. Delivered to webhook endpoints and listed by listEvents (kept 30 days)." } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge the event." } } } }, "law.changed": { "post": { "operationId": "webhook_law_changed", "summary": "law.changed", "description": "A law change Checkbox applies affected one of your sites (data.object is the law update with that site's impact).", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "law.changed" ], "description": "Event type.", "example": "law.changed" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/LawUpdate" }, "previous_attributes": { "type": "object", "additionalProperties": {}, "description": "Previous values of changed fields.", "example": {} } }, "required": [ "object" ], "example": { "object": { "id": "law_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "law_update", "livemode": false, "source": "effective", "date": "2026-11-01", "summary": "New York online-cancellation rule takes effect.", "jurisdictions": [ "US-NY" ], "changes": [ { "requirement_id": "US-NY.527-a.1", "change": "effective", "jurisdiction": "US-NY", "citation": "N.Y. Gen. Bus. Law § 527-a", "title": "Online cancellation", "summary": null, "effective_date": "2026-11-01", "sunset_date": null, "source_url": "https://www.nysenate.gov/legislation/laws/GBS/527-A" } ], "impacts": [ { "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "summary": "1 check now fails under the new rule.", "score_before": 90, "score_after": 84, "affected_checks": [ { "check_id": "cancellation.online_cancel_available", "title": "Customers can cancel online", "severity": "critical", "before": "pass", "after": "fail" } ], "evaluated": 1793318400 } ], "created": 1793318400 }, "previous_attributes": {} } } } } ], "description": "Something that happened in the account. Delivered to webhook endpoints and listed by listEvents (kept 30 days)." } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge the event." } } } }, "certificate.issued": { "post": { "operationId": "webhook_certificate_issued", "summary": "certificate.issued", "description": "A monitoring certificate was issued.", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "certificate.issued" ], "description": "Event type.", "example": "certificate.issued" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Certificate" }, "previous_attributes": { "type": "object", "additionalProperties": {}, "description": "Previous values of changed fields.", "example": {} } }, "required": [ "object" ], "example": { "object": { "id": "cert_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "certificate", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "status": "active", "domain": "acme.example", "issued": 1793318400, "valid_until": 1793318400, "renewed": 1793318400, "ended": 1793318400, "public_reason": null, "verify_url": "https://app.checkbox.site/verify/SC-7Q2K-9M4X", "badge": { "svg_url": "https://app.checkbox.site/badge/SC-7Q2K-9M4X.svg", "script_url": "https://app.checkbox.site/badge/SC-7Q2K-9M4X.js", "embed_html": "\"…\"" } }, "previous_attributes": {} } } } } ], "description": "Something that happened in the account. Delivered to webhook endpoints and listed by listEvents (kept 30 days)." } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge the event." } } } }, "certificate.lapsed": { "post": { "operationId": "webhook_certificate_lapsed", "summary": "certificate.lapsed", "description": "A certificate lapsed (the site stopped meeting the requirements).", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "certificate.lapsed" ], "description": "Event type.", "example": "certificate.lapsed" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Certificate" }, "previous_attributes": { "type": "object", "additionalProperties": {}, "description": "Previous values of changed fields.", "example": {} } }, "required": [ "object" ], "example": { "object": { "id": "cert_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "certificate", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "status": "active", "domain": "acme.example", "issued": 1793318400, "valid_until": 1793318400, "renewed": 1793318400, "ended": 1793318400, "public_reason": null, "verify_url": "https://app.checkbox.site/verify/SC-7Q2K-9M4X", "badge": { "svg_url": "https://app.checkbox.site/badge/SC-7Q2K-9M4X.svg", "script_url": "https://app.checkbox.site/badge/SC-7Q2K-9M4X.js", "embed_html": "\"…\"" } }, "previous_attributes": {} } } } } ], "description": "Something that happened in the account. Delivered to webhook endpoints and listed by listEvents (kept 30 days)." } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge the event." } } } }, "certificate.revoked": { "post": { "operationId": "webhook_certificate_revoked", "summary": "certificate.revoked", "description": "A certificate was revoked.", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "certificate.revoked" ], "description": "Event type.", "example": "certificate.revoked" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Certificate" }, "previous_attributes": { "type": "object", "additionalProperties": {}, "description": "Previous values of changed fields.", "example": {} } }, "required": [ "object" ], "example": { "object": { "id": "cert_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "certificate", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "status": "active", "domain": "acme.example", "issued": 1793318400, "valid_until": 1793318400, "renewed": 1793318400, "ended": 1793318400, "public_reason": null, "verify_url": "https://app.checkbox.site/verify/SC-7Q2K-9M4X", "badge": { "svg_url": "https://app.checkbox.site/badge/SC-7Q2K-9M4X.svg", "script_url": "https://app.checkbox.site/badge/SC-7Q2K-9M4X.js", "embed_html": "\"…\"" } }, "previous_attributes": {} } } } } ], "description": "Something that happened in the account. Delivered to webhook endpoints and listed by listEvents (kept 30 days)." } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge the event." } } } }, "notice.sent": { "post": { "operationId": "webhook_notice_sent", "summary": "notice.sent", "description": "Checkbox sent a legally required notice (acknowledgment, reminder, price change) for the merchant.", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "notice.sent" ], "description": "Event type.", "example": "notice.sent" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Notice" }, "previous_attributes": { "type": "object", "additionalProperties": {}, "description": "Previous values of changed fields.", "example": {} } }, "required": [ "object" ], "example": { "object": { "id": "ntc_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "notice", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "kind": "renewal_reminder", "status": "sent", "platform": "stripe", "subscription": "sub_1Q…", "recipient": "j***@example.com", "subject": "Your Acme Coffee Club subscription renews on 1 December", "sent": 1793318400, "late": false, "evidence": "ev_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b" }, "previous_attributes": {} } } } } ], "description": "Something that happened in the account. Delivered to webhook endpoints and listed by listEvents (kept 30 days)." } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge the event." } } } }, "consent.created": { "post": { "operationId": "webhook_consent_created", "summary": "consent.created", "description": "A subscriber gave affirmative consent to the automatic-renewal terms through Checkbox Elements (or your server recorded one); data.object is the consent.", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "consent.created" ], "description": "Event type.", "example": "consent.created" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Consent" }, "previous_attributes": { "type": "object", "additionalProperties": {}, "description": "Previous values of changed fields.", "example": {} } }, "required": [ "object" ], "example": { "object": { "id": "cons_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "consent", "livemode": false, "created": 1793318400, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "disclosure": { "id": null, "text": "Your Joybox subscription automatically renews every month …", "consent_label": "I agree that my Joybox subscription renews automatically …", "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "texts_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "matches_locked_text": true }, "terms": { "merchant_name": "Joybox", "amount": 1999, "currency": "usd", "interval": "month" }, "checkbox": { "checked": true, "initially_checked": false, "required": true }, "page_url": "https://joybox.example/checkout", "origin": "https://joybox.example", "user_agent_sha256": null, "customer_reference": "cs_test_a1b2c3", "client_reference": null, "source": "elements", "element_version": "1.0.0", "client_timestamp": null, "presentation": { "violations": [], "fallback_applied": false, "font_size_px": 16, "contrast_ratio": 16.1, "above_submit": true, "gap_px": 12, "boxed": true, "visible": true }, "metadata": {}, "evidence": { "id": "ev_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "sha256": null, "chain_hash": null }, "corroborating_capture": null, "next_action": { "type": "verify_domain", "message": "Verify your site domain to turn on live mode.", "operation_id": "createDomainVerification", "mcp_tool": "call_api", "url": "https://checkbox.site/docs/api/activation" } }, "previous_attributes": {} } } } } ], "description": "Something that happened in the account. Delivered to webhook endpoints and listed by listEvents (kept 30 days)." } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge the event." } } } }, "site.compliant": { "post": { "operationId": "webhook_site_compliant", "summary": "site.compliant", "description": "A site's compliance plan became compliant: nothing is left to apply, verify or answer; data.object is the site.", "tags": [ "Webhooks" ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "site.compliant" ], "description": "Event type.", "example": "site.compliant" }, "data": { "type": "object", "properties": { "object": { "$ref": "#/components/schemas/Site" }, "previous_attributes": { "type": "object", "additionalProperties": {}, "description": "Previous values of changed fields.", "example": {} } }, "required": [ "object" ], "example": { "object": { "id": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "site", "livemode": false, "name": "Acme Coffee Club", "url": "https://acme.example", "platform": "stripe", "jurisdictions": [], "facts": { "has_free_trial": true, "trial_days": 14, "term_months": 1, "online_signup": true, "sells_goods": false, "notice_channel_email": true, "price_increase_consent_or_refund": false, "payment_methods": [ "card" ] }, "checkout": { "url": "https://acme.example/pricing", "regions": [ "US-CA", "US-NY" ], "devices": [ "desktop", "mobile" ], "checkout_steps": 0, "completes_purchase": false, "has_test_account": false, "test_account": { "login_url": "https://acme.example/login", "email": "test-subscriber@acme.example" }, "cancel_steps": 0 }, "monitoring": { "enabled": true, "interval_minutes": 1440, "held_for_activation": false, "last_scanned": 1793318400 }, "compliance": { "score": 82, "insurable": false, "evaluated": 1793318400, "open_findings": 2, "needs_review": 1 }, "install": { "script_tag": "", "snippet_key": "ab12cd34ef56", "inbound_email": "ab12cd34ef56@in.checkbox.site", "webhook_urls": { "stripe": "https://app.checkbox.site/webhooks/stripe/…" } }, "archived": false, "created": 1793318400, "latest_scan": { "id": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "scan", "livemode": false, "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "status": "completed", "trigger": "api", "regions": [ "US-CA", "US-NY" ], "error": null, "warnings": [], "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "score": 82, "insurable": false, "started": 1793318400, "finished": 1793318400, "created": 1793318400 }, "domain_verification": { "id": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "object": "domain_verification", "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", "domain": "acme.example", "status": "pending", "method": null, "verified_at": 1793318400, "last_checked": 1793318400, "last_error": "TXT record not found", "dns_record": { "type": "TXT", "name": "_checkbox-verify.acme.example", "value": "checkbox-verify=Xy…" }, "file": { "url": "https://acme.example/.well-known/checkbox-verify.txt", "contents": "Xy…" }, "scan_target_problems": [], "account_activated": false, "next_action": { "type": "publish_dns_record", "message": "Publish the TXT record, then call checkDomainVerification.", "operation_id": "checkDomainVerification", "mcp_tool": "call_api" } } }, "previous_attributes": {} } } } } ], "description": "Something that happened in the account. Delivered to webhook endpoints and listed by listEvents (kept 30 days)." } } } }, "responses": { "200": { "description": "Return any 2xx status to acknowledge the event." } } } } }, "x-error-codes": { "parameter_invalid": { "status": 400, "type": "invalid_request_error", "description": "A parameter has an invalid value; `param` names it." }, "parameter_missing": { "status": 400, "type": "invalid_request_error", "description": "A required parameter is missing; `param` names it." }, "parameter_unknown": { "status": 400, "type": "invalid_request_error", "description": "The request has a parameter this endpoint does not accept." }, "body_invalid_json": { "status": 400, "type": "invalid_request_error", "description": "The request body is not valid JSON." }, "url_not_allowed": { "status": 400, "type": "invalid_request_error", "description": "A URL points to a private, local or otherwise unreachable address." }, "api_version_invalid": { "status": 400, "type": "invalid_request_error", "description": "The Checkbox-Version header names an unknown API version." }, "idempotency_key_invalid": { "status": 400, "type": "idempotency_error", "description": "The Idempotency-Key header is empty or longer than 255 characters." }, "idempotency_key_reused": { "status": 400, "type": "idempotency_error", "description": "The Idempotency-Key was already used with different parameters within 24 hours." }, "test_key_missing": { "status": 400, "type": "invalid_request_error", "description": "A Stripe test run needs a Stripe TEST-mode key stored for the site (createTestCredential)." }, "test_key_not_test_mode": { "status": 400, "type": "invalid_request_error", "description": "The billing key is a live-mode (or malformed) key; test runs only accept test-mode keys (rk_test_… / sk_test_…)." }, "test_key_rejected": { "status": 400, "type": "invalid_request_error", "description": "Stripe rejected the test-mode key or it lacks a permission test runs need; `message` names it." }, "authorization_pending": { "status": 400, "type": "invalid_request_error", "description": "Device login: the human has not approved yet. Keep polling createDeviceToken every `interval` seconds." }, "slow_down": { "status": 400, "type": "rate_limit_error", "description": "Device login: polling too fast. Add 5 seconds to the interval and keep polling." }, "expired_token": { "status": 400, "type": "invalid_request_error", "description": "Device login: the device code expired (15 minutes) or was already used. Start again with createDeviceAuthorization." }, "device_code_invalid": { "status": 400, "type": "invalid_request_error", "description": "Device login: the device code is unknown." }, "access_denied": { "status": 403, "type": "permission_error", "description": "Device login: the human clicked Deny. Do not retry without asking them." }, "api_key_missing": { "status": 401, "type": "authentication_error", "description": "No API key was provided (Authorization: Bearer ck_…)." }, "api_key_invalid": { "status": 401, "type": "authentication_error", "description": "The API key is unknown, revoked or expired." }, "publishable_key_not_allowed": { "status": 403, "type": "permission_error", "description": "A publishable key (pk_…) cannot call this endpoint; use a secret key on your server." }, "origin_not_allowed": { "status": 403, "type": "permission_error", "description": "A publishable-key request came from a page (Origin) that is not on one of the site's domains (base URL or checkout URL)." }, "insufficient_scope": { "status": 403, "type": "permission_error", "description": "The restricted key lacks the scope this endpoint needs." }, "insufficient_role": { "status": 403, "type": "permission_error", "description": "The key (or the person who created it) does not have a role that allows this action." }, "account_not_activated": { "status": 403, "type": "permission_error", "description": "Live mode needs an activated account: verify the domain of one of your sites (or use a test key)." }, "test_mode_domain_unverified": { "status": 403, "type": "permission_error", "description": "Test mode only scans, monitors, fetches and test-runs localhost or domains the account has verified; verify the domain (createDomainVerification) or send the HTML instead." }, "test_mode_scan_budget_exhausted": { "status": 429, "type": "rate_limit_error", "description": "The daily test-mode scan budget for sites on unverified domains is used up; verify the domain (createDomainVerification) to lift it." }, "account_suspended": { "status": 403, "type": "permission_error", "description": "The account was suspended by Checkbox staff; contact support." }, "resource_missing": { "status": 404, "type": "invalid_request_error", "description": "No object with this id exists in this mode of the account." }, "route_not_found": { "status": 404, "type": "invalid_request_error", "description": "No such endpoint. See /v1/openapi.json for the list." }, "resource_conflict": { "status": 409, "type": "invalid_request_error", "description": "The object is in a state that does not allow this action." }, "scan_already_queued": { "status": 409, "type": "invalid_request_error", "description": "A scan of this site is already queued or running." }, "consent_reference_locked": { "status": 409, "type": "invalid_request_error", "description": "The consent already carries a different customer_reference; references are set once and never changed." }, "test_run_in_progress": { "status": 409, "type": "invalid_request_error", "description": "The site already has a queued or running test run; wait for it (retrieveTestRun) or cancel it (cancelTestRun)." }, "idempotency_key_in_use": { "status": 409, "type": "idempotency_error", "description": "A request with this Idempotency-Key is still being processed; retry shortly." }, "resource_archived": { "status": 410, "type": "invalid_request_error", "description": "The object is archived; restore it before changing it." }, "body_too_large": { "status": 413, "type": "invalid_request_error", "description": "The request body is too large." }, "content_type_unsupported": { "status": 415, "type": "invalid_request_error", "description": "Send JSON bodies with Content-Type: application/json." }, "site_limit_reached": { "status": 403, "type": "invalid_request_error", "description": "The account reached its fair-use site limit (default 25); contact support to raise it." }, "webhook_endpoint_limit_reached": { "status": 403, "type": "invalid_request_error", "description": "The account reached the maximum number of webhook endpoints (16 per mode)." }, "plan_required": { "status": 402, "type": "invalid_request_error", "description": "Only when billing is enabled on this deployment: the feature needs a paid plan." }, "rate_limit_exceeded": { "status": 429, "type": "rate_limit_error", "description": "Too many requests; slow down and retry after the Retry-After header." }, "feature_unavailable": { "status": 503, "type": "api_error", "description": "The feature is not configured on this deployment (for example the database migration is missing)." }, "internal_error": { "status": 500, "type": "api_error", "description": "Something went wrong on Checkbox's side. Retrying with the same Idempotency-Key is safe." } }, "x-api-versions": [ "2026-10-30" ] }