> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.hoppyapps.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 🌍 How to Run Region-Specific Upsell Offers

Want to show different upsell offers to customers in different countries? 🌎

That’s exactly what **Geolocation targeting** in Hoppy Upsell & Cross Sell is designed for.

With this feature, you can:

* 🎯 Show an upsell only to shoppers browsing from specific countries  
* 🎁 Run location-relevant offers, like a free gift just for US customers  
* 🚫 Hide offers in regions where they don’t make sense (shipping limits, local pricing, regional promotions)

This helps keep your offers relevant — customers only see deals that actually apply to them, which means better conversions and fewer confusing moments at checkout ✨

---

# **📍 How Geolocation Targeting Works**

Every upsell setup includes a **Geolocation targeting** option inside the **Placement** tab with two choices:

* **All world** → The upsell shows for everyone, everywhere (this is the default)  
* **Specific countries** → The upsell only shows for shoppers browsing from the countries you select

On the storefront, the app detects the visitor’s country using Shopify’s built-in country detection and checks it against your selected list before showing the upsell.

ℹ️ Targeting works at the **country level**. Selecting individual states, provinces, or cities within a country is not supported.

---

# **🛠️ Example Setup Used in This Documentation**

In this guide, we’ll configure the following campaign:

* 🎁 A **free gift offer** (a $0 gift product) shown on the **Cart Page**  
* 🇺🇸 Visible **only to customers browsing from the United States**

The same steps work for any placement type (Product Page, Cart Page, Cart Drawer, or Custom Position) and for any offer — just swap in your own products and countries ⚙️

---

# **✅ Before You Begin**

Make sure the following are ready:

* The **Upsell Cross-Sell Slider** app embed is enabled in your theme (**Shopify Admin → Online Store → Themes → Edit theme → App Embeds → toggle it ON → Save**)  
* The product you want to offer already exists in your store (for a free gift, create a product priced at **$0** and make sure it’s in stock)

💡 If you’ve already created the upsell you want to restrict, you can skip straight to **Step 3** and just update its Geolocation targeting.

---

# **⚙️ Step 1 — Create a New Upsell**

Open the **Hoppy Upsell & Cross Sell** app.

Then:

→ Click **Create new upsell**

→ Select the placement where the offer should appear — in this example, **Cart Page**

Once selected, the setup page opens automatically with three tabs: **Content**, **Design**, and **Placement**.

---

# **🎯 Step 2 — Set Up the Offer in the Content Tab**

Inside the **Content** tab, configure what customers will actually see:

* **Upsell Name** → An internal name only you can see, e.g. `US Free Gift – Cart Page` 💡 Clear naming makes region-specific campaigns much easier to manage when you run several of them.  
* **Select upsell products** → Choose **Upsell Specific Products**, then click **Select Products** and pick your gift product  
* **Upsell Title** → The headline customers see, e.g. `You've unlocked a free gift! 🎁`  
* **Button Text (Before adding to cart)** → Something action-oriented like `Claim Free Gift`

You can adjust the look and feel in the **Design** tab if you like — see Design & Styling for details. The defaults work fine to get started.

---

# **🌍 Step 3 — Restrict the Offer to Specific Countries**

Now the important part. Open the **Placement** tab and scroll to the **Geolocation targeting** card.

Then:

→ Select the **Specific countries** radio button

→ Click **Select countries** to open the Country Selection popup

Inside the popup you can:

* 🔍 **Search** for a country by name  
* ☑️ **Check** the countries you want — each is listed as country code \+ name, so for this example select **US United States**  
* Use **Select All** to quickly check or uncheck the entire list

Click **Select** at the bottom of the popup (next to the **Selected: N** counter) to confirm and close it. Your chosen countries now appear as a list inside the **Geolocation targeting** card, so you can double-check them at a glance.

⚠️ If you choose **Specific countries** but don’t select at least one country, you’ll see a **“Select at least one country.”** error when saving. Always make sure at least one country is checked.

---

# **💾 Step 4 — Save and Publish**

When everything looks good:

→ Click **Save** in the save bar at the top of the page

→ Click **Publish** to make the upsell live on your storefront

Your region-specific offer is now active 🎉

---

# **🧪 Testing Your Region-Specific Offer**

Geolocation behaves differently from most settings, so keep these points in mind when testing:

* **The in-app preview doesn’t reflect location.** The Desktop/Mobile preview next to the setup page shows your design and content, but it doesn’t simulate country detection. Don’t worry if the offer appears there regardless of your targeting.  
* **Test on the live storefront.** Open your store the way a customer would and check whether the upsell appears based on your location.  
* **Use a VPN to test other countries.** Since the app detects the visitor’s country automatically, a VPN set to the United States lets you see the offer exactly as a US customer would. Switch the VPN to another country to confirm the offer stays hidden there.  
* **Detection is cached per browser session.** The detected country is remembered for the duration of the browser tab session. If you switch VPN locations while testing, close the tab (or open a new incognito window) so the country is detected again.  
* **Shopify theme preview works normally.** You can safely test inside the theme editor’s preview mode — country detection runs there the same way as on the live storefront.

---

# **📌 Important Notes**

* **Geolocation stacks with your other targeting rules.** The upsell only shows when *all* conditions pass — page rules, customer conditions, scheduling, *and* location. For a full walkthrough of the remaining options on the Placement tab (page include/exclude rules, customer display conditions, time-on-site targeting, and more), see 🎯 Advanced Targeting Options for Upsell & Cross Sell.  
* **Switching back to All world clears your country list.** If you change the setting from **Specific countries** back to **All world**, the selected countries are removed. You’ll need to select them again if you re-enable specific targeting.  
* **Running the same offer in multiple regions?** Create a separate upsell for each region (e.g. one for the US, one for Canada) and give each a clear internal name. This also lets you tailor the title, products, and messaging per region.  
* **If your upsell isn’t showing at all,** location targeting is only one of several possible causes — see Upsell & Cross Sell is Not Showing on My Store \[Fixed\] for a full checklist.

---

# **🎉 Final Result**

Your storefront now shows a location-relevant offer exactly where it matters:

* 🇺🇸 Shoppers browsing from the **United States** see the free gift offer on the cart page  
* 🌐 Shoppers from all other countries don’t see it — no confusion, no irrelevant offers

Region-specific upsells are a simple way to make your offers feel personal, respect shipping and pricing differences between markets, and keep every campaign focused on the customers it was built for 🚀