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, hide a block, block products, or redirect for selected countries.
2. Geo campaigns add new bars, popups, and embeds (announcement, email signup, free shipping, countdown, cross-sell, ticker, multi-announcement, Access Denied, and more).
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 campaigns in the GeoTailor screens inside admin. The dashboard shows storefront health and a setup checklist while you go live. You can leave items inactive while you test, then turn them active when you are happy. Priority tells GeoTailor which rule or campaign 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, v1.0.40+):

• Geo campaigns: announcement bars, email signup, promo popups, free shipping, countdowns, cross-sell, ticker, multi-announcement rotation, and Access Denied screens from guided wizards.
• Visual campaign builder: template gallery, split layouts, block reorder, styling presets, and mobile preview.
• Analytics & revenue: impressions, signups, and CTA clicks; attributed revenue when orders link to campaigns.
• Dashboard: welcome onboarding, setup checklist, storefront health (embed + last visitor geo check), and quota forecast.
• ESP sync: Klaviyo, Omnisend, and Mailchimp with country and market properties on signup leads.
• Shopify Markets: target rules and campaigns by Market handle; GeoTailor resolves each market to its country list.
• Scheduling, A/B rotation, page targeting & exit intent: on campaigns; never on checkout or thank-you pages.
• Product picker: Block product uses in-admin catalog search on every plan.
• Plans & billing: $9 / $15 / $24 per month (USD) or annual billing with 20% off. 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 Campaigns 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. Geo Campaigns

Geo campaigns are bars, popups, and embeds rendered by GeoTailor and targeted by country or Shopify Market. Choose a campaign type in the create wizard, then pick a display format (top bar, bottom bar, popup, full-width popup, embed, or cart drawer where supported).

Campaign types

• Announcement - regional promo or compliance message.
• Email signup - capture leads; sync to Klaviyo, Omnisend, or Mailchimp.
• Promo popup - offers and announcements with rich styling.
• Free shipping - progress bar toward a shipping threshold.
• Countdown - timed urgency bar or popup.
• Cross-sell - geo-targeted product recommendations.
• Ticker - scrolling announcement strip.
• Multi-announcement - rotate multiple messages in one bar.
• Access Denied - full-screen or bar experience when a region should not shop.

Market redirects and checkout Product Blocker remain under Geo Rules, not campaigns.

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, signups, CTA clicks, and attributed revenue 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.

Campaign 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; choose monthly or annual billing (annual saves 20%). 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.