Checkbox Docs

Region API

The visitor's region from the IP address, for the two places where the cited laws differ by place and Checkbox varies the disclosure: Vermont (bold-face renewal terms, plans of a year or more) and the District of Columbia (a separate opt-in for free trials).

Looked up in memory on Checkbox's servers; IP addresses are never stored.

The VisitorRegion object

The requesting browser's region, from its IP address (not stored).

FieldTypeDescription
objectenumString representing the object's type. Always "visitor_region".
regionenumThe visitor's region from the IP address: "US-VT" (Vermont), "US-DC" (the District of Columbia), "other" (an address elsewhere) or "unknown" (no usable address: private, loopback or malformed). Only these two regions are told apart, from an offline table (DB-IP Lite, CC BY 4.0); a VPN, a mobile network or travel can place a visitor wrongly. One of US-VT, US-DC, other, unknown.
dc_trial_consentenumDC_TRIAL_CONSENT on this deployment: "geo" (default) = the D.C. free-trial consent only for visitors in D.C.; "all" = for every visitor of a D.C.-scoped free trial. One of geo, all.

Get the calling browser's region from its IP address

GET /v1/visitor-region

Used by <checkbox-disclosure> (Elements 1.6.0 by default; 1.6.1 and later only with extras="vt-dc"; Vermont / D.C. are not checked by default): in Vermont it shows the renewal terms of a plan of a year or more in bold and adds the separate consent checkbox; in the District of Columbia it adds the separate consent checkbox for a free trial. No key; CORS *; not cached. The IP address is looked up in memory and not stored.

No API key (public) · Operation getVisitorRegion

SDK: checkbox.visitorRegions.retrieve() (Node) · checkbox.visitor_regions.retrieve() (Python). MCP / agents: operation getVisitorRegion.

Returns

Returns a VisitorRegion object.

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

curl https://app.checkbox.site/v1/visitor-region
Response
{
  "object": "visitor_region",
  "region": "other",
  "dc_trial_consent": "geo"
}

Check whether a visitor needs a separate opt-in or bold terms

POST /v1/checks/region

For your server when it creates a Stripe Checkout Session (or renders its own checkout): pass the visitor's IP address (or region) and the plan. Returns whether a separate opt-in to the renewal applies to this visitor (add consent_collection: { terms_of_service: "required" } to the session when it is not null) and whether the renewal terms must be bold. Stateless; the IP address is not stored. Checkbox cannot see this per-visitor branch from one Checkout Session, so a session without consent_collection, where the Vermont or D.C. opt-in applies, stays for you to confirm in the checks. A Payment Link serves every visitor the same: keep consent_collection on it.

Scope checks:read · Operation checkRegion

SDK: checkbox.regions.check() (Node) · checkbox.regions.check() (Python). MCP / agents: operation checkRegion.

Body

FieldTypeDescription
ipstringThe visitor's IP address, as your server received it (IPv4 or IPv6). Not stored. Give ip or region.
regionstringThe visitor's region when you already know it (e.g. "US-DC", "DC", "US-VT"); otherwise pass ip.
interval requiredenumBilling interval of the plan. One of day, week, month, year.
interval_countintegerIntervals per billing period (default 1).
trial_daysintegerFree-trial days (0 or absent: no trial).
jurisdictionsenumWhere you sell: "all" (default) or state codes ("US-CA", "CA", "US-NY"; "US-FED" is always included).

Returns

Returns a RegionCheckResult object.

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

curl https://app.checkbox.site/v1/checks/region \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "interval": "month",
  "ip": "203.0.113.7",
  "trial_days": 14
}'
Response
{
  "object": "region_check",
  "region": "US-DC",
  "separate_opt_in": true,
  "bold_renewal_terms": false,
  "consent_collection": {
    "terms_of_service": "required"
  },
  "reasons": [
    "The District of Columbia asks for a separate opt-in to the renewal for free trials (D.C. Code § 28A-203(c)(2))."
  ],
  "dc_trial_consent": "geo",
  "note": ""
}

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.