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.
| Operation | Endpoint |
|---|---|
| Get the calling browser's region from its IP address | GET /v1/visitor-region |
| Check whether a visitor needs a separate opt-in or bold terms | POST /v1/checks/region |
The VisitorRegion object
The requesting browser's region, from its IP address (not stored).
| Field | Type | Description |
|---|---|---|
object | enum | String representing the object's type. Always "visitor_region". |
region | enum | The 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_consent | enum | DC_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-regionimport Checkbox from '@checkbox-site/node';
const checkbox = new Checkbox();
const visitorRegion = await checkbox.visitorRegions.retrieve();
console.log(visitorRegion);import os
from checkbox import Checkbox
checkbox = Checkbox()
visitor_region = checkbox.visitor_regions.retrieve()
print(visitor_region){
"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
| Field | Type | Description |
|---|---|---|
ip | string | The visitor's IP address, as your server received it (IPv4 or IPv6). Not stored. Give ip or region. |
region | string | The visitor's region when you already know it (e.g. "US-DC", "DC", "US-VT"); otherwise pass ip. |
interval required | enum | Billing interval of the plan. One of day, week, month, year. |
interval_count | integer | Intervals per billing period (default 1). |
trial_days | integer | Free-trial days (0 or absent: no trial). |
jurisdictions | enum | Where 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
}'import Checkbox from '@checkbox-site/node';
const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);
const region = await checkbox.regions.check({ interval: 'month', ip: '203.0.113.7', trial_days: 14 });
console.log(region);import os
from checkbox import Checkbox
checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])
region = checkbox.regions.check(interval="month", ip="203.0.113.7", trial_days=14)
print(region){
"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.