Country Shield
Contact supportInstall on Shopify

How Country Shield makes a storefront decision.

Country Shield separates merchant configuration, storefront execution, and operational visibility so each part can be understood and tested independently.

1. Shopify authorizes the app

The merchant installs Country Shield through Shopify. OAuth grants the approved Admin API scopes, and Country Shield stores the rotating offline access and refresh tokens encrypted at rest.

Public apps use expiring offline tokens. Country Shield refreshes them before expiry and records authentication failures for operators.

2. The merchant saves a policy

The embedded app collects rule mode, countries, paid location or network rules, storefront scope, and action. The server sanitizes the ruleset and removes anything the current plan does not allow before saving it.

  1. Choose denylist or allowlist mode.
  2. Add countries and, when entitled, regions or network rules.
  3. Select block, redirect, or challenge.
  4. Choose whole store or checkout-only scope.
  5. Save and run a decision preview.

3. Shopify loads the theme app extension

The merchant enables Country Shield under App embeds in the Shopify theme editor. The extension loads a small storefront script from Shopify's CDN and calls the Country Shield decision endpoint with the permanent shop domain and requested path.

Saving rules does not activate storefront protection by itself. The embedded app keeps the status at “Not active yet” until the merchant confirms the theme app extension step.

4. Country Shield evaluates the request

The backend resolves the client IP from the trusted proxy path, looks up available geographic and network signals, checks verified crawler status, loads the merchant policy, and evaluates it in a predictable order.

  1. Verified search bots are allowed first when bot protection is enabled.
  2. Checkout-only scope allows non-checkout paths.
  3. Allowlist or denylist country and region logic runs.
  4. Plan-entitled ASN, IP, or anonymous traffic rules run when data is available.
  5. The configured action and public response are returned.

5. The storefront enforces the result

An allow result releases the page. A redirect navigates to the merchant URL. Block and challenge results display a full-screen interstitial so the visitor cannot continue interacting with the storefront behind it.

Soft mode

Allowed visitors see the page normally while Country Shield acts only on a deny result.

Strict mode

The page remains hidden until an allow result or a short fail-open timeout. This gives stronger visual enforcement with a small perceived-loading tradeoff.

6. Merchants and operators see the outcome

Merchant analytics use aggregate counts and never expose individual visitor profiles. The protected operations console shows installed stores, setup status, database availability, billing configuration, token health, and open Shopify API errors.

Premium stores may also sync supported rules to Cloudflare. Edge sync errors are recorded without preventing the merchant from saving the core Country Shield policy.

Open setup guideExplore product controls