# 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](#getVisitorRegion) | `GET /v1/visitor-region` |
| [Check whether a visitor needs a separate opt-in or bold terms](#checkRegion) | `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 {#getVisitorRegion}

`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](https://checkbox.site/docs/api/region#the-visitorregion-object) object.

Errors use the [standard envelope](https://checkbox.site/docs/api/errors) with a stable `code` and, where useful, `next_action`.

```curl
curl https://app.checkbox.site/v1/visitor-region
```
```node
import Checkbox from '@checkbox-site/node';

const checkbox = new Checkbox();

const visitorRegion = await checkbox.visitorRegions.retrieve();
console.log(visitorRegion);
```
```python
import os
from checkbox import Checkbox

checkbox = Checkbox()

visitor_region = checkbox.visitor_regions.retrieve()
print(visitor_region)
```

```json title="Response"
{
  "object": "visitor_region",
  "region": "other",
  "dc_trial_consent": "geo"
}
```

## Check whether a visitor needs a separate opt-in or bold terms {#checkRegion}

`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](https://checkbox.site/docs/api/errors) with a stable `code` and, where useful, `next_action`.

```curl
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
}'
```
```node
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);
```
```python
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)
```

```json title="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": ""
}
```
