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:
| Phase | Capability bits | Behavior |
|---|---|---|
| Off | both false | IP shape only (CONSUMER_IP_INVALID for reserved/private addresses). Sandbox keys are always this phase. |
| Monitor | consumerGeoMonitorEnabled | Full evaluation; request succeeds with additive geoWarning |
| Enforce | consumerGeoEnforcementEnabled | Default 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#
-
SKU territory (always) —
salesCountryCode/ previewcountryCodemust be in the publisher region country pack for that SKU (minus release exclusions). -
Catalog list price (always) —
expectedUnitPriceCentsmust match POST /orders/preview for the same country. -
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. -
Geo cross-check (when geo enforcement is on) — IP-derived country must equal
salesCountryCode. -
VPN / hosting block (when geo enforcement is on and anonymous-IP data is loaded) — VPN, hosting, Tor, and public proxy IPs are rejected.
-
Restricted jurisdiction (always) — some locations are not available for access or sale (LOCATION_BLOCKED on your API source IP;
COUNTRY_RESTRICTEDon the sales country or buyer IP). -
Checkout-page confirmation, per Content Owner (see Buyer verification levels). When
GET /allocations.consumerGeoAttestRequiredis true for a Content Owner (alsowhoami.capabilities.consumerGeoAttestRequiredseller-wide), callPOST /geo/attest, loadpixelUrlin the buyer browser, and sendconsumerGeoAttestIdon preview/hold/reserve/commit. Completing the pixel from your store server is refused at completion time (CONSUMER_GEO_ATTEST_INVALIDfromPOST /geo/attest/{attestId}/complete; the attest stays incomplete and a later order seesCONSUMER_IP_INVALID). An attest is usable for 10 minutes fromPOST /geo/attest(CONSUMER_GEO_ATTEST_EXPIREDafterwards) and covers one order (CONSUMER_GEO_ATTEST_CONSUMEDon 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 sameorderReferencemay reuse it. -
The Content Owner's geo-mismatch policy (always, whenever there is evidence) — each agreement states what happens when the declared
salesCountryCodeand the country the evidence points at disagree (whoami.geoPolicyByPublisher[].policy). The evidence is the country the checkout attest resolved, else the IP lookup of theconsumerIpthe 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): 422CONSUMER_GEO_MISMATCH_POLICY_REFUSEDon preview, hold and commit alike, withdetails.declaredCountry,details.evidencedCountryanddetails.evidenceSource(checkout_attestorip_lookup). Nothing is sold, so nothing is settled, and an attest sent with the refused order stays usable.warn: the sale proceeds with aCONSUMER_GEO_MISMATCHgeoWarning, 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.
level | What you send | Notes |
|---|---|---|
declared_ip | integrationOrderContext.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_attest | consumerIp and consumerGeoAttestId from the checkout pixel | The platform default. The pixel-attested IP outranks the declared one for geo checks and settlement evidence. |
checkout_attest_risk | As checkout_attest | The 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#
- Discover territory —
GET /products/{id}→releases[].allowedCountries;GET /regions→allowedCountriesper region code. - Availability first —
GET /availabilitywith the buyer's country at product-page time and hide the buy button when the SKU is not sellable there. - Preview —
POST /orders/previewwithcountryCodeand the real buyer IP at cart time. - Reserve / hold — send the same
countryCodeplusintegrationOrderContext.consumerIpbefore charging. Under enforcement, a missing IP returnsCONSUMER_IP_REQUIRED. On a production key, preview and hold refuse a missing buyer IP (noconsumerIpand noconsumerGeoAttestId) with the commit's own 422VALIDATION_FAILED, whatever the enforcement mode, becausePOST /orderswould. - Order — include both fields in
integrationOrderContext:
{
"expectedUnitPriceCents": 450000,
"integrationOrderContext": {
"schemaVersion": 1,
"salesCountryCode": "JP",
"consumerIp": "203.0.113.42",
"currencyCode": "JPY",
"salesPriceGrossMinor": 598000
}
}
- Capture the end-buyer public IP — see Which IP to send.
- Re-preview on
CATALOG_PRICE_MISMATCH,TERRITORY_*, orCONSUMER_GEO_MISMATCH. - Discover posture —
GET /whoami→consumerGeoEnforcementEnabled/consumerGeoMonitorEnabled. During monitor, treatgeoWarningin 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-IPon Cloudflare, or the first public address inX-Forwarded-Forbehind 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 with422 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#
| Code | HTTP | Meaning |
|---|---|---|
TERRITORY_NOT_ALLOWED_FOR_SKU | 422 | Country not in SKU region pack |
TERRITORY_EXCLUDED_FOR_RELEASE | 422 | Country blocked for this release |
SKU_REGION_UNRESOLVED | 422 | SKU has no territorial coverage configured |
FOOTPRINT_COUNTRY_NOT_DECLARED | 422 | Country missing from your selling footprint. See footprint-country-not-declared. |
TERRITORY_NOT_GRANTED | 422 | Country outside the territory your agreement grants. See territory-not-granted. |
REGION_LOCKED_FOR_CONTRACT | 422 | Content Owner locked this country under your agreement. See region-locked-for-contract. |
REGION_LOCKED_FOR_SKU | 422 | Content Owner locked this title in that country. See region-locked-for-sku. |
CONSUMER_GEO_MISMATCH_POLICY_REFUSED | 422 | Declared and evidenced countries disagree, and the agreement refuses that. See consumer-geo-mismatch-policy-refused. |
CONSUMER_IP_REQUIRED | 422 | Missing consumerIp (enforce mode; also at reserve/hold) |
CONSUMER_IP_INVALID | 422 | Private/reserved IP (always, including monitor/off) |
CONSUMER_GEO_MISMATCH | 422 | IP country ≠ salesCountryCode. Details include declaredCountry and detectedCountry (never the raw IP). |
CONSUMER_IP_HIGH_RISK | 422 | VPN/hosting/Tor/proxy detected — prompt the buyer to disable VPN |
CONSUMER_GEO_UNAVAILABLE | 503 | Geo data temporarily unavailable. Retry with the same Idempotency-Key after Retry-After. |
COUNTRY_RESTRICTED | 422 | Sales are not available for this location (platform restricted jurisdiction or catalog restricted country). |
CONSUMER_GEO_ATTEST_REQUIRED | 422 | This 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_EXPIRED | 422 | The confirmation is older than its 10-minute window (details.expiresAt). Mint a new one. |
CONSUMER_GEO_ATTEST_CONSUMED | 422 | The 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_INVALID | 422 | consumerGeoAttestId 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_HIGH | 422 | The 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_UNAVAILABLE | 503 | The required risk assessment could not be completed. Retry with the same Idempotency-Key and consumerGeoAttestId after Retry-After. See consumer-risk-unavailable. |
LOCATION_BLOCKED | 403 | Access 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 carriesactivation: { type, countries }wheretypeisworldwide,region_locked, orunknown(no unarchived batch metadata) andcountriesis the guaranteed ISO 3166-1 alpha-2 list (null when worldwide or unknown).GET /allocations— every row carries the sameactivationblock.POST /orders/preview—lines[].activationfor every line, plus the advisory warningACTIVATION_REGION_MISMATCHwhen yourcountryCodefalls outside a guaranteed set and the sale's policy iswarn.POST /orders,POST /keys/pull,POST /orders/{orderId}/fulfill— the success body carries the sameactivationblock 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:
| Policy | Preview warning | Transact paths (preview, hold, reserve, order, bulk, commit, pull, export) |
|---|---|---|
warn | ACTIVATION_REGION_MISMATCH | Not 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:
| Method | Path | Purpose |
|---|---|---|
GET | /api/seller/v1/regions | List 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
salesCountryCoderemains 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 matchingCONSUMER_*codes so integrators can test.