Sites API

View as Markdown Open in Claude

The subscription businesses Checkbox monitors, how to install the snippet, and domain verification (which activates live mode).

Operation	Endpoint
List sites	`GET /v1/sites`
Create a site	`POST /v1/sites`
Retrieve a site	`GET /v1/sites/{site}`
Update a site	`POST /v1/sites/{site}`
Archive a site	`DELETE /v1/sites/{site}`
Restore an archived site	`POST /v1/sites/{site}/restore`
Connect a billing platform	`POST /v1/sites/{site}/integrations`
Retrieve domain verification	`GET /v1/sites/{site}/domain_verification`
Start domain verification	`POST /v1/sites/{site}/domain_verification`
Check domain verification now	`POST /v1/sites/{site}/domain_verification/check`
Re-sync Stripe settings	`POST /v1/sites/{site}/billing/resync`

The Site object

A subscription business Checkbox monitors.

Field	Type	Description
`id`	string	Unique identifier of the site (site_…).
`object`	enum	String representing the object's type. Always "site".
`livemode`	boolean	true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).
`name`	string	Display name.
`url`	string	Base URL.
`platform`	enum	Billing platform. One of `stripe`, `shopify`, `recharge`, `chargebee`, `recurly`, `paddle`, `woocommerce`, `custom`.
`jurisdictions`	array of enum	Evaluated jurisdictions (empty = all).
`facts`	SiteFacts	Business facts that decide which legal requirements apply.
`checkout`	object	Synthetic-shopper configuration (secrets are never returned).
`checkout.url`	string	Checkout entry page.
`checkout.regions`	array of enum	States scanned from.
`checkout.devices`	array of enum	Devices scanned.
`checkout.checkout_steps`	integer	Number of configured checkout steps.
`checkout.completes_purchase`	boolean	A synthetic sign-up is configured.
`checkout.has_test_account`	boolean	A test account for the cancellation test is configured.
`checkout.test_account`	object \| null	The test account as configured (the password is write-only and never returned).
`checkout.cancel_steps`	integer	Number of explicit cancellation steps.
`checkout.account_url`	string \| null	Public account / cancellation page visited on every scan.
`checkout.terms_url`	string \| null	Terms of service page read on every scan.
`checkout.homepage_as_checkout`	boolean	The checkout page is the home page (checkout_url was omitted or set to the site root). Sign-up checks then judge the home page: set checkout_url to the page with the subscribe button unless the home page really has it.
`monitoring`	SiteMonitoring	Scheduled monitoring.
`protection_level`	enum	Which requirement tiers Checkbox shows (minimum: required only; balanced: + recommended suggestions; maximum: + extras). Only required items affect compliance. One of `minimum`, `balanced`, `maximum`.
`retention`	SiteRetention	The retention in effect for the site.
`legal_hold`	LegalHold	Account-wide legal hold: while active, nothing of this mode's data is deleted.
`compliance`	SiteCompliance \| null	Latest verdict; null until the first evaluation.
`install`	SiteInstall	What to install on the merchant site.
`archived`	boolean	Archived (soft-deleted); evidence is retained.
`created`	integer	When the site was created. Unix timestamp in seconds.
`latest_scan`	Scan	Most recent scan (only with expand[]=latest_scan).
`unverified_scan`	UnverifiedScan \| null	While the domain is not verified: the newest read-only scan of the site's own public pages (labeled "unverified scan": no checkout submitted, not evidence, replaced by the full scan after verification). Null otherwise.
`domain_verification`	DomainVerification	Domain verification (only with expand[]=domain_verification).

List sites

GET /v1/sites

Returns the sites of the account in the current mode, newest first. Archived sites are included only with archived=true.

Scope sites:read · Operation listSites

SDK: checkbox.sites.list() (Node) · checkbox.sites.list() (Python). MCP / agents: operation listSites.

Parameters

Parameter	In	Type	Description
`limit`	query	integer	Number of objects to return, 1-100 (default 10).
`starting_after`	query	string	Cursor: an object id; returns the objects after it (older).
`ending_before`	query	string	Cursor: an object id; returns the objects before it (newer).
`archived`	query	enum	true lists only archived sites. One of `true`, `false`.

Returns

Returns a list ({ object: "list", data, has_more, url }) of Site objects.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl -G https://app.checkbox.site/v1/sites \
  -u "$CHECKBOX_SECRET_KEY:" \
  -d limit=3

import Checkbox from '@checkbox-site/node';

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

const sites = await checkbox.sites.list({ limit: 3 });
console.log(sites.data);

import os
from checkbox import Checkbox

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

sites = checkbox.sites.list(limit=3)
print(sites.data)

Response

{
  "object": "list",
  "data": [
    {
      "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,
        "plan_price_id": "price_1Pabc",
        "payment_methods": [
          "card"
        ],
        "checkout_type": "payment_link"
      },
      "checkout": {
        "url": "https://acme.example/pricing",
        "regions": [
          "US-CA"
        ],
        "devices": [
          "desktop"
        ],
        "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,
        "account_url": "https://acme.example/account",
        "terms_url": "https://acme.example/terms",
        "homepage_as_checkout": false
      },
      "monitoring": {
        "enabled": true,
        "interval_minutes": 1440,
        "held_for_activation": false,
        "last_scanned": 1793318400,
        "held_for_domain_verification": false,
        "verify_domains": []
      },
      "protection_level": "balanced",
      "retention": {
        "records_years": 7,
        "superseded_results_days": 30,
        "good_practice_years": 7,
        "problem_history_days": 30
      },
      "legal_hold": {
        "active": false,
        "scope": null,
        "set": null,
        "reason": null
      },
      "compliance": {
        "evaluated": 1793318400,
        "open_findings": 2,
        "needs_review": 1,
        "status": "compliant",
        "label": "Compliant · 2 live checks pending",
        "rollup": {
          "status": "compliant",
          "label": "Compliant · 2 live checks pending",
          "counts": {
            "needs_fix": 0,
            "your_call": 0,
            "pending_live_check": 2,
            "verified_live": 3,
            "compliant": 9,
            "not_applicable": 6,
            "not_set_up": 0,
            "not_checked": 0
          },
          "pending_live_checks": [
            {
              "what": "Your acknowledgment email, seen sent for a real sign-up",
              "completes": "Run a proof, or BCC your real acknowledgment emails to your Checkbox inbound address.",
              "action": "bcc_real_sends",
              "due": "2026-11-20"
            }
          ],
          "suggestions": 1,
          "checkouts": [
            {
              "name": "Annual",
              "kind": "payment_link",
              "plan": "Annual",
              "status": "pending_live_check",
              "label": "Needs a fix",
              "open": []
            }
          ]
        }
      },
      "install": {
        "script_tag": "<script async src=\"https://app.checkbox.site/s.js\" data-key=\"ab12…\"></script>",
        "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"
        ],
        "error": null,
        "warnings": [],
        "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
        "compliance": {
          "status": "needs_fix",
          "label": "2 fixes needed"
        },
        "started": 1793318400,
        "finished": 1793318400,
        "created": 1793318400
      },
      "unverified_scan": {
        "id": "uscan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
        "object": "unverified_scan",
        "unverified": true,
        "label": "unverified scan",
        "status": "completed",
        "created": 1793318400,
        "finished": 1793318400,
        "pages": [],
        "findings": [],
        "counts": {
          "pages_captured": 6,
          "pages_skipped": 1,
          "failing": 2,
          "needs_review": 1,
          "passing": 9
        },
        "error": null,
        "note": "Unverified scan: Checkbox only loaded public pages of this site…"
      },
      "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…"
        },
        "meta_tag": {
          "url": "https://acme.example/",
          "html": "<meta name=\"checkbox-verify\" content=\"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",
          "endpoint": "POST /v1/sites/{site}/domain_verification/check"
        }
      }
    }
  ],
  "has_more": false,
  "url": "/v1/sites"
}

Create a site

POST /v1/sites

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.

Scope sites:write · Idempotent (send Idempotency-Key) · Operation createSite

SDK: checkbox.sites.create() (Node) · checkbox.sites.create() (Python). MCP / agents: operation createSite.

Body

Field	Type	Description
`name`	string	Display name.
`url` required	string	Base URL of the business website.
`platform`	enum	Billing platform. One of `stripe`, `shopify`, `recharge`, `chargebee`, `recurly`, `paddle`, `woocommerce`, `custom`.
`jurisdictions`	array of enum	Jurisdictions to evaluate (empty = all US laws).
`facts`	SiteFacts	Business facts that decide which legal requirements apply.
`checkout_url`	string	Page with the subscribe button (defaults to url). Not a Stripe-hosted session link.
`account_url`	string \| null	Public account or cancellation page. Visited on every scan, even without a test account, so offline-only cancellation instructions are seen. null clears it.
`terms_url`	string \| null	Terms of service page. Checkbox reads it on every scan (rendering JavaScript, so single-page apps work) and checks its renewal and cancellation terms. null clears it.
`checkout_steps`	array of ScanSteps	Steps to reach the final pre-payment screen.
`purchase`	SitePurchase	How the synthetic shopper completes a real (free) sign-up.
`test_account`	SiteTestAccount	A test customer account the synthetic shopper uses to try cancelling online.
`cancel_steps`	array of ScanSteps	Explicit cancellation steps (otherwise auto-discovered).
`regions`	array of enum	States the synthetic shopper visits from.
`devices`	array of enum	Devices to emulate.
`monitoring_interval_minutes`	integer	Scheduled re-scan interval (0 = off, minimum 60). Default 1440 in live mode, 0 in test mode.
`protection_level`	enum	Which requirement tiers Checkbox shows. minimum: the legal floor only (required items). balanced (default): required items plus recommended suggestions (consent receipts, a cancellation confirmation email…), collapsed and never blocking "compliant". maximum: everything, including extra protections (a separate checkbox per term, a pre-purchase summary). Only required items can make a site not compliant, at every level. One of `minimum`, `balanced`, `maximum`.

Returns

Returns a Site object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/sites \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://acme.example"
}'

import Checkbox from '@checkbox-site/node';

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

const site = await checkbox.sites.create({ url: 'https://acme.example' });
console.log(site);

import os
from checkbox import Checkbox

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

site = checkbox.sites.create(url="https://acme.example")
print(site)

Response

{
  "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,
    "plan_price_id": "price_1Pabc",
    "payment_methods": [
      "card"
    ],
    "checkout_type": "payment_link"
  },
  "checkout": {
    "url": "https://acme.example/pricing",
    "regions": [
      "US-CA"
    ],
    "devices": [
      "desktop"
    ],
    "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,
    "account_url": "https://acme.example/account",
    "terms_url": "https://acme.example/terms",
    "homepage_as_checkout": false
  },
  "monitoring": {
    "enabled": true,
    "interval_minutes": 1440,
    "held_for_activation": false,
    "last_scanned": 1793318400,
    "held_for_domain_verification": false,
    "verify_domains": []
  },
  "protection_level": "balanced",
  "retention": {
    "records_years": 7,
    "superseded_results_days": 30,
    "good_practice_years": 7,
    "problem_history_days": 30,
    "inherited": true
  },
  "legal_hold": {
    "active": false,
    "scope": null,
    "set": null,
    "reason": null
  },
  "compliance": {
    "evaluated": 1793318400,
    "open_findings": 2,
    "needs_review": 1,
    "status": "compliant",
    "label": "Compliant · 2 live checks pending",
    "rollup": {
      "status": "compliant",
      "label": "Compliant · 2 live checks pending",
      "counts": {
        "needs_fix": 0,
        "your_call": 0,
        "pending_live_check": 2,
        "verified_live": 3,
        "compliant": 9,
        "not_applicable": 6,
        "not_set_up": 0,
        "not_checked": 0
      },
      "pending_live_checks": [
        {
          "what": "Your acknowledgment email, seen sent for a real sign-up",
          "completes": "Run a proof, or BCC your real acknowledgment emails to your Checkbox inbound address.",
          "action": "bcc_real_sends",
          "due": "2026-11-20"
        }
      ],
      "suggestions": 1,
      "checkouts": [
        {
          "name": "Annual",
          "kind": "payment_link",
          "plan": "Annual",
          "status": "pending_live_check",
          "label": "Needs a fix",
          "open": [
            {
              "check_id": "signup.disclosure.price",
              "title": "recurring charge is stated",
              "status": "pending_live_check"
            }
          ]
        }
      ]
    }
  },
  "install": {
    "script_tag": "<script async src=\"https://app.checkbox.site/s.js\" data-key=\"ab12…\"></script>",
    "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"
    ],
    "error": null,
    "warnings": [],
    "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "compliance": {
      "status": "needs_fix",
      "label": "2 fixes needed"
    },
    "started": 1793318400,
    "finished": 1793318400,
    "created": 1793318400
  },
  "unverified_scan": {
    "id": "uscan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "object": "unverified_scan",
    "unverified": true,
    "label": "unverified scan",
    "status": "completed",
    "created": 1793318400,
    "finished": 1793318400,
    "pages": [],
    "findings": [],
    "counts": {
      "pages_captured": 6,
      "pages_skipped": 1,
      "failing": 2,
      "needs_review": 1,
      "passing": 9
    },
    "error": null,
    "note": "Unverified scan: Checkbox only loaded public pages of this site…"
  },
  "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…"
    },
    "meta_tag": {
      "url": "https://acme.example/",
      "html": "<meta name=\"checkbox-verify\" content=\"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",
      "endpoint": "POST /v1/sites/{site}/domain_verification/check"
    }
  }
}

Retrieve a site

GET /v1/sites/{site}

Returns a site with its latest compliance status (label and counts) and install details.

Scope sites:read · Operation retrieveSite

SDK: checkbox.sites.retrieve() (Node) · checkbox.sites.retrieve() (Python). MCP / agents: operation retrieveSite.

Parameters

Parameter	In	Type	Description
`site` required	path	string	Unique identifier of the site (site_…).
`expand[]`	query	array of enum	Related objects to include inline: latest_scan, domain_verification. Pass as expand[]=name.

Returns

Returns a Site object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b \
  -u "$CHECKBOX_SECRET_KEY:"

import Checkbox from '@checkbox-site/node';

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

const site = await checkbox.sites.retrieve('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(site);

import os
from checkbox import Checkbox

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

site = checkbox.sites.retrieve("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(site)

Response

{
  "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,
    "plan_price_id": "price_1Pabc",
    "payment_methods": [
      "card"
    ],
    "checkout_type": "payment_link"
  },
  "checkout": {
    "url": "https://acme.example/pricing",
    "regions": [
      "US-CA"
    ],
    "devices": [
      "desktop"
    ],
    "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,
    "account_url": "https://acme.example/account",
    "terms_url": "https://acme.example/terms",
    "homepage_as_checkout": false
  },
  "monitoring": {
    "enabled": true,
    "interval_minutes": 1440,
    "held_for_activation": false,
    "last_scanned": 1793318400,
    "held_for_domain_verification": false,
    "verify_domains": []
  },
  "protection_level": "balanced",
  "retention": {
    "records_years": 7,
    "superseded_results_days": 30,
    "good_practice_years": 7,
    "problem_history_days": 30,
    "inherited": true
  },
  "legal_hold": {
    "active": false,
    "scope": null,
    "set": null,
    "reason": null
  },
  "compliance": {
    "evaluated": 1793318400,
    "open_findings": 2,
    "needs_review": 1,
    "status": "compliant",
    "label": "Compliant · 2 live checks pending",
    "rollup": {
      "status": "compliant",
      "label": "Compliant · 2 live checks pending",
      "counts": {
        "needs_fix": 0,
        "your_call": 0,
        "pending_live_check": 2,
        "verified_live": 3,
        "compliant": 9,
        "not_applicable": 6,
        "not_set_up": 0,
        "not_checked": 0
      },
      "pending_live_checks": [
        {
          "what": "Your acknowledgment email, seen sent for a real sign-up",
          "completes": "Run a proof, or BCC your real acknowledgment emails to your Checkbox inbound address.",
          "action": "bcc_real_sends",
          "due": "2026-11-20"
        }
      ],
      "suggestions": 1,
      "checkouts": [
        {
          "name": "Annual",
          "kind": "payment_link",
          "plan": "Annual",
          "status": "pending_live_check",
          "label": "Needs a fix",
          "open": [
            {
              "check_id": "signup.disclosure.price",
              "title": "recurring charge is stated",
              "status": "pending_live_check"
            }
          ]
        }
      ]
    }
  },
  "install": {
    "script_tag": "<script async src=\"https://app.checkbox.site/s.js\" data-key=\"ab12…\"></script>",
    "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"
    ],
    "error": null,
    "warnings": [],
    "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "compliance": {
      "status": "needs_fix",
      "label": "2 fixes needed"
    },
    "started": 1793318400,
    "finished": 1793318400,
    "created": 1793318400
  },
  "unverified_scan": {
    "id": "uscan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "object": "unverified_scan",
    "unverified": true,
    "label": "unverified scan",
    "status": "completed",
    "created": 1793318400,
    "finished": 1793318400,
    "pages": [],
    "findings": [],
    "counts": {
      "pages_captured": 6,
      "pages_skipped": 1,
      "failing": 2,
      "needs_review": 1,
      "passing": 9
    },
    "error": null,
    "note": "Unverified scan: Checkbox only loaded public pages of this site…"
  },
  "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…"
    },
    "meta_tag": {
      "url": "https://acme.example/",
      "html": "<meta name=\"checkbox-verify\" content=\"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",
      "endpoint": "POST /v1/sites/{site}/domain_verification/check"
    }
  }
}

Update a site

POST /v1/sites/{site}

Updates the given fields; omitted fields keep their values. Changing url to another domain forgets the domain verification and ends the active certificate.

Scope sites:write · Idempotent (send Idempotency-Key) · Operation updateSite

SDK: checkbox.sites.update() (Node) · checkbox.sites.update() (Python). MCP / agents: operation updateSite.

Parameters

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

Body

Field	Type	Description
`name`	string	Display name.
`url`	string	Base URL of the business website.
`platform`	enum	Billing platform. One of `stripe`, `shopify`, `recharge`, `chargebee`, `recurly`, `paddle`, `woocommerce`, `custom`.
`jurisdictions`	array of enum	Jurisdictions to evaluate (empty = all US laws).
`facts`	SiteFacts	Business facts that decide which legal requirements apply.
`checkout_url`	string	Page with the subscribe button (defaults to url). Not a Stripe-hosted session link.
`account_url`	string \| null	Public account or cancellation page. Visited on every scan, even without a test account, so offline-only cancellation instructions are seen. null clears it.
`terms_url`	string \| null	Terms of service page. Checkbox reads it on every scan (rendering JavaScript, so single-page apps work) and checks its renewal and cancellation terms. null clears it.
`checkout_steps`	array of ScanSteps	Steps to reach the final pre-payment screen.
`purchase`	SitePurchase	How the synthetic shopper completes a real (free) sign-up.
`test_account`	SiteTestAccount	A test customer account the synthetic shopper uses to try cancelling online.
`cancel_steps`	array of ScanSteps	Explicit cancellation steps (otherwise auto-discovered).
`regions`	array of enum	States the synthetic shopper visits from.
`devices`	array of enum	Devices to emulate.
`monitoring_interval_minutes`	integer	Scheduled re-scan interval (0 = off, minimum 60). Default 1440 in live mode, 0 in test mode.
`protection_level`	enum	Which requirement tiers Checkbox shows. minimum: the legal floor only (required items). balanced (default): required items plus recommended suggestions (consent receipts, a cancellation confirmation email…), collapsed and never blocking "compliant". maximum: everything, including extra protections (a separate checkbox per term, a pre-purchase summary). Only required items can make a site not compliant, at every level. One of `minimum`, `balanced`, `maximum`.
`checkout`	object	The URLs nested as the site object returns them (checkout.url, checkout.account_url, checkout.terms_url); the flat fields win when both are given.
`checkout.url`	string	Same as checkout_url.
`checkout.account_url`	string \| null	Same as account_url.
`checkout.terms_url`	string \| null	Same as terms_url.
`retention`	RetentionParams	Default retention for every site without its own setting. A longer period for superseded check results keeps a fuller timeline of changes to your site.
`retention.records_years`	integer \| null	Years records are kept (1-10). On a site, null returns to the account default.
`retention.superseded_results_days`	integer \| null	Days superseded check results are kept (7-730). On a site, null returns to the account default.
`retention.good_practice_years`	integer \| null	Deprecated: use records_years.
`retention.problem_history_days`	integer \| null	Deprecated: use superseded_results_days.
`legal_hold`	LegalHoldParams	Account-wide legal hold: suspends every deletion of the account's records until turned off.
`legal_hold.active` required	boolean	true turns the hold on, false turns it off.
`legal_hold.reason`	string	Note stored with the hold (who asked, matter).

Returns

Returns a Site object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme Coffee Club"
}'

import Checkbox from '@checkbox-site/node';

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

const site = await checkbox.sites.update('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b', { name: 'Acme Coffee Club' });
console.log(site);

import os
from checkbox import Checkbox

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

site = checkbox.sites.update("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", name="Acme Coffee Club")
print(site)

Response

{
  "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,
    "plan_price_id": "price_1Pabc",
    "payment_methods": [
      "card"
    ],
    "checkout_type": "payment_link"
  },
  "checkout": {
    "url": "https://acme.example/pricing",
    "regions": [
      "US-CA"
    ],
    "devices": [
      "desktop"
    ],
    "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,
    "account_url": "https://acme.example/account",
    "terms_url": "https://acme.example/terms",
    "homepage_as_checkout": false
  },
  "monitoring": {
    "enabled": true,
    "interval_minutes": 1440,
    "held_for_activation": false,
    "last_scanned": 1793318400,
    "held_for_domain_verification": false,
    "verify_domains": []
  },
  "protection_level": "balanced",
  "retention": {
    "records_years": 7,
    "superseded_results_days": 30,
    "good_practice_years": 7,
    "problem_history_days": 30,
    "inherited": true
  },
  "legal_hold": {
    "active": false,
    "scope": null,
    "set": null,
    "reason": null
  },
  "compliance": {
    "evaluated": 1793318400,
    "open_findings": 2,
    "needs_review": 1,
    "status": "compliant",
    "label": "Compliant · 2 live checks pending",
    "rollup": {
      "status": "compliant",
      "label": "Compliant · 2 live checks pending",
      "counts": {
        "needs_fix": 0,
        "your_call": 0,
        "pending_live_check": 2,
        "verified_live": 3,
        "compliant": 9,
        "not_applicable": 6,
        "not_set_up": 0,
        "not_checked": 0
      },
      "pending_live_checks": [
        {
          "what": "Your acknowledgment email, seen sent for a real sign-up",
          "completes": "Run a proof, or BCC your real acknowledgment emails to your Checkbox inbound address.",
          "action": "bcc_real_sends",
          "due": "2026-11-20"
        }
      ],
      "suggestions": 1,
      "checkouts": [
        {
          "name": "Annual",
          "kind": "payment_link",
          "plan": "Annual",
          "status": "pending_live_check",
          "label": "Needs a fix",
          "open": [
            {
              "check_id": "signup.disclosure.price",
              "title": "recurring charge is stated",
              "status": "pending_live_check"
            }
          ]
        }
      ]
    }
  },
  "install": {
    "script_tag": "<script async src=\"https://app.checkbox.site/s.js\" data-key=\"ab12…\"></script>",
    "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"
    ],
    "error": null,
    "warnings": [],
    "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "compliance": {
      "status": "needs_fix",
      "label": "2 fixes needed"
    },
    "started": 1793318400,
    "finished": 1793318400,
    "created": 1793318400
  },
  "unverified_scan": {
    "id": "uscan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "object": "unverified_scan",
    "unverified": true,
    "label": "unverified scan",
    "status": "completed",
    "created": 1793318400,
    "finished": 1793318400,
    "pages": [],
    "findings": [],
    "counts": {
      "pages_captured": 6,
      "pages_skipped": 1,
      "failing": 2,
      "needs_review": 1,
      "passing": 9
    },
    "error": null,
    "note": "Unverified scan: Checkbox only loaded public pages of this site…"
  },
  "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…"
    },
    "meta_tag": {
      "url": "https://acme.example/",
      "html": "<meta name=\"checkbox-verify\" content=\"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",
      "endpoint": "POST /v1/sites/{site}/domain_verification/check"
    }
  }
}

Archive a site

DELETE /v1/sites/{site}

Archives (soft-deletes) the site: monitoring stops and it disappears from lists, but evidence and findings are retained. Undo with restoreSite.

Scope sites:write · Operation deleteSite

SDK: checkbox.sites.del() (Node) · checkbox.sites.delete() (Python). MCP / agents: operation deleteSite.

Parameters

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

Returns

Returns a Site object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b \
  -u "$CHECKBOX_SECRET_KEY:" \
  -X DELETE

import Checkbox from '@checkbox-site/node';

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

const site = await checkbox.sites.del('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(site);

import os
from checkbox import Checkbox

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

site = checkbox.sites.delete("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(site)

Response

{
  "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,
    "plan_price_id": "price_1Pabc",
    "payment_methods": [
      "card"
    ],
    "checkout_type": "payment_link"
  },
  "checkout": {
    "url": "https://acme.example/pricing",
    "regions": [
      "US-CA"
    ],
    "devices": [
      "desktop"
    ],
    "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,
    "account_url": "https://acme.example/account",
    "terms_url": "https://acme.example/terms",
    "homepage_as_checkout": false
  },
  "monitoring": {
    "enabled": true,
    "interval_minutes": 1440,
    "held_for_activation": false,
    "last_scanned": 1793318400,
    "held_for_domain_verification": false,
    "verify_domains": []
  },
  "protection_level": "balanced",
  "retention": {
    "records_years": 7,
    "superseded_results_days": 30,
    "good_practice_years": 7,
    "problem_history_days": 30,
    "inherited": true
  },
  "legal_hold": {
    "active": false,
    "scope": null,
    "set": null,
    "reason": null
  },
  "compliance": {
    "evaluated": 1793318400,
    "open_findings": 2,
    "needs_review": 1,
    "status": "compliant",
    "label": "Compliant · 2 live checks pending",
    "rollup": {
      "status": "compliant",
      "label": "Compliant · 2 live checks pending",
      "counts": {
        "needs_fix": 0,
        "your_call": 0,
        "pending_live_check": 2,
        "verified_live": 3,
        "compliant": 9,
        "not_applicable": 6,
        "not_set_up": 0,
        "not_checked": 0
      },
      "pending_live_checks": [
        {
          "what": "Your acknowledgment email, seen sent for a real sign-up",
          "completes": "Run a proof, or BCC your real acknowledgment emails to your Checkbox inbound address.",
          "action": "bcc_real_sends",
          "due": "2026-11-20"
        }
      ],
      "suggestions": 1,
      "checkouts": [
        {
          "name": "Annual",
          "kind": "payment_link",
          "plan": "Annual",
          "status": "pending_live_check",
          "label": "Needs a fix",
          "open": [
            {
              "check_id": "signup.disclosure.price",
              "title": "recurring charge is stated",
              "status": "pending_live_check"
            }
          ]
        }
      ]
    }
  },
  "install": {
    "script_tag": "<script async src=\"https://app.checkbox.site/s.js\" data-key=\"ab12…\"></script>",
    "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"
    ],
    "error": null,
    "warnings": [],
    "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "compliance": {
      "status": "needs_fix",
      "label": "2 fixes needed"
    },
    "started": 1793318400,
    "finished": 1793318400,
    "created": 1793318400
  },
  "unverified_scan": {
    "id": "uscan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "object": "unverified_scan",
    "unverified": true,
    "label": "unverified scan",
    "status": "completed",
    "created": 1793318400,
    "finished": 1793318400,
    "pages": [],
    "findings": [],
    "counts": {
      "pages_captured": 6,
      "pages_skipped": 1,
      "failing": 2,
      "needs_review": 1,
      "passing": 9
    },
    "error": null,
    "note": "Unverified scan: Checkbox only loaded public pages of this site…"
  },
  "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…"
    },
    "meta_tag": {
      "url": "https://acme.example/",
      "html": "<meta name=\"checkbox-verify\" content=\"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",
      "endpoint": "POST /v1/sites/{site}/domain_verification/check"
    }
  }
}

Restore an archived site

POST /v1/sites/{site}/restore

Un-archives a site (counts against the fair-use site limit again).

Scope sites:write · Idempotent (send Idempotency-Key) · Operation restoreSite

SDK: checkbox.sites.restore() (Node) · checkbox.sites.restore() (Python). MCP / agents: operation restoreSite.

Parameters

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

Returns

Returns a Site object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/restore \
  -u "$CHECKBOX_SECRET_KEY:" \
  -X POST

import Checkbox from '@checkbox-site/node';

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

const site = await checkbox.sites.restore('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(site);

import os
from checkbox import Checkbox

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

site = checkbox.sites.restore("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(site)

Response

{
  "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,
    "plan_price_id": "price_1Pabc",
    "payment_methods": [
      "card"
    ],
    "checkout_type": "payment_link"
  },
  "checkout": {
    "url": "https://acme.example/pricing",
    "regions": [
      "US-CA"
    ],
    "devices": [
      "desktop"
    ],
    "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,
    "account_url": "https://acme.example/account",
    "terms_url": "https://acme.example/terms",
    "homepage_as_checkout": false
  },
  "monitoring": {
    "enabled": true,
    "interval_minutes": 1440,
    "held_for_activation": false,
    "last_scanned": 1793318400,
    "held_for_domain_verification": false,
    "verify_domains": []
  },
  "protection_level": "balanced",
  "retention": {
    "records_years": 7,
    "superseded_results_days": 30,
    "good_practice_years": 7,
    "problem_history_days": 30,
    "inherited": true
  },
  "legal_hold": {
    "active": false,
    "scope": null,
    "set": null,
    "reason": null
  },
  "compliance": {
    "evaluated": 1793318400,
    "open_findings": 2,
    "needs_review": 1,
    "status": "compliant",
    "label": "Compliant · 2 live checks pending",
    "rollup": {
      "status": "compliant",
      "label": "Compliant · 2 live checks pending",
      "counts": {
        "needs_fix": 0,
        "your_call": 0,
        "pending_live_check": 2,
        "verified_live": 3,
        "compliant": 9,
        "not_applicable": 6,
        "not_set_up": 0,
        "not_checked": 0
      },
      "pending_live_checks": [
        {
          "what": "Your acknowledgment email, seen sent for a real sign-up",
          "completes": "Run a proof, or BCC your real acknowledgment emails to your Checkbox inbound address.",
          "action": "bcc_real_sends",
          "due": "2026-11-20"
        }
      ],
      "suggestions": 1,
      "checkouts": [
        {
          "name": "Annual",
          "kind": "payment_link",
          "plan": "Annual",
          "status": "pending_live_check",
          "label": "Needs a fix",
          "open": [
            {
              "check_id": "signup.disclosure.price",
              "title": "recurring charge is stated",
              "status": "pending_live_check"
            }
          ]
        }
      ]
    }
  },
  "install": {
    "script_tag": "<script async src=\"https://app.checkbox.site/s.js\" data-key=\"ab12…\"></script>",
    "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"
    ],
    "error": null,
    "warnings": [],
    "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "compliance": {
      "status": "needs_fix",
      "label": "2 fixes needed"
    },
    "started": 1793318400,
    "finished": 1793318400,
    "created": 1793318400
  },
  "unverified_scan": {
    "id": "uscan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "object": "unverified_scan",
    "unverified": true,
    "label": "unverified scan",
    "status": "completed",
    "created": 1793318400,
    "finished": 1793318400,
    "pages": [],
    "findings": [],
    "counts": {
      "pages_captured": 6,
      "pages_skipped": 1,
      "failing": 2,
      "needs_review": 1,
      "passing": 9
    },
    "error": null,
    "note": "Unverified scan: Checkbox only loaded public pages of this site…"
  },
  "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…"
    },
    "meta_tag": {
      "url": "https://acme.example/",
      "html": "<meta name=\"checkbox-verify\" content=\"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",
      "endpoint": "POST /v1/sites/{site}/domain_verification/check"
    }
  }
}

Connect a billing platform

POST /v1/sites/{site}/integrations

Connects the site's billing platform with read-only credentials (a Stripe restricted key, a Recharge token or a Shopify Admin API token), so Checkbox reads the customer-portal and reminder settings. Works for test-mode sites too (use an rk_test_ key). The credentials are validated by reading the settings once and stored encrypted.

Scope sites:write · Idempotent (send Idempotency-Key) · Operation connectBillingPlatform

SDK: checkbox.sites.connectBillingPlatform() (Node) · checkbox.sites.connect_billing_platform() (Python). MCP / agents: operation connectBillingPlatform.

Parameters

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

Body

Field	Type	Description
`platform` required	enum	Billing platform. One of `stripe`, `recharge`, `shopify`.
`credentials` required	object	Read-only credentials. Stripe: { "secretKey": "rk_test_…" } (a restricted key with read access; rk_test_ in test mode). Recharge: { "apiToken": "…" }. Shopify: { "shop": "store.myshopify.com", "accessToken": "shpat_…" }.

Returns

Returns an Integration object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/integrations \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "platform": "stripe",
  "credentials": {
    "secretKey": "rk_test_51H…"
  }
}'

import Checkbox from '@checkbox-site/node';

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

const site = await checkbox.sites.connectBillingPlatform('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b', {
  platform: 'stripe',
  credentials: { secretKey: 'rk_test_51H…' },
});
console.log(site);

import os
from checkbox import Checkbox

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

site = checkbox.sites.connect_billing_platform("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", platform="stripe", credentials={"secretKey": "rk_test_51H…"})
print(site)

Response

{
  "object": "integration",
  "livemode": false,
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "platform": "stripe",
  "status": "connected",
  "last_synced": 1793318400,
  "warning": null
}

Retrieve domain verification

GET /v1/sites/{site}/domain_verification

Status of the site domain verification, with the DNS record / file to publish.

Scope sites:read · Operation retrieveDomainVerification

SDK: checkbox.domainVerifications.retrieve() (Node) · checkbox.domain_verifications.retrieve() (Python). MCP / agents: operation retrieveDomainVerification.

Parameters

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

Returns

Returns a DomainVerification object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/domain_verification \
  -u "$CHECKBOX_SECRET_KEY:"

import Checkbox from '@checkbox-site/node';

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

const domainVerification = await checkbox.domainVerifications.retrieve('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(domainVerification);

import os
from checkbox import Checkbox

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

domain_verification = checkbox.domain_verifications.retrieve("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(domain_verification)

Response

{
  "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…"
  },
  "meta_tag": {
    "url": "https://acme.example/",
    "html": "<meta name=\"checkbox-verify\" content=\"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",
    "endpoint": "POST /v1/sites/{site}/domain_verification/check"
  }
}

Start domain verification

POST /v1/sites/{site}/domain_verification

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).

Scope sites:write · Idempotent (send Idempotency-Key) · Operation createDomainVerification

SDK: checkbox.domainVerifications.create() (Node) · checkbox.domain_verifications.create() (Python). MCP / agents: operation createDomainVerification.

Parameters

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

Body

Field	Type	Description
`rotate`	boolean	Issue a new token (invalidates the old one).

Returns

Returns a DomainVerification object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/domain_verification \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{}'

import Checkbox from '@checkbox-site/node';

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

const domainVerification = await checkbox.domainVerifications.create('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(domainVerification);

import os
from checkbox import Checkbox

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

domain_verification = checkbox.domain_verifications.create("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(domain_verification)

Response

{
  "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…"
  },
  "meta_tag": {
    "url": "https://acme.example/",
    "html": "<meta name=\"checkbox-verify\" content=\"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",
    "endpoint": "POST /v1/sites/{site}/domain_verification/check"
  }
}

Check domain verification now

POST /v1/sites/{site}/domain_verification/check

Looks for the DNS TXT record, the /.well-known file, and the site's Checkbox snippet or the checkbox-verify meta tag on https://<domain>/ now. On success in live mode, the account is activated and held monitoring starts.

Scope sites:write · Idempotent (send Idempotency-Key) · Operation checkDomainVerification

SDK: checkbox.domainVerifications.check() (Node) · checkbox.domain_verifications.check() (Python). MCP / agents: operation checkDomainVerification.

Parameters

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

Returns

Returns a DomainVerification object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/domain_verification/check \
  -u "$CHECKBOX_SECRET_KEY:" \
  -X POST

import Checkbox from '@checkbox-site/node';

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

const domainVerification = await checkbox.domainVerifications.check('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(domainVerification);

import os
from checkbox import Checkbox

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

domain_verification = checkbox.domain_verifications.check("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(domain_verification)

Response

{
  "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…"
  },
  "meta_tag": {
    "url": "https://acme.example/",
    "html": "<meta name=\"checkbox-verify\" content=\"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",
    "endpoint": "POST /v1/sites/{site}/domain_verification/check"
  }
}

Re-sync Stripe settings

POST /v1/sites/{site}/billing/resync

Re-reads the site's billing-platform settings now (Stripe customer-portal cancellation, trial-ending emails, plans) and re-evaluates the site, so a setting you just changed in Stripe shows up without waiting for the next scan. Every scan also re-reads them. Then poll retrieveLatestEvaluation (or listFindings) after about a minute.

Scope sites:write · Idempotent (send Idempotency-Key) · Operation resyncBilling

SDK: checkbox.billings.resync() (Node) · checkbox.billings.resync() (Python). MCP / agents: operation resyncBilling.

Parameters

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

Returns

Returns a BillingSync object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/billing/resync \
  -u "$CHECKBOX_SECRET_KEY:" \
  -X POST

import Checkbox from '@checkbox-site/node';

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

const billing = await checkbox.billings.resync('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(billing);

import os
from checkbox import Checkbox

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

billing = checkbox.billings.resync("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(billing)

Response

{
  "object": "billing_sync",
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "platforms": [
    {
      "platform": "stripe",
      "status": "queued",
      "last_synced": 1793318400,
      "last_error": null
    }
  ],
  "next_action": {
    "type": "verify_domain",
    "message": "Verify your site domain to turn on live mode.",
    "operation_id": "createDomainVerification",
    "mcp_tool": "call_api",
    "endpoint": "POST /v1/sites/{site}/domain_verification",
    "url": "https://checkbox.site/docs/concepts/activation#verify"
  }
}

Checkbox is compliance software, not a law firm; nothing in these docs is legal advice (details). You remain solely responsible for your subscription program, and Checkbox takes on no legal liability for it (Terms). Checkbox is a System1 company; Trust center · Status. For AI agents: every page is available as Markdown at the same URL plus .md; the index is /llms.txt.

Sites API

#The Site object

#List sites

#Parameters

#Returns

#Create a site

#Body

#Returns

#Retrieve a site

#Parameters

#Returns

#Update a site

#Parameters

#Body

#Returns

#Archive a site

#Parameters

#Returns

#Restore an archived site

#Parameters

#Returns

#Connect a billing platform

#Parameters

#Body

#Returns

#Retrieve domain verification

#Parameters

#Returns

#Start domain verification

#Parameters

#Body

#Returns

#Check domain verification now

#Parameters

#Returns

#Re-sync Stripe settings

#Parameters

#Returns

The Site object

List sites

Parameters

Returns

Create a site

Body

Returns

Retrieve a site

Parameters

Returns

Update a site

Parameters

Body

Returns

Archive a site

Parameters

Returns

Restore an archived site

Parameters

Returns

Connect a billing platform

Parameters

Body

Returns

Retrieve domain verification

Parameters

Returns

Start domain verification

Parameters

Body

Returns

Check domain verification now

Parameters

Returns

Re-sync Stripe settings

Parameters

Returns