GeoTailor Shopify App Documentation

Overview for merchants

GeoTailor helps you run one Shopify storefront while still speaking clearly to customers in different parts of the world. You work from the same Shopify admin you already use. The app does not replace your theme; it layers on top of it with rules you define.

Country detection is based on the visitor's connection (IP-based lookup to a country code). It is not the same as a logged-in customer shipping address unless you add workflows that use account data. For most merchants, think of it as what a typical shopper from France or Japan would see on a first visit.

The three building blocks

1. Geo rules change existing page content: show a bar, swap headline text, or hide a block for selected countries.
2. Geo popups add new overlays (offers, notices, consent-style messages) with templates and controls for who sees them and when.
3. Geo app blocks (optional) are sections you drop into the theme editor, such as trust badges or FAQs, each with its own country targeting.

Day-to-day workflow

You install the app, enable the app embed once, then create rules or popups in the GeoTailor screens inside admin. You can leave items inactive while you test, then turn them active when you are happy. Priority tells GeoTailor which rule wins when more than one matches the same visitor.

Skills you might use

Many tasks are point and click. If you want to replace a specific sentence in your theme, the app will ask for a CSS selector. That sounds technical, but it usually means “right-click the text in your browser, Inspect, and copy a stable class name.” The docs below walk through it.

Plans and limits

Every plan includes all GeoTailor features (rules, popups, product blocker, redirects, Markets, A/B popups, analytics, and more). Plans differ only by your monthly geo request quota (storefront visitor IP lookups). You manage paid plans through Shopify billing on the Plans page. Downgrading lowers your quota only. Nothing is removed from your setup.

What’s new

Recent updates (2026):

• Shopify Markets: target rules and popups by Market handle; GeoTailor resolves each market to its country list on the storefront. Requires read_markets (re-authorize after enabling Markets).
• Popup template gallery: browse free and premium templates from Popup Templates; apply a template into the popup editor.
• Popup analytics: dashboard card for impressions, dismissals, and primary CTA clicks.
• Popup scheduling: optional UTC start and end datetimes per popup.
• A/B rotation: group popups by rotation ID with weighted variants; one variant per visitor session.
• Popups list: compact condition column (countries or Markets) on Rules and Geo Popups tables.
• Split popup layout: two-column promos with side image, ratio, and vertical alignment; improved content padding in split previews.
• Page targeting & exit intent: limit popups by page type or path; optional desktop exit intent. Never on checkout or thank-you pages.
• Product picker: Block product uses in-admin catalog search and multi-select.
• Plans & billing: $9 / $15 / $24 per month (USD, 30-day cycle). All features on every tier. Quotas: up to 5k, 50k, 100k, or unlimited visitors/mo.

1. Installation

GeoTailor installs as an embedded Shopify admin app and does not require manual code edits during onboarding.

1. Install GeoTailor from the Shopify App Store listing.
2. Approve requested permissions in the OAuth flow.
3. You will be redirected to the embedded GeoTailor dashboard in Shopify admin.
4. Open Rules or Geo popups to create your first targeting setup.

Permissions (high level)

GeoTailor requests the minimum access needed for personalization and compliance:

• read_products: lets the admin search and pick products when you use the Block product action (read-only; no product writes).
• read_markets: reads your Shopify Markets catalog for Market targeting in rules and popups.
• read_themes: supports theme-related integration where required by Shopify.
• read_validations / write_validations: install and update the checkout validation that enforces product blocking at cart and checkout.

2. Enable App Embed

The app embed is required for storefront execution of your geo targeting rules and popups.

1. Open Shopify Admin → Online Store → Themes → Customize.
2. Open App embeds from the left sidebar.
3. Toggle GeoTailor Script ON and click Save.
4. Preview the storefront in incognito once to confirm the script is active.

3. Create Geo Rules

Rules target visitors by country and then execute one or more actions in priority order.

• Condition: select country operator and values. The Rules list shows a compact Condition column for quick scanning.
• Actions: Show banner, replace text, hide element, block product, and redirect URL.
• Status: Active/Inactive toggle for safe rollout.
• Priority: Control execution order for matching rules (custom 1–1000).

Recommended workflow

1. Start with one country and one action.
2. Use browser Inspect to capture a stable selector.
3. Save as Inactive, verify in preview, then activate.
4. Add extra actions only after the first action is confirmed stable.

Best practices

• Prefer class-based selectors over fragile nth-child selectors.
• Use clear rule names (for example: US Hero Copy).
• Keep a fallback message for countries with no specific rule.

4. Advanced Rule Actions

GeoTailor includes these rule actions on every plan:

• Block products: block selected catalog products from being purchased for targeted countries/regions, using the in-app product picker.
• Redirect URL: send visitors from selected countries to another URL (for regional storefronts, market-specific pages, or compliance paths).

Product Blocker behavior

• In the rule editor, open the product picker: search your catalog, paginate results, and select one or more products to block (no need to copy product IDs by hand).
• Selected products are stored as IDs on the rule; GeoTailor blocks add-to-cart and checkout for matched visitor locations.
• The blocker is purchase-focused and does not depend on theme-specific product hiding selectors.
• Show a clear shopper-facing message so customers understand why checkout is restricted.

Geo redirection best practices

• Use absolute HTTPS URLs.
• Avoid redirect loops (do not redirect to the same page or a URL that immediately redirects back).
• Test in incognito for each target country segment before enabling broadly.

5. Create Geo Popups

Geo popups are standalone overlays rendered by GeoTailor and targeted by country conditions. The Geo Popups list shows name, position, condition, priority, and status for each popup.

Content & layout

• Choose a template or start from scratch; premium templates are available on every plan.
• Layout: single column (default) or split: image column beside headline, message, and buttons.
• Split options: image URL (Shopify Files or CDN), split ratio (image : text), and content vertical position (top, center, bottom).
• Content order: drag blocks (headline, message, primary/secondary buttons) to reorder. Space between blocks (px) is available on every plan (0–48 px, default 16).
• Style position (center, corners, etc.), text alignment, colors, background image, and CTA labels.

Who sees it & when

• Country / Market condition: country lists, Shopify Market handles, and advanced exclusion (not_in).
• Scheduling: optional UTC start and end datetimes.
• Analytics: impressions, dismissals, and CTA clicks on the dashboard.
• A/B rotation: rotation group ID and variant weight; one popup per group per visitor session.
• Show delay: wait before the popup appears.
• Exit intent: show when the shopper moves to leave the tab (desktop); mobile relies on delay.
• Pages: all pages, home only, product, collection, or custom paths (prefix or exact). Popups never run on checkout or thank-you pages.
• Priority: lower number runs first when multiple popups match.
• Secondary CTA: optional second button.

Popup launch checklist

• Popup title and body are short and region-specific.
• CTA URL is valid and lands on a relevant collection/product.
• Split-layout images use a stable HTTPS or Shopify CDN URL; preview matches storefront.
• Dismiss behavior and auto-hide settings are intentional.
• Mobile preview is reviewed before enabling.

6. Plan Capabilities

All plans include the same features. Tiers differ by monthly visitor allowance:

• Free ($0): Up to 5k visitors / month.
• Starter ($9/mo): Up to 50k visitors / month.
• Growth ($15/mo): Up to 100k visitors / month.
• Scale ($24/mo): Unlimited visitors per month.

7. Plans & billing

Paid plans are managed from the embedded app’s Plans page and billed through Shopify (same subscription experience as other App Store apps).

• Start or change a plan from Plans; Shopify may show a confirmation step before the new subscription is active.
• Pricing labels follow what Shopify displays for your store at checkout time.
• Downgrading lowers your monthly geo request quota only. Your rules, popups, and settings stay in place.

8. Geo App Blocks

GeoTailor app blocks let merchants add localized content directly from the Theme Editor:

• GeoSection - flexible rich text or custom HTML region.
• Geo Shipping Promise - delivery/returns messaging by location.
• Geo Trust Badges - icon + proof highlights for specific countries.
• Geo Promo Cards - regional campaign cards and links.
• Geo Country FAQ - country-specific Q&A accordion.
• Geo Countdown - localized timed campaign banner.

All blocks use the same country targeting model as rules and popups.

9. CSS Selector Tips

Selectors determine what text or element your rule will modify.

1. Open your storefront in Chrome.
2. Right click target text/element → Inspect.
3. Copy a stable class or selector (for example .announcement-bar__message).
4. Use that selector in GeoTailor rule actions.

What to avoid

• Random auto-generated class names that change on deploy.
• Very deep selectors tied to current DOM nesting.
• Selectors that match multiple unrelated elements.

10. Developer Hooks

Listen to GeoTailor readiness after rule payload evaluation:

document.addEventListener("geotailor:ready", (e) => {
  console.log(e.detail.countryCode, e.detail.rules, e.detail.popups);
});

Payload fields: countryCode, rules, popups.