Understanding Regions and Geographic Rules
The XYZ Age Verification plugin uses geographic rules to determine which visitors need to be verified. This guide explains how region matching works and how to plan your region configuration.
How Region Matching Works
When a visitor arrives at your site, Cloudflare provides two pieces of location information:
- Country code — a two-letter ISO 3166-1 code (e.g.,
US, DE, GB, AU)
- State/region code — a subdivision code (e.g.,
TX for Texas, BY for Bavaria)
The plugin sends these codes to the XYZ API, which checks them against your configured regions to determine what action to take.
Region Hierarchy
Regions are matched from most specific to least specific:
- Country + State — If you have a rule for
US-TX, it matches visitors from Texas specifically.
- Country only — If you have a rule for
US (no state), it matches all visitors from the United States.
- No match — If no rule matches, the visitor is allowed through without verification.
The most specific match wins. If you have both US (verify) and US-CA (block), a visitor from California will be blocked while a visitor from Texas will be verified.
Region Actions
Each region can be configured with one of three actions:
- Verify — the visitor must complete age verification to access the site
- Block — the visitor is completely blocked from the site (used for jurisdictions where you cannot legally operate)
- Allow — the visitor is explicitly allowed through without verification (useful to override a broader country rule for specific states)
Practical Examples
Example 1: Verify All US Visitors
Create a single region:
- Country:
US, State: (empty), Action: Verify
All visitors from the United States will be age-gated.
Example 2: US Verification with Texas Having a Higher Age Threshold
Create two regions:
- Country:
US, State: (empty), Action: Verify, Minimum Age: 18
- Country:
US, State: TX, Action: Verify, Minimum Age: 21
Visitors from Texas will require Tier 2 verification (government ID) to confirm they are 21 or older. Visitors from other US states only need to pass the standard Tier 1 check.
Example 3: European Compliance
Create individual regions for countries with age verification requirements:
- Country:
GB, Action: Verify (UK Online Safety Act)
- Country:
DE, Action: Verify
- Country:
FR, Action: Verify
Example 4: Block a Specific Jurisdiction
If regulations prohibit you from operating in a region:
- Country:
US, State: UT, Action: Block
Visitors from Utah will see a block message instead of your site content.
Example 5: Allow a State Exception
If you verify all of the US but want to exempt a state:
- Country:
US, Action: Verify
- Country:
US, State: PR, Action: Allow
Visitors from Puerto Rico bypass verification while all other US states require it.
Country and State Codes
Country codes follow the ISO 3166-1 alpha-2 standard. Some common codes:
US — United StatesGB — United KingdomDE — GermanyFR — FranceAU — AustraliaCA — CanadaJP — Japan
State/region codes follow ISO 3166-2 subdivision codes (the part after the hyphen). For the US, these are the standard two-letter state abbreviations (TX, CA, NY, etc.). For other countries, consult the ISO 3166-2 tables for the specific country.
Free Plan Region Limit
The free plan supports up to 15 regions. This is more than sufficient for most sites — you only need regions for jurisdictions that require age verification. If you need more than 15 regions, consider upgrading to the Pro plan.
How Regions Interact with Verification Tiers
The region configuration determines which verification tier is used:
- Requires ID Verification = No — Tier 1 only (face liveness). The system may still escalate to Tier 2 if the liveness result is inconclusive.
- Requires ID Verification = Yes — Tier 2 required (liveness + government ID).
- Minimum Age ≠ 18 — Tier 2 is automatically required regardless of the "Requires ID" setting, because date of birth extraction from a document is needed to verify a non-standard age threshold.
Next Steps
