Territory enforcement

Sales-country and geo rules that return hard 4xx at preview and commit.

Avrix enforces regional SKU territory and declared sales country on production API-key orders before keys are pulled. Buyer IP geo / VPN verification defaults to enforce on production keys. Sandbox keys stay off. Discover the live posture via GET /whoami:

PhaseCapability bitsBehavior
Offboth falseIP shape only (CONSUMER_IP_INVALID for reserved/private addresses). Sandbox keys are always this phase.
MonitorconsumerGeoMonitorEnabledFull evaluation; request succeeds with additive geoWarning
EnforceconsumerGeoEnforcementEnabledDefault for production keys when geo data is loaded. Mismatches and high-risk IPs return 422; geo data outage returns 503

Reserve and hold now run the same territory and geo gates as preview (API-model allocations) so a region-mismatched buyer fails before payment.

Whatever the phase, the country the gate resolved from the buyer IP is persisted next to the declared salesCountryCode on every API-model sale and pull row: GET /finance/api-sales, GET /finance/statements lines and GET /transactions return detectedCountryCode, countryMismatch and warnings: ["COUNTRY_MISMATCH"], and the api-sales CSV carries customerRegionCode, detectedCountryCode, warning columns. In monitor mode this is the fraud signal for a sale that went through with a geoWarning; the raw IP is never returned.

Example#

curl -s -X GET "https://api.avrix.io/api/seller/v1/availability?skuCode=SANDBOX-ALWAYS-001&quantity=1&country=US" \
  -H "Authorization: Bearer $AVRIX_API_KEY"

Market region locks as VPN-proof only when capabilities.consumerGeoEnforcementEnabled is true. Territory allowlists and catalog list-price checks are always enforced on production keys. Sandbox keys never enable IP-country or VPN/hosting checks.

Defense layers#

  1. SKU territory (always) — salesCountryCode / preview countryCode must be in the publisher region country pack for that SKU (minus release exclusions).

  2. Catalog list price (always) — expectedUnitPriceCents must match POST /orders/preview for the same country.

  3. Buyer IP shape (when geo enforcement is on) — production keys require integrationOrderContext.consumerIp (public routable IPv4/6); private/reserved IPs are always rejected when supplied.

  4. Geo cross-check (when geo enforcement is on) — IP-derived country must equal salesCountryCode.

  5. VPN / hosting block (when geo enforcement is on and anonymous-IP data is loaded) — VPN, hosting, Tor, and public proxy IPs are rejected.

  6. Restricted jurisdiction (always) — some locations are not available for access or sale (LOCATION_BLOCKED on your API source IP; COUNTRY_RESTRICTED on the sales country or buyer IP).

  7. Checkout-page confirmation, per Content Owner (see Buyer verification levels). When GET /allocations.consumerGeoAttestRequired is true for a Content Owner (also whoami.capabilities.consumerGeoAttestRequired seller-wide), call POST /geo/attest, load pixelUrl in the buyer browser, and send consumerGeoAttestId on preview/hold/reserve/commit. Completing the pixel from your store server is refused at completion time (CONSUMER_GEO_ATTEST_INVALID from POST /geo/attest/{attestId}/complete; the attest stays incomplete and a later order sees CONSUMER_IP_INVALID). An attest is usable for 10 minutes from POST /geo/attest (CONSUMER_GEO_ATTEST_EXPIRED afterwards) and covers one order (CONSUMER_GEO_ATTEST_CONSUMED on another). Validation order: the confirmation is checked after the order admission (sale country, price, footprint, currency, channel, region locks) and before the buyer-network verdict, on preview, hold and commit alike, so a missing or expired confirmation never hides a refusal you can fix in the request. It is spent only when a commit has cleared every other gate and is about to deliver the key: a commit refused for any reason leaves it usable, and a retry of the same orderReference may reuse it.

  8. The Content Owner's geo-mismatch policy (always, whenever there is evidence) — each agreement states what happens when the declared salesCountryCode and the country the evidence points at disagree (whoami.geoPolicyByPublisher[].policy). The evidence is the country the checkout attest resolved, else the IP lookup of the consumerIp the sale carries. This runs whether or not consumer geo enforcement is on: enforcement is the platform's own rule (does Avrix refuse an IP / country disagreement?), the policy is the agreement's.

    • refuse (also the reading of an agreement that states none, policyStated: false): 422 CONSUMER_GEO_MISMATCH_POLICY_REFUSED on preview, hold and commit alike, with details.declaredCountry, details.evidencedCountry and details.evidenceSource (checkout_attest or ip_lookup). Nothing is sold, so nothing is settled, and an attest sent with the refused order stays usable.
    • warn: the sale proceeds with a CONSUMER_GEO_MISMATCH geoWarning, and settles at the lower evidence rank.
    • settle_at_evidence: with enforcement on, the sale is re-priced at the higher of the two territories' SRPs; with it off, it proceeds with the warning (re-pricing needs preview and hold to quote the same price, which they only do under enforcement). Only a country disagreement is judged here. An anonymised connection is refused by the platform check (layer 5) when enforcement is on; the policy does not refuse it on its own.

When geo enforcement is off, a supplied malformed IP is still rejected. Sandbox / non-production keys never enable IP-country or VPN/hosting checks, and never require checkout-page confirmation.

Buyer verification levels#

Each Content Owner chooses how buyers are verified at checkout on their connection with you. The level is disclosed per Content Owner in GET /whoami → buyerVerificationByPublisher[] (publisherCompanyId, level, riskAction, note) and on every GET /allocations row as buyerVerification { level, riskAction }; consumerGeoAttestRequired is derived from it. Levels apply to production keys only — sandbox keys never require checkout-page confirmation.

levelWhat you sendNotes
declared_ipintegrationOrderContext.consumerIp (the buyer's public IP)No checkout pixel. Layers 3–6 and the agreement's geo policy still apply to the declared IP. A production key's own calling address, or one on its IP allowlist, is refused as CONSUMER_IP_INVALID.
checkout_attestconsumerIp and consumerGeoAttestId from the checkout pixelThe platform default. The pixel-attested IP outranks the declared one for geo checks and settlement evidence.
checkout_attest_riskAs checkout_attestThe confirmed checkout is also risk-scored (once per confirmation; preview, hold and commit share the result). At or above the Content Owner's threshold: riskAction: refuse → 422 CONSUMER_RISK_HIGH, riskAction: warn → 200 with riskWarning. A confirmation that cannot be scored: refuse → 503 CONSUMER_RISK_UNAVAILABLE + Retry-After, warn → 200 with riskWarning. The score itself is never returned. Live only while whoami.capabilities.buyerRiskScoringEnabled is true; otherwise the level behaves as checkout_attest.

A Content Owner can change the level at any time; re-read GET /whoami when you receive CONSUMER_GEO_ATTEST_REQUIRED from a connection that did not require the pixel before, and prefer sending the pixel on every production checkout so a change never interrupts sales.

Read a confirmation back. GET /geo/attest/{attestId} with the key that minted it answers its status (pending, completed, consumed, expired, or store_server when the completion came from your store's server and was refused), expiresAt, completedAt, consumedAt and the consumedOrderReference that spent it, so your checkout can wait for the buyer's browser before it sends the order instead of guessing. No buyer data is returned. Another key, even of your own company, gets 404.

Rehearse it in sandbox. The sandbox Content Owner does not require the confirmation, so send X-Avrix-Sandbox-Simulate: buyer_verification_required with contract date 2026-12-01 on POST /orders/preview, /orders/hold, /orders/reserve, /orders/commit, POST /orders, /orders/bulk or /keys/pull: that call then behaves as if the confirmation were required and answers 422 CONSUMER_GEO_ATTEST_REQUIRED until you send a completed consumerGeoAttestId. Production keys ignore the header. See Sandbox.

Partner integration checklist#

  1. Discover territory — GET /products/{id} → releases[].allowedCountries; GET /regions → allowedCountries per region code.
  2. Availability first — GET /availability with the buyer's country at product-page time and hide the buy button when the SKU is not sellable there.
  3. Preview — POST /orders/preview with countryCode and the real buyer IP at cart time.
  4. Reserve / hold — send the same countryCode plus integrationOrderContext.consumerIp before charging. Under enforcement, a missing IP returns CONSUMER_IP_REQUIRED. On a production key, preview and hold refuse a missing buyer IP (no consumerIp and no consumerGeoAttestId) with the commit's own 422 VALIDATION_FAILED, whatever the enforcement mode, because POST /orders would.
  5. Order — include both fields in integrationOrderContext:
JSON
{
  "expectedUnitPriceCents": 450000,
  "integrationOrderContext": {
    "schemaVersion": 1,
    "salesCountryCode": "JP",
    "consumerIp": "203.0.113.42",
    "currencyCode": "JPY",
    "salesPriceGrossMinor": 598000
  }
}
  1. Capture the end-buyer public IP — see Which IP to send.
  2. Re-preview on CATALOG_PRICE_MISMATCH, TERRITORY_*, or CONSUMER_GEO_MISMATCH.
  3. Discover posture — GET /whoami → consumerGeoEnforcementEnabled / consumerGeoMonitorEnabled. During monitor, treat geoWarning in 200 responses as a would-be 422.

Which IP to send#

Send the end-buyer's public IPv4 or IPv6, not your store backend's egress address.

  • Read it from your CDN or load-balancer headers after you trust the hop (for example CF-Connecting-IP on Cloudflare, or the first public address in X-Forwarded-For behind nginx).
  • Do not forward an unverified client-supplied header.
  • A private, loopback, link-local or carrier-NAT address (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8, 169.254.0.0/16, 100.64.0.0/10, ::1, fc00::/7, fe80::/10) is refused when the request is parsed with 422 CONSUMER_IP_INVALID, on every surface — it is your network, never the buyer's.
  • Sending your server or NAT egress IP will usually trip CONSUMER_IP_HIGH_RISK (hosting range). Prompt the buyer to disable VPN when you receive that code.

Sandbox keys can exercise the same codes without geo data using 203.0.113.66 (CONSUMER_GEO_MISMATCH), 203.0.113.99 (CONSUMER_IP_HIGH_RISK) and 203.0.113.77 (CONSUMER_RISK_HIGH). See Sandbox.

Error codes#

CodeHTTPMeaning
TERRITORY_NOT_ALLOWED_FOR_SKU422Country not in SKU region pack
TERRITORY_EXCLUDED_FOR_RELEASE422Country blocked for this release
SKU_REGION_UNRESOLVED422SKU has no territorial coverage configured
FOOTPRINT_COUNTRY_NOT_DECLARED422Country missing from your selling footprint. See footprint-country-not-declared.
TERRITORY_NOT_GRANTED422Country outside the territory your agreement grants. See territory-not-granted.
REGION_LOCKED_FOR_CONTRACT422Content Owner locked this country under your agreement. See region-locked-for-contract.
REGION_LOCKED_FOR_SKU422Content Owner locked this title in that country. See region-locked-for-sku.
CONSUMER_GEO_MISMATCH_POLICY_REFUSED422Declared and evidenced countries disagree, and the agreement refuses that. See consumer-geo-mismatch-policy-refused.
CONSUMER_IP_REQUIRED422Missing consumerIp (enforce mode; also at reserve/hold)
CONSUMER_IP_INVALID422Private/reserved IP (always, including monitor/off)
CONSUMER_GEO_MISMATCH422IP country ≠ salesCountryCode. Details include declaredCountry and detectedCountry (never the raw IP).
CONSUMER_IP_HIGH_RISK422VPN/hosting/Tor/proxy detected — prompt the buyer to disable VPN
CONSUMER_GEO_UNAVAILABLE503Geo data temporarily unavailable. Retry with the same Idempotency-Key after Retry-After.
COUNTRY_RESTRICTED422Sales are not available for this location (platform restricted jurisdiction or catalog restricted country).
CONSUMER_GEO_ATTEST_REQUIRED422This catalog requires confirming the buyer’s network from the checkout page. Call POST /geo/attest, load pixelUrl in the buyer browser, then retry with consumerGeoAttestId.
CONSUMER_GEO_ATTEST_EXPIRED422The confirmation is older than its 10-minute window (details.expiresAt). Mint a new one.
CONSUMER_GEO_ATTEST_CONSUMED422The confirmation was spent on another order (details.consumedOrderReference). Mint a new one for this order; a retry of the same orderReference may reuse it.
CONSUMER_GEO_ATTEST_INVALID422consumerGeoAttestId is unknown, belongs to another key or account, or the pixel was completed from the store server. Mint it with the ordering key; complete it in the buyer's browser.
CONSUMER_RISK_HIGH422The Content Owner scores confirmed checkouts and this one reached their threshold (checkout_attest_risk, riskAction: refuse). Do not deliver. See consumer-risk-high.
CONSUMER_RISK_UNAVAILABLE503The required risk assessment could not be completed. Retry with the same Idempotency-Key and consumerGeoAttestId after Retry-After. See consumer-risk-unavailable.
LOCATION_BLOCKED403Access is not available from the current location (authenticated API source IP).

Activation territory (where the key redeems)#

Sale territory answers "may I sell here?"; activation territory answers "will the delivered key actually redeem there?" — vendors can stock region-locked keys for a SKU whose sale territory is broader. The API exposes the guaranteed activation set per SKU, computed across all inventory batches (a mixed pool of worldwide and region-locked batches reports the most restrictive intersection, because your pull may be served from any batch):

  • GET /products/{productId} — each SKU carries activation: { type, countries } where type is worldwide, region_locked, or unknown (no unarchived batch metadata) and countries is the guaranteed ISO 3166-1 alpha-2 list (null when worldwide or unknown).
  • GET /allocations — every row carries the same activation block.
  • POST /orders/preview — lines[].activation for every line, plus the advisory warning ACTIVATION_REGION_MISMATCH when your countryCode falls outside a guaranteed set and the sale's policy is warn.
  • POST /orders, POST /keys/pull, POST /orders/{orderId}/fulfill — the success body carries the same activation block next to the delivered keys (also on pre-order acceptances), so "activates in" can be shown at delivery time without a second lookup. It is resolved after the pull commits; if inventory metadata cannot be read at that moment the field degrades to { "type": "unknown", "countries": null } rather than failing a delivered order.

activationPolicy is also on GET /integration/status. Modes:

PolicyPreview warningTransact paths (preview, hold, reserve, order, bulk, commit, pull, export)
warnACTIVATION_REGION_MISMATCHNot blocked
enforce_known (default since 2026-09-24)—422 ACTIVATION_REGION_MISMATCH for a known locked-set miss
enforce_strict—Also 422 ACTIVATION_REGION_UNKNOWN when coverage is absent

Missing countryCode is never an activation 422 (sale territory remains a separate gate).

The policy is decided per sale. enforce_known is the platform default. A Content Owner may accept the redemption risk for its own SKUs, and its sales then only warn. A seller that opted into enforcement (whoami.capabilities.activationEnforceOptIn) is always enforced. SANDBOX-ACTIVATION-LOCK-001 is locked to Germany: order it with countryCode: "US" to see the 422, and with "DE" to see it pass.

Region catalog#

Discover countries and region packs the platform exposes:

MethodPathPurpose
GET/api/seller/v1/regionsList regions / country packs
GET/api/seller/v1/regions/{code}Detail for one region code

Use these to validate buyer-country pickers and map storefront locales to ISO country codes before preview. Territory allow/deny for a SKU still comes from preview / commit errors and allocation readiness — the regions catalog is reference data, not a sellability gate by itself.

Limits#

  • Declared salesCountryCode remains authoritative for territory allowlists even when geo is off.
  • When anonymous-IP data is unavailable, VPN/hosting blocks are skipped but country cross-check still runs when country geo data is present.
  • Sandbox / non-production keys never enable IP-country or VPN/hosting layers and never call the risk provider. Shared sandbox catalog magic IPs (203.0.113.66, 203.0.113.99, 203.0.113.77) still return the matching CONSUMER_* codes so integrators can test.

What links here

Published guides that link to this page.

Search docs

Search documentation…