# Welcome

Orbe is a geolocation app for Shopify stores. It offers international customers a seamless, localised experience tailored to their preferences. It is the gateway to each locale's experience.

It ensures that all customers have the right localised shopping experience (prices, products, language, content and currency) whether they use **Shopify International** (aka Shopify Markets), **Managed Markets** (aka Markets Pro), **Global-e Native**, or have **multiple Shopify expansion stores** for each country they are selling in.

<figure><img src="/files/GRQtoodqzSHu5opBQmXF" alt=""><figcaption></figcaption></figure>

## Who is the Orbe app for?

Orbe is a 💎 *Built for Shopify* app designed for brands expanding internationally through Shopify Markets, Markets Pro, Global-e, or multiple expansion stores. If you're handling growing international traffic, Orbe offers **the best geolocation solution** to enhance your global customer experience.

Orbe’s advanced technology ensures a smooth user journey by improving SEO, complying with data protection laws, and delivering a superior international shopping experience. Without effective geolocation, you risk higher bounce rates, lower international conversion rates, and lost revenue.

Here’s what you need to know:

* **Shopify Configuration:** All product details, pricing, languages, and currencies must be configured through Shopify Markets or Global-e. Orbe reads these settings to geolocate users and direct them to the correct localized experience on your store.
* **Shopify Payments:** Orbe does not handle currency conversion. This functionality is managed natively by Shopify Payments. To sell in multiple currencies, you need to set up Shopify Payments. Supported countries can be found [here](https://help.shopify.com/en/manual/payments/shopify-payments/supported-countries).
* **Built for Shopify:** Orbe is built around Shopify Markets and follows Shopify best practices for international storefronts. It ensures each visitor is routed to, and remains in, the correct local experience (country, language, catalog, and pricing context) across the buying journey. Checkout currency is then handled by Shopify as intended.

For app compatibility details and translation recommendations, see our [FAQs](/before-starting/faqs).


# How it works

<figure><img src="/files/o3Jcy4mCjxIkAlX4xuhY" alt=""><figcaption></figcaption></figure>

Orbe syncs with your Shopify Markets settings to identify the countries where you sell. It creates a custom-designed popup to make recommendations to customers based on their geographic location and preferred browser language.

There are two distinct ways to utilize Orbe, and both can be configured within the Settings:

1. **Welcome Popup.** This is the default option for all brands. It greets customers on their initial visit, prompting them to select their preferred experience. This popup will only appear during the first visit, after which Orbe will store the user's preferences for automatic redirects.
2. **Displaying the popup only to users who are in a wrong shopping experience.** This option ensures that the geolocation popup is displayed only when the user is in the wrong shopping experience. When an international user visits an incorrect shopping experience, Orbe will recommend redirecting them to their localized experience.

{% hint style="success" %}
You can set up how you want to work from the app's Geolocation settings. Learn more [here](/settings/geolocation).
{% endhint %}

## Features

Orbe was conceptualized to be 100% customisable, compliant with data protection laws worldwide and SEO-friendly.

### User experience

Orbe enables a simple, functional and customizable popup to match each brand guideline and offer the best UX. We provide different layouts to adapt to the necessities of our merchants and allow them to use CSS and Javascript to give our technology the best look and feel.

### Data Protection Laws

Some countries prohibit redirecting users to a specific local experience without their consent. To meet these regulations, Orbe integrates with each store to ask customers where they want to buy and recommend the best shopping experience based on their location and preferences. After Orbe saves the permission for subsequent visits, the popup doesn’t bother again.

These data protection laws include, among others, the European Union –GDPR, General Data Protection Regulation–, California –CCPA, California Consumer Privacy Act– or Brazil –LGPD, Brazilian General Data Protection Law–.

### SEO

As [Google's best practices](https://developers.google.com/search/docs/specialty/international/managing-multi-regional-sites) indicate for managing multi-regional or multilingual sites, automatic redirection based on the customer's IP can negatively impact SEO.

Most bots that the leading web crawlers use (such as Google) come from the United States. They don't attempt to vary the location of the crawler to detect site variations. Thus, their IP addresses are primarily associated with IP ranges from the US. In this way, if a store uses automatic redirections, they will also automatically prevent web crawlers from viewing and indexing correctly all the versions of their site.

Orbe redirects users to the right shopping experience by thinking about SEO. We allow web crawlers to read each localised experience without confusion.

### Accessibility

At Orbe, we are committed to universal accessibility and work every day to ensure our products reflect that commitment in practice. Our platform is designed to be usable by as many people as possible, regardless of ability, and we continuously review our features to meet evolving standards.

We are currently compliant with **WCAG 2.1** and **2.2 AA guidelines**, and accessibility remains a core part of how we design and improve Orbe.


# Quickstart

Setting up Orbe only takes a few steps, but each one is essential to ensure everything runs smoothly.

This **checklist** walks you through the key actions to complete in both your Shopify theme and the Orbe app. By following it, you’ll guarantee that your international visitors see the right version of your store, with accurate language, currency, and rules from the very first click.

{% stepper %}
{% step %}

#### **Install Orbe from the Shopify App Store**

Add Orbe to your store directly from the Shopify App Store. It only takes a few clicks to get started.

[Download Orbe](https://apps.shopify.com/orbe) from the Shopify App Store.
{% endstep %}

{% step %}

#### **Choose the right plan for your store**

Select the plan that best matches your international strategy. Each plan unlocks tools designed to help you scale across markets.

See [how to choose the right plan](/before-starting/pricing) for your store.
{% endstep %}

{% step %}

#### **Enable and customize the Geolocation Popup**

Turn on the welcome popup in the Shopify Theme Editor and personalize it to match your brand’s design. This is the first touchpoint for your international visitors.

Find out how to enable and customize your [Geolocation Popup](https://help.orbe.app/selectors/overview).
{% endstep %}

{% step %}

#### **Check your Geolocation settings**

Go to your **Orbe Geolocation > Settings >** [**Geolocation**](http://admin.shopify.com/apps/300c7396da3de51b6c2a5df448979f2a/settings/geolocation) tab to review how your store behaves for international visitors. Here’s what you can customize:

[**When a customer visits for the first time**](/settings/geolocation#first-visit)

Choose if Orbe should appear for every new visitor or only when someone lands in the wrong experience. Showing it to everyone is ideal if you want to capture preferences from the start, while limiting it to incorrect visits keeps the journey simpler.

[**When a customer comes back**](/settings/geolocation#second-visit)

Decide whether Orbe should redirect returning users automatically or only when their location and selected market match. The default option keeps things smooth, while always redirecting guarantees consistency with their chosen country.

[**Language selector behavior**](/settings/geolocation#language-selector-behavior)

Define which language Orbe suggests first, either the visitor’s browser language (recommended for relevance) or the default language of each market set in Shopify.

[**Language settings**](/settings/geolocation#language-settings)

Sometimes users land in the right store but see it in a different language than their preference (for example, a French speaker browsing the Canadian store in English). With Orbe, you can choose whether to simply show a popup suggesting their preferred language or automatically redirect them, ensuring the experience always feels local and consistent.
{% endstep %}

{% step %}

#### **Review existing selectors in your theme**

Verify whether your current country and language selectors are fully synced with Orbe.

{% hint style="success" %}
For the best results, we recommend switching to Orbe’s selectors, which are optimized for compatibility and performance.
{% endhint %}

Click here to discover [how to sync your current selectors](/selectors/overview#why-integration-with-orbe-is-important) with Orbe.
{% endstep %}

{% step %}

#### **Test your setup**

{% hint style="danger" %}
**Must-do before testing**

Disable Shopify’s automatic redirection and check that no other apps are redirecting visitors. You can turn off the country and language redirection from Shopify on

* **For Markets 1.0**, you can enable automatic redirection in [**Markets > Preferences**](https://admin.shopify.com/settings/markets/preferences).

* **For Markets 2.0**, this setting is available in [**Online Store > Preferences**](https://admin.shopify.com/online_store/preferences).
  {% endhint %}

* [ ] Use a VPN to preview your store from different countries.

* [ ] Switch between locations with your selectors on both desktop and mobile.

* [ ] Confirm that [all selectors are synced with Orbe](/selectors/overview#why-integration-with-orbe-is-important) and working consistently.

* [ ] If you test a draft theme across several Shopify Markets domains, add the `?preview_theme_id=...` parameter to each domain URL. Learn why in [FAQs](/before-starting/faqs#draft-theme-preview-market-domains).
  {% endstep %}
  {% endstepper %}


# Pricing

<figure><img src="/files/65zyuFNlwaWffSXaI799" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Subscription charges follow **your store’s billing currency in Shopify**: if your Shopify billing currency is EUR or GBP, we’ll charge you in that same currency. Otherwise, all plans are billed in USD.

For example:

* If your store is billed in **EUR**, the Advanced plan is **29€/mo** instead of $29.
* If your store is billed in **GBP**, the Advanced plan is **£29/mo** instead of $29.
* For all other billing currencies (e.g. MXN, CHF), charges remain in **USD**.
  {% endhint %}

## How do we count total redirects?

We only count a redirect when a visitor lands in the wrong shopping experience and then moves to the correct one.

### Example

Imagine your main store experience is the United States (`www.mystore.com`) with USD and English, and you also have a Spain experience (`www.mystore.com/es-es`) with EUR and Spanish.

<table data-full-width="false"><thead><tr><th width="315.6015625">Scenario</th><th width="173.2578125" align="center">Counts as redirect?</th><th>Why</th></tr></thead><tbody><tr><td>A US visitor lands directly on <code>www.mystore.com</code></td><td align="center">No</td><td>They already land in the correct experience.</td></tr><tr><td>A Spain visitor lands on <code>www.mystore.com</code> and accepts Orbe's recommendation</td><td align="center">Yes</td><td>Orbe moves the visitor to the correct country and language experience.</td></tr><tr><td>On a later visit, that same Spain visitor lands on the wrong experience and Orbe redirects automatically</td><td align="center">Yes</td><td>Orbe applies saved preferences and sends the visitor back to the correct experience.</td></tr><tr><td>On a later visit, that same Spain visitor lands directly on <code>www.mystore.com/es-es</code></td><td align="center">No</td><td>No redirect is needed because they already land in the correct experience.</td></tr><tr><td>A visitor changes country or language from an Orbe selector and moves to another experience</td><td align="center">Yes</td><td>The visitor is moved to a different market experience.</td></tr></tbody></table>

{% hint style="info" %}
The Free Plan includes up to 300 total redirects. Paid plans include unlimited redirects.
{% endhint %}

For a full analytics view of redirect metrics, see [Metrics](/general/metrics).

## Do you offer a free trial?

You can use our geolocation service for free, up to 300 total redirects. If you'd like more time to evaluate our service before making a decision, we offer free trials:

* For Monthly plans, you'll enjoy a **7-day free trial**. If you decide to cancel your plan within these seven days, you won't incur any charges.
* We provide a **15-day free trial** with yearly plans. If you choose to cancel your plan during the first 15 days, no charges will be applied.


# FAQs

## Orbe

<details>

<summary>Why should I choose Orbe over Shopify’s automatic redirection for geolocation?</summary>

Forcing visitors into a country storefront with IP-based automatic redirects can look like a shortcut, but it often creates more problems than it solves.

International storefronts need more than a redirect. They need the right balance between SEO, privacy, accessibility, and user choice.

Forced redirections can affect:

* **SEO:** search engines might not be able to access and index all localized versions of your store correctly. Google recommends avoiding automatic redirection between language versions because it can prevent users and search engines from viewing every version of the site: [Google Search Central](https://developers.google.com/search/docs/specialty/international/managing-multi-regional-sites#let-the-user-switch-the-page-language).
* **Crawlers, feeds, and LLMs:** bots, commerce crawlers, and AI crawlers can receive only the redirected version of the page. If a crawler is redirected to the US or English experience, it might miss localized prices, currencies, product content, or language-specific pages.
* **Google Merchant Center:** mismatches between prices, currencies, and campaign destinations can create disapprovals or incorrect product data.
* **Privacy compliance:** forcing a redirect before the visitor makes a choice can create issues under privacy and data protection laws, especially in regions where users must be able to understand and control how their location or language preferences are used.
* **Customer trust:** visitors can feel disoriented if they are moved without being asked.

Orbe Geolocation is built for this layer.

Orbe Geolocation gives visitors a clear, accessible way to choose their country and language experience instead of forcing an automatic redirect on the first visit. After the visitor makes a choice, Orbe remembers it with a first-party functional cookie and can keep them in the correct country experience on later visits.

This means the first visit is privacy-conscious and user-led. Return visits can be frictionless.

Shopify also recognizes that automatic redirection has limits. For example, Shopify explains that EU customers accessing a localized experience with an EU country-code domain, such as `.de`, `.fr`, or `.es`, are not automatically redirected. Shopify recommends using a third-party app to provide country or region recommendations so customers can select the best experience for their language and location.

You can read Shopify's documentation here: [Country/region redirection in the European Union (EU)](https://help.shopify.com/en/manual/international/automatic-redirection#countryregion-redirection-in-the-european-union-eu).

This helps merchants with:

* **Better international UX:** visitors can choose the right country and language experience.
* **Privacy-conscious routing:** Orbe asks first, then remembers the visitor's choice.
* **Consistent return visits:** Orbe remembers the visitor's country and language choice.
* **SEO control:** regional experiences can remain discoverable by search engines.
* **Feed and crawler reliability:** localized experiences can stay accessible to search engines and commerce crawlers.
* **Accessibility:** Orbe's geolocation popup and selectors are designed and maintained to meet accessibility criteria within the components controlled by Orbe.

In short, Orbe gives international merchants more control over how visitors choose, enter, and return to the correct country storefront without sacrificing SEO, compliance, accessibility, or user choice.

</details>

<details>

<summary>How can I customise the style of the welcome Orbe popup?</summary>

Orbe integrates natively with any Shopify theme. Once you install Orbe in your store, you can customise the look and feel of your popup using our app-embed in the Shopify Theme Editor.

</details>

<details>

<summary>Is it possible to show "Markets" or group countries in the selector instead of showing each individual country in the country selector?</summary>

Due to technical constraints and limitations within Shopify International (also known as Shopify Markets), Orbe is unable to display "Markets" or group countries together in the country selector. While Shopify Markets allows merchants to group experiences by market, it is fundamentally structured at the country level. Markets have been designed as a Shopify feature intended solely to make management more efficient for the merchant, not for the customer’s final storefront experience.

Unfortunately, it is not possible to show "Markets" or group countries in the selector due to how Shopify storefronts are structured at a country-specific level. While it might seem practical to group countries under broader categories like "Europe" or "Rest of the World," Shopify requires each redirection to be tied to an individual country.

Imagine a scenario where a brand has four available markets: the United States, the United Kingdom, a market labeled "Europe" encompassing Spain, France, Italy, and Germany, and a "Rest of the World" market covering all other countries. Ideally, the brand might want the geolocation popup to display only these four options: the United States, the United Kingdom, Europe, and Rest of the World. However, since Shopify Markets is structured at the country level, every redirection by Orbe must be specific to an individual country.

For example, assuming the store URL is <https://mystore.com>, to redirect users within the "Europe" market, Orbe would need to add a specific `?country=CountryCode` parameter for each country. This would result in unique redirection links for each country in Europe:

* Spain: <https://mystore.com/?country=ES>
* France: <https://mystore.com/?country=FR>
* Italy: <https://mystore.com/?country=IT>
* Germany: <https://mystore.com/?country=DE>

While Shopify Markets allows merchants to group countries for organizational simplicity, it does not support redirection to an entire market. Instead, redirection remains country-specific, which affects factors like tax rates, shipping options, or even content tailored to each country.

Consider a scenario where a merchant wishes to redirect users to a "Rest of the World" market that spans Europe, Asia, and Oceania. Shopify would require a specific country to be indicated in the URL for this redirection. For instance, if "Australia" were chosen as the representative country for "Rest of the World," a user accessing the store from Japan would be directed to an experience tailored for Australia. This could lead to discrepancies in prices (due to different tax rates), shipping options, and even country-specific content configured in Shopify using the `{{ localization.country }}` object in Liquid. Thus, each country can have unique configurations and localized experiences that cannot be overridden by a market grouping.

Attempting to redirect at a market level or group countries in the selector **is not technically compatible with Shopify Markets**. Any app trying to redirect to a market as a whole, rather than by individual country, would be incompatible with Shopify’s infrastructure, potentially leading to issues with the customer experience.

Orbe adheres to this country-based structure to ensure full compatibility with Shopify’s ecosystem, as Shopify is built for storefronts focused on the country level.

</details>

<details>

<summary>Is it possible to implement automatic redirections instead of showing a popup?</summary>

Yes. Orbe Geolocation can automatically redirect visitors, but only after the visitor has made an explicit country or language choice.

This is intentional. Forcing an automatic redirect on the first visit can create SEO, privacy, accessibility, and user experience issues for international storefronts. We explain this in more detail here: [Common Shopify Markets mistakes: relying on redirects](https://orbe.app/blogs/blog/shopify-markets-mistakes#rely-on-redirects).

On the first visit, if an international visitor lands in the wrong country experience, Orbe performs a one-off technical geolocation check and shows a geolocation popup. The visitor can then choose the right country and language experience.

After that explicit action, Orbe stores the visitor's choice in a first-party functional cookie.

On later visits, Orbe can automatically redirect the visitor to the correct country and language experience without showing the popup again, depending on your configuration.

This gives merchants the best of both worlds: a privacy-conscious first visit and a frictionless experience on return visits.

This approach helps protect international SEO, respect privacy expectations, and guarantee a better international UX. Automatic redirections without a prior visitor choice can create SEO, privacy, and user experience issues, especially for international storefronts.

</details>

<details>

<summary>Does Orbe appear twice to the user?</summary>

No, it doesn't.

Orbe does not show the geolocation popup twice when the visitor already has a saved country and language preference.

The usual flow is:

1. On the first relevant visit, Orbe shows the geolocation popup so the visitor can choose their country and language.
2. After the visitor makes a choice, Orbe remembers that preference with a first-party functional cookie.
3. On later visits, Orbe uses that saved preference to load the correct storefront automatically, without showing the popup again.

The popup only appears again if the saved preference expires.

You control that timing with the **Preferences duration** setting. For example, if you ask Orbe to remember a visitor's choice for 60 days, the popup stays hidden during those 60 days. After that, Orbe can ask again so the visitor can confirm their country and language.

Learn how to configure it in [Geolocation](/settings/geolocation#preferences-duration).

</details>

<details>

<summary>Can I use Orbe with multiple expansion stores?</summary>

Yes, you can, and it is our most popular use case. If you pay for the Plus Plan in one of your stores, you can connect a maximum of four different Shopify stores and redirect the traffic to the right shopping experience. If you have over four Shopify stores, please contact our team at <support@orbe.app> to request a custom plan.

</details>

<details>

<summary>Does Orbe allow redirecting with the full path of the URL?</summary>

Yes, it does. It’s an advanced setting you can enable. If a merchant connects two different Shopify stores and both have the same URL structure, can enable this feature so if, for example, a British user goes to example.fr/collections/all, it will be redirected to example.co.uk/collections/all.

</details>

<details>

<summary>Does Orbe allow efficient UTM tracking when there is a redirection?</summary>

Yes, it does. For example, if a French user access to the United States experience with a UTM parameter from a Facebook ad: <https://store.com/?utm\\_content=textlink\\&utm\\_source=facebook>, Orbe will redirect the user to the French experience maintaining the full path in the URL: <https://store.fr/?utm\\_content=textlink\\&utm\\_source=facebook>.

In this way, Orbe guarantees that the store owner does not lose the traffic attribution for all their media campaigns.

</details>

<details>

<summary>Is Orbe compatible with other apps?</summary>

Yes. Orbe is compatible with any app that is compatible with Shopify Markets, including order editing, checkout, subscriptions, and other Shopify-native app flows.

</details>

<details>

<summary>Is Orbe compatible with translation apps?</summary>

Yes. Orbe works with translation apps that follow Shopify's Translation API and Shopify Markets workflow.

Your translation app manages your store content translations (theme, product, and collection content). Orbe manages international logic, including geolocation recommendations and country/language routing.

If you are evaluating translation options, you can explore Shopify's store-language apps here: <https://apps.shopify.com/collections/apps-for-store-languages>.

Orbe Translate is coming soon and will become our recommended setup for Shopify merchants. You can join the beta here: <https://orbe.app/pages/translate>.

</details>

<details>

<summary>Does Orbe convert currencies with JavaScript?</summary>

No. Orbe does not use client-side JavaScript currency conversion.

This is intentional. In Shopify, the best practice is to set local currencies through Shopify Markets and Shopify Payments, so customers can complete checkout in the correct local currency.

JavaScript currency converters can display converted prices in the storefront, but checkout may still happen in a different currency. This creates confusion and a poor buying experience.

Orbe focuses on international routing and market experience: it ensures each visitor lands in the correct country and language experience, and stays in the correct journey. Shopify then handles checkout currency as intended.

If your business cannot use Shopify Payments in your country, a currency converter can still be a temporary fallback for price display. In that case, keep in mind that customers may still pay in your store's primary currency.

</details>

<details>

<summary>Can I add country and language selectors with Orbe?</summary>

Yes. Orbe provides multiple selector options you can add to your theme, including Geolocation Button, Country Selector, Language Selector, and Modal Selector.

If your theme already includes its own selector, you can also integrate it with Orbe. See the full options here: [Selectors overview](/selectors/overview).

</details>

<details>

<summary>Does Orbe have a Free plan or Trial plan?</summary>

You can use our geolocation service for free, up to 300 total redirects. If you'd like more time to evaluate our service before making a decision, we offer free trials:

* For Monthly plans, you'll enjoy a **7-day free trial**. If you decide to cancel your plan within these seven days, you won't incur any charges.
* With Yearly plans, we provide a **15-day free trial.** Should you choose to cancel your plan during the first 15 days, there will be no charges applied.

For details on what counts as a redirect, see [How do we count total redirects?](/before-starting/pricing#how-do-we-count-total-redirects).

</details>

<details>

<summary>What happens if I want to cancel my subscription?</summary>

You can cancel the paid plan at any time. You will only be charged for the last month you used Orbe.

</details>

<details>

<summary>Why is the Orbe cookie a first-party essential cookie?</summary>

Orbe uses a first-party functional cookie to remember the visitor's location and language choice. This cookie is created only when the visitor takes an explicit action in the geolocation popup, such as accepting or selecting a country, language, or market.

The initial geolocation check does not install cookies. It uses minimal technical data, such as IP address or browser language, on a one-off and non-persistent basis to recommend the right localized experience.

This cookie is essential because it lets Orbe keep the visitor in the correct language, country, currency, or market experience on future visits. Without that preference, Orbe cannot reliably provide the experience requested by the visitor, including an accessible experience where they can understand the storefront and cookie banner.

This first-party functional cookie is used only to remember the visitor's choice and render the right storefront.

If you use Shopify cookie management apps, the Orbe functional cookies should be allowed as essential cookies. Blocking them can prevent Orbe from remembering the visitor's country or language choice and may break the international experience.

The main Orbe functional cookies are:

* `mdApp_countryCodeDomain`
* `mdApp_showRecommendationLang`

This information is provided for transparency. For other jurisdictions, merchants remain responsible for configuring their own cookie banner, privacy policy, and legal settings according to local law.

</details>

<details>

<summary>Does Orbe's geolocation popup meet accessibility standards?</summary>

Yes. Orbe Geolocation's default geolocation popup, country selector, and language selector are designed and maintained to meet WCAG 2.1 AA accessibility criteria within the components controlled by Orbe.

Accessibility is part of Orbe's value for international storefronts. Visitors should be able to choose their country and language without barriers.

This includes keyboard interaction, readable structure, contrast considerations, clear hierarchy, and compatibility efforts with assistive technologies.

The final accessibility of the storefront can also depend on the merchant's theme, custom code, third-party scripts, and implementation. Merchants remain responsible for the accessibility of their storefront as a whole.

You can read the full Accessibility Statement here: <https://orbe.app/pages/accessibility-statement>.

</details>

## Shopify Markets

When using Shopify Markets, you might come across specific store behaviours or have doubts about setting up your preferences accurately. No worries! We're here to assist you in resolving these common queries.

{% hint style="info" %}
We strongly advise you to refer to the **official Shopify Markets** support documentation at <https://help.shopify.com/en/manual/markets> for further assistance.
{% endhint %}

<details>

<summary>What is the behaviour of Shopify Markets when a user transitions from the storefront cart to the checkout?</summary>

As explained by the Shopify Markets team:

If the user does not use Orbe or any selector in their theme to choose a country in the storefront, Shopify will automatically geolocate the country during checkout. However, suppose the user intentionally selects a different country than the default in any selector on the storefront. In that case, Shopify respects that selection and sets it as the default country in the checkout.

For example, suppose a customer enters the storefront without selecting their market in Orbe and is located in a different country than the one they are visiting. In that case, the checkout will automatically change to their IP country and the user's preferred language.

Consider a specific example: Suppose a user does not use the Orbe popup or any country selector in their theme and is visiting your store's British experience in English. This user wants to ship their order to the UK. However, the user is located in France, and their preferred browser language is French (both available in another experience of your store). Once the user proceeds to the checkout, it will automatically switch to their location and language, despite being in a different store experience.

We hope this information clarifies any questions about the behaviour of Shopify Markets during the transition from the storefront cart to the checkout screen. If you have any further questions, please don't hesitate to contact us.

</details>

### Draft theme previews across domains <a href="#draft-theme-preview-market-domains" id="draft-theme-preview-market-domains"></a>

This can happen when you are testing a draft theme on a Shopify Markets setup with several domains.

Shopify keeps a draft theme preview per domain. If you open a draft theme on one domain and then move to another country domain, Shopify can show the live theme for that domain instead of the draft. The change has not disappeared. You have just left the preview for that domain.

To test the same draft theme on each domain, add the Shopify preview parameter to every domain you check:

{% code title="Draft theme preview URLs" overflow="wrap" %}

```
https://your-store.de/?preview_theme_id=123456789
https://your-store.fr/?preview_theme_id=123456789
```

{% endcode %}

In this example, `123456789` is the draft theme ID. You can get it by copying the link from the **Preview** button in Shopify, or by opening the theme editor and copying the number that appears in the URL:

{% code title="Theme editor URL" overflow="wrap" %}

```
https://admin.shopify.com/store/yourstorename/themes/194237432155/editor
```

{% endcode %}

Here, the theme ID is `194237432155`.

When the theme is published, you do not need this parameter. The live theme will load normally across your Shopify Markets domains.


# Install Orbe

Installing Orbe will only take two minutes and allow you to ensure your customers always see the right products, prices, content, currency and language, depending on their country. In this tutorial, we will describe how you can do it:

## Step 1: Search for Orbe and add app

After gaining an understanding of how Orbe works and how it can benefit your business, it's time to proceed with the installation. You can find Orbe Geolocation in the Shopify App Store by searching for it, or you can quickly access the app listing by clicking on this [link](https://apps.shopify.com/orbe?utm_source=docs\&utm_medium=content\&utm_campaign=install-orbe).

Next, simply click on "Add app":

<figure><img src="/files/hZcs1hiAu3vvNESDxS3B" alt=""><figcaption></figcaption></figure>

## Step 2: Install the app

Please keep in mind that Orbe installation is free and requires only minimal permissions to function. It remains free until you exceed 5,000 page views per month. Beyond that threshold, a payment will be required to continue using it.

With these considerations in mind, go ahead and click on "Install app".

<figure><img src="/files/y19m8ZZar5g2hNuJZMVF" alt=""><figcaption></figcaption></figure>

## Step 3: Onboarding

Once you have installed Orbe, you will find a two-step onboarding process. Its purpose is to briefly explain how Orbe works and assist you in configuring your store's geolocation. To do this, click on 'Customize popup,' and you will be taken to the Shopify Theme Editor.

<figure><img src="/files/9ZbegYZtguijiZR13nlX" alt=""><figcaption></figcaption></figure>

We recommend referring to [Geolocation popup](/geolocation-popup/getting-started) for more detailed instructions on setting up the App Embed correctly.


# Refresh data

How can I resolve the issue if my popup isn't displaying all countries?

Be sure to click "Refresh data" whenever you make changes to your Markets to ensure that your customers always see the most up-to-date information.

Orbe is a geolocation app that seamlessly integrates with Shopify Markets. Due to considerations of performance and scalability, as well as the fact that most merchants configure Markets infrequently, we do not regularly access your Markets settings.

To ensure that Orbe reflects your latest configuration changes in Shopify Markets, please remember to manually click 'Refresh Data' in Orbe every time you make adjustments. This action allows us to refresh and display your updated configuration in the geolocation popup and the country selector.

<figure><img src="/files/LfBH4QtBtVoKFj77az6T" alt=""><figcaption></figcaption></figure>

## When should you resfresh your data?

When you make changes to your markets, open Orbe, and click 'Refresh Data.' This includes any of the following changes:

* Creating a new market.
* Removing some countries.
* Adding a new country to an existing market.
* Modifying the currency.
* Publishing new languages in a specific market.

## Example

Let's illustrate this with an example:

Imagine a scenario where a store does not have a dedicated market for Germany, and Germany is also not part of the International Market selection. In this situation, Orbe will not display Germany in the country selector.

<figure><img src="/files/Fsh8fxdcYAWDB36huH9M" alt=""><figcaption></figcaption></figure>

However, if, after some weeks, the store owner decides to include Germany as a market through the Markets settings but forgets to click "Refresh Data," the information in Orbe will become outdated.

<figure><img src="/files/Ms4hqVukfowRD3VdUl4p" alt=""><figcaption></figcaption></figure>

To rectify this, simply go to Orbe, click "Refresh Data," and observe how your popup works perfectly.

<figure><img src="/files/E1iswhG9GXegm1f2xktv" alt=""><figcaption></figcaption></figure>


# Metrics

Understand the main redirect metrics in your app home.

{% hint style="info" %}
Use these metrics to measure Orbe's impact on your international storefront and track your Free Plan usage.
{% endhint %}

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Total redirects</strong></td><td>Main metric in Orbe. It combines first-time and returning redirects.</td><td><a href="#total-redirects">#total-redirects</a></td></tr><tr><td><strong>Unique redirects</strong></td><td>First-time visitors who land in the wrong experience and then move to the correct one.</td><td><a href="#unique-redirects">#unique-redirects</a></td></tr><tr><td><strong>% of automatic redirects</strong></td><td>Share of returning visitors redirected automatically after landing in the wrong experience again.</td><td><a href="#of-automatic-redirects">#of-automatic-redirects</a></td></tr></tbody></table>

## Total redirects <a href="#total-redirects" id="total-redirects"></a>

This is the main metric in Orbe.

`Total redirects = Unique redirects + Automatic redirects`

You can also use this metric to monitor how close your store is to the Free Plan limit.

## Unique redirects <a href="#unique-redirects" id="unique-redirects"></a>

This counts first-time visitors who land in the wrong shopping experience and then move to the correct one.

`Unique redirects = Total redirects - Automatic redirects`

## % of automatic redirects <a href="#of-automatic-redirects" id="of-automatic-redirects"></a>

This metric only covers returning visitors. If they land in the wrong experience and Orbe moves them automatically, it counts. This is where Orbe adds value: it keeps visitors in the correct country storefront in Shopify. If they land in the correct experience directly, nothing is counted.

In your app home, you see this as a percentage of total redirects.

`% of automatic redirects = (Automatic redirects / Total redirects) x 100`

## Example

If your app home shows:

* `Total redirects: 123`
* `Unique redirects: 58`
* `% of automatic redirects: 53%`

Then:

* `Automatic redirects: 65` (123 x 53%)

{% hint style="success" %}
These metrics help you understand both product impact and Free Plan usage.

For plan limits and billing details, see [Pricing](/before-starting/pricing).
{% endhint %}


# Connect Stores

Learn how to redirect between multiple international stores

{% hint style="info" %}
This feature is available in the Orbe **Plus** and **Enterprise** plans. You only need to subscribe on **one store.**\
All other connected stores can remain on the **Free plan** and are fully sponsored, with access to all features.
{% endhint %}

Orbe allows you to connect **multiple Shopify stores** or stores on other platforms into one unified shopping experience.

<figure><img src="/files/pmQ2PSROeSZ8zw2JCS3i" alt="" width="375"><figcaption></figcaption></figure>

Merchants that sell internationally often have separate stores for each country or region. Each store typically has its own domain. For example:

* `store-us.myshopify.com` (Shopify store)
* `store-eu.myshopify.com` (Shopify store)
* `store-uk.myshopify.com` (Shopify store)
* `store-asia.com` (another platform or technology)

With Orbe, you can easily connect all these expansion stores. This way, your customers see a unified geolocation popup that automatically directs them to the correct store based on their location and preferences.

## FAQs

<details>

<summary><strong>Do I need to pay for each store I connect?</strong></summary>

No. With the Plus plan, you only need to upgrade in one store. All other stores are sponsored for free. Learn more here: [Redirect to another store](/general/connect-stores/redirect-to-another-store)

</details>

<details>

<summary><strong>Can I connect stores outside of Shopify?</strong></summary>

Yes. You can connect stores from other platforms like Magento, distributors or franchise websites. Learn more how to do it here: [Redirect to another store](/general/connect-stores/redirect-to-another-store)

</details>

<details>

<summary><strong>What if I have more than 4 stores to connect?</strong></summary>

You’ll need an Enterprise plan. [Contact us](https://orbe.app/contact) and we’ll help you upgrade.

</details>

## How to use it

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>🔀 <strong>Redirect to another store</strong></td><td>Learn how to add and redirect customers between your multiple stores.</td><td><a href="/pages/csnfKSjzr7SwDS9pR16I">/pages/csnfKSjzr7SwDS9pR16I</a></td></tr><tr><td>⚙️ <strong>Settings</strong></td><td>Manage your redirect preferences and exclude specific URLs from redirection.</td><td><a href="/pages/gWu32owOXbfulHGyY0qj">/pages/gWu32owOXbfulHGyY0qj</a></td></tr></tbody></table>


# Redirect to another store

Orbe allows you to connect all your regional stores (whether on Shopify, BigCommerce, Magento, WooCommerce, Amazon, or other technologies) into a single, unified shopping experience.

When customers visit any of your stores, they'll see the same geolocation popup and selectors with all available countries and languages, no matter where they land.

This way, your store feels like **one global storefront**, even if it runs across multiple platforms.

## How it works

Orbe merges the country and language options from **all your connected stores** into a single, consistent selector and popup.

Your customers will always see the full list of markets you support, without knowing they're navigating between different stores behind the scenes.

You only need to **subscribe to Orbe on one store** (what we call your main store). All other connected stores can stay on the Free plan and are fully sponsored.

### Add a Shopify store

Before adding a store, make sure Orbe is installed on the Free plan in the store you want to connect.

You only need to subscribe to Orbe on one store (what we call your main store). All other connected stores can stay on the Free plan and are fully sponsored.

To add a Shopify store:

1. In the store you want to connect, install Orbe on the Free plan.
2. In that store, go to **Connect stores** and copy the **Account ID**.
3. Go to your main store (the one with a subscription) and open **Connect stores**.
4. Click **Connect store**, select **Shopify**, and paste the Account ID.
5. Go to this new store and **approve the connection**. This step is required to verify your ownership of the store.
6. Click **Save**.

Repeat for each store you want to connect.

{% embed url="<https://www.loom.com/share/5de88e95affb469d91d23d86d79a159a>" %}

{% hint style="info" %}
**Things to keep in mind**

If you don’t have access to install Orbe in a Shopify store (for example, in a distributor or franchise store), select "**Other platform"** (adding it as an [external store](#add-a-store-from-another-platform)).

However, we only recommend this when there's no alternative. Installing Orbe on the Free plan is always preferred to ensure a fully synced and consistent experience.
{% endhint %}

#### Duplicates

When two or more connected stores include the same country, **Orbe automatically handles the conflict**, keeping the country active in one store and deactivated in the other.

From the Connect stores view, you can see at a glance all the countries in each store (active and deactivated) without any extra clicks.

If a country appears in more than one store, you'll see a **`+X in other stores`** label. Click it to expand and see exactly which stores have it and whether it's active or not.

**How Orbe decides which store gets the country by default:**

1. If one of the stores is set as primary, that store gets the country active by default.
2. If no store is set as primary, the store that was connected first gets the country active. The same country in the newly connected store will appear as deactivated.

**To move a country from one store to another:**

1. In the Connect stores view, find the store you want to receive the traffic.
2. Click **Edit** *(the pencil icon)* on that store.
3. You'll see only the countries that are duplicated across stores. Select the country you want to move.
4. Confirm the change. Orbe will activate the country in this store and deactivate it in the other automatically.

{% embed url="<https://www.loom.com/share/63bf429aef5a4c6189e3ef66fa7a14e0>" %}

{% hint style="info" %}
**Example**\
You have Store A (connected first) and Store B (connected later), and both include Spain. Orbe will automatically keep Spain active in Store A and deactivated in Store B. If you want Spanish traffic to go to Store B instead, click **Edit** on Store B, find Spain, and activate it there. Orbe will deactivate it in Store A automatically.
{% endhint %}

Once you've made a change, click the three dots next to the store and select **Refresh data** to see the update reflected immediately.

### Add a store from another platform

To connect an external store (Magento, WooCommerce, BigCommerce, Amazon, etc.):

1. In your main store, go to **Connect stores**.
2. Click **Connect store**, then select the platform.
3. Enter the store URL and click **Save.**
4. Assign all the **countries** this store will serve.
5. For each country, define the **languages**, **currency**, and whether the **URL changes** based on country or language.
   1. **This step is required**. The store will remain in **Pending** status and won’t be added until everything is set.
   2. (Optional) Enable **Redirect with full path URL** if the store you’re connecting uses the same URL structure. For example, if `/products/example` exists in both stores, this option will redirect the user to the exact same page instead of the homepage.
6. Click **Save** to finish.

The store will now appear in your geolocation popup and selector like any other Shopify store.

{% embed url="<https://www.loom.com/share/f48d3187c3de402fb45bfb95809485ed>" %}

{% hint style="info" %}
**Things to keep in mind**

If the same country is assigned to both a Shopify store and an external store, Orbe will prioritize the external store.
{% endhint %}

## Set up your country and language selector

You need to use one of [**Orbe's selectors**](/selectors/overview) to give your customers access to all countries and languages across your connected stores.

If a customer uses the **native selector from your theme** to change their country or language:

* It only displays the countries and languages available in the current store. It is not aware of the complete list of markets across all your stores.
* The experience will feel disconnected when navigating between stores.
* It will not update their preferences on Orbe, so the redirection logic may not behave as expected.

Only [**Orbe’s selectors**](/selectors/overview) show all available countries and languages, and sync with the popup and redirection logic.

**To make sure everything works as expected**, use a selector built by Orbe: [Overview](/selectors/overview)

## FAQs

<details>

<summary><strong>I want to move a country from one store to another. How do I do it?</strong></summary>

Just go to the new store where you want to manage that country and click **Refresh data** in Orbe. Orbe will detect the overlap and let you reassign it to the new store.

</details>

<details>

<summary><strong>Do I need to install Orbe in all stores?</strong></summary>

Yes, Orbe must be installed in all connected stores, but only one of them needs a **Plus** or **Enterprise** plan.

</details>

<details>

<summary><strong>Do I need to configure the popup in every store?</strong></summary>

Yes. Since the popup is a **Shopify app embed**, you must activate it manually in the theme editor of each live theme across your connected stores. You can follow [this guide](/geolocation-popup/getting-started) to do it step by step.

</details>

<details>

<summary><strong>Can I connect more than 4 stores?</strong></summary>

Yes, but you'll need an Enterprise plan. [Contact us](https://orbe.app/contact) and we'll help you upgrade.

</details>


# Settings

## Set up redirect behavior

When connecting multiple stores, you can decide how redirections between them should work. There are two options:

<figure><img src="/files/NelJidzohkiskbdrsyfB" alt=""><figcaption></figcaption></figure>

### Redirect to homepage

Use this if **your stores don’t share the same URL structure**.

This option redirects users to the homepage of the correct store. It helps prevent 404 errors when equivalent pages don’t exist across stores.

### Redirect to the same page

Use this if **your stores share the same URL paths**.

When enabled, Orbe redirects users to the same page they were visiting, but in the correct store.

For example:

* The user lands on: `https://store-a.com/products/example1`
* They are redirected to: `https://store-b.com/products/example1`

If this option is disabled, they will be redirected to: `https://store-b.com/`

## Exclude specific URLs from geolocation

Sometimes you might want to disable the popup or redirection on specific pages—like a shared blog, press section, or landing pages. By excluding URLs, Orbe will stay inactive on those pages.

<figure><img src="/files/RaQYVaXu9Ef749R8l8l6" alt=""><figcaption></figcaption></figure>

#### Example use case

Imagine you have a shared blog hosted in your US store, and users from other countries should access it without redirection. To prevent Orbe from triggering, add an exclusion like: `/blogs/global-blog*`

This disables both the popup and any redirection logic on all pages that start with that path.

{% hint style="info" %}
URL exclusions give you control over where and when Orbe’s popup and redirect logic should apply.
{% endhint %}

#### How to format exclusions

* Add **relative URLs only** (no domain)
* Use an asterisk `*` to match all content after the URL
* Separate multiple URLs with commas

Example: `/blogs/global-blog*, /pages/summer-sale, /pages/about-us`

### FAQs

<details>

<summary>What happens if my store doesn't have the same URL structure?</summary>

Use the "Redirect to homepage" option. It avoids 404 errors by sending users to the homepage of the correct store.

</details>

<details>

<summary>What if I want users to land on the same page in another store?</summary>

Enable "Redirect to the equivalent page in the correct stores." It works only if all your stores follow the same URL structure.

</details>

<details>

<summary>How do I make sure certain pages never trigger the popup or redirection?</summary>

Use the [exclusion rules](#exclude-specific-urls-from-geolocation) to disable Orbe on any URL. Make sure to format the paths correctly (e.g., `/blogs/global*`).

</details>

<details>

<summary>Can I exclude only one specific page?</summary>

Yes. Just use the full relative URL without `*`, like `/pages/press`.

</details>

## Shared settings across stores <a href="#shared-settings" id="shared-settings"></a>

{% hint style="warning" %}
You’ll only see **Shared settings** if your account meets both conditions below:

* You’re on an **Orbe Plus or Enterprise plan**;
* You have **more than one store** connected to Orbe.

If either requirement isn’t met, the Shared settings option won’t appear in **Connect stores**.
{% endhint %}

### What Shared settings is <a href="#shared-settings-definition" id="shared-settings-definition"></a>

Shared settings let you **apply the same configuration across all your connected stores**, so you don’t need to repeat the same update over and over. **Each section can be shared or kept independent**, giving you full flexibility: make a change once when all stores should behave the same, or switch a section back to local settings when you need exceptions for specific markets.

**It works per section, not globally**. This means you decide **in each specific tab** whether settings are shared or kept independent. The feature is available in:

* **Settings →** [**Geolocation**](/settings/geolocation);
* **Settings →** [**Custom code**](/settings/custom-code);
* and [**Integrations**](/general/integrations) **→ All**, **Internationalization** and/or **marketing**.

You choose, in each section, whether the settings are shared between stores or managed independently. It does **not** affect the “Connect stores” setup itself.

<figure><img src="/files/SGja0knINnuu4Flqegf3" alt=""><figcaption></figcaption></figure>

#### When you turn Shared settings **on** <a href="#shared-settings-on" id="shared-settings-on"></a>

When you activate Shared settings in a section, Orbe immediately takes the settings from the store you’re currently editing and **copies them to all other connected stores** for that specific section.

From there, the section becomes shared: **any change you make and save is automatically synced across all stores**, so you only need to configure it once.

#### When saving changes with Shared settings **on** <a href="#save-shared-settings" id="save-shared-settings"></a>

Once a section is shared, you only need to configure it **once**. Any change you make (no matter **which store** you’re editing from) will automatically sync across all connected stores for that section.

All stores stay perfectly aligned, so your setup remains consistent everywhere without extra steps.

#### When you turn Shared settings **off** <a href="#shared-settings-off" id="shared-settings-off"></a>

When you switch Shared settings off in a section, **synchronization stops right away**. Nothing is reversed or overwritten: **each store keeps the settings it already had** at that moment.

From then on, changes you make apply **only** to the store you’re currently editing, and that section becomes fully independent again for every store.

### FAQs <a href="#shared-settings-faqs" id="shared-settings-faqs"></a>

<details>

<summary>If I activate Shared settings, will changes apply to all my stores?</summary>

**Yes**. As long as Shared settings is **on** in a section, anything you edit there will be synced across all connected stores.

</details>

<details>

<summary>If Shared settings is off, do changes apply only to one store?</summary>

**Exactly**. With it off, each store has its own local settings. Changes affect **only** the store you're editing.

</details>

<details>

<summary>Can I keep different settings for different stores?</summary>

**Yes**. Shared settings works **per section**, not globally.

* If Shared settings is **on** in a section, all stores share those settings.
* If it’s **off**, that section is independent for every store.

</details>

<details>

<summary>What happens if I turn Shared settings on later?</summary>

Orbe will take the settings of the store you are currently editing and **push them to all other stores** for that section, then start syncing going forward.

</details>

<details>

<summary>What happens if I turn it off later?</summary>

The sync stops. All stores keep the settings they currently have (nothing is undone). From there, each store becomes independent again for that section.

</details>


# Integrations

Use these guides to connect Orbe with your international setup and key ecosystem apps.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Global-e</strong></td><td>Official partnership and native compatibility guide for stores using Global-e Native and Shopify Markets.</td><td><a href="/pages/zRk4teNfk53noDnbaM6u">/pages/zRk4teNfk53noDnbaM6u</a></td></tr><tr><td><strong>Klaviyo</strong></td><td>Sync country and language preferences to Klaviyo profiles for localized email and SMS flows.</td><td><a href="/pages/XY6qWbmJK7qZ42eesVqb">/pages/XY6qWbmJK7qZ42eesVqb</a></td></tr><tr><td><strong>Connectif</strong></td><td>Send user country and language preferences to Connectif for segmentation and localized automation.</td><td><a href="/pages/LmXBmLd5ZRcPod8F42oH">/pages/LmXBmLd5ZRcPod8F42oH</a></td></tr><tr><td><strong>Hreflang Manager</strong></td><td>Improve international SEO for multi-store setups with hreflang management and Orbe partnership benefits.</td><td><a href="/pages/xcJjAxJz8eLOra7bz2Wp">/pages/xcJjAxJz8eLOra7bz2Wp</a></td></tr><tr><td><strong>Announcement Bar</strong></td><td>Create dynamic country-specific announcement bars using Orbe with Translate &#x26; Adapt.</td><td><a href="/pages/idUQTYcL81ZpolXhUl2L">/pages/idUQTYcL81ZpolXhUl2L</a></td></tr></tbody></table>


# Klaviyo

Integration of Orbe with Klaviyo

[Klaviyo](https://www.klaviyo.com/partner/signup?utm_source=0013o00002ZsVRdAAN\&utm_medium=partner) is a marketing automation platform that enables merchants to create personalized email and SMS campaigns based on customer behavior and data.

When connected with Orbe, it allows you to send **each customer’s country** and **language preferences** **directly to their Klaviyo profile**, helping you localize your communication and build more relevant marketing experiences for every market.

{% hint style="info" %}
Want to see how it works? Watch [our short video on YouTube](https://www.youtube.com/watch?v=vIPs7enYTXc) to learn more about Klaviyo and how to make the most of it with Orbe.
{% endhint %}

## How to active the integration with Klaviyo? <a href="#active-klaviyo-integration" id="active-klaviyo-integration"></a>

{% embed url="<https://www.loom.com/share/fa55801195964cf0abb7f27f0820a9c8>" %}

Here’s **a quick step-by-step recap** of the Klaviyo ↔ Orbe integration shown in the video.

{% stepper %}
{% step %}
**Install both apps**: make sure the *Klaviyo: Email Marketing & SMS* app and the *Orbe* app are installed in your Shopify store.
{% endstep %}

{% step %}
**Activate the embeds**: open your Theme Editor and, under the App embeds tab, activate both the *Klaviyo Onsite JavaScript Integration* and the *Orbe Geolocation Popup* embeds.
{% endstep %}

{% step %}
**Enable the integration**: once both embeds are active, go back to the Orbe app, open the Integrations tab, and enable the integration with Klaviyo (available for paid plans only).
{% endstep %}

{% step %}
**Test the connection**: you’re all set. Run a quick test to make sure everything’s working smoothly.
{% endstep %}
{% endstepper %}

## How the integration with Orbe works <a href="#klaviyo-orbe-integration" id="klaviyo-orbe-integration"></a>

Orbe connects with Klaviyo through JavaScript and sends each customer’s country and language preferences whenever Klaviyo identifies a visitor on your storefront.

With Klaviyo’s current integration model, user identification now happens only in specific cases, such as when a visitor arrives through a Klaviyo email (with UTM parameters) or when they are logged in to their account.

When Klaviyo identifies a session, Orbe automatically transmits the visitor’s country and language data and links it to the corresponding Klaviyo profile. If the visitor isn’t yet identified, the session remains anonymous until Klaviyo provides an identity, at which point Orbe syncs the preferences immediately.

For example, when a customer clicks a link in an email and lands in your store, the Orbe modal opens in their browser, allowing them to select their preferred country and language. Since their email is already registered, Orbe records these preferences and sends them to Klaviyo, ensuring that all shared data is accurate, compliant, and tied to verified user identities.

<figure><img src="/files/laBNsgB1CzLBX9gqx7NW" alt="" width="375"><figcaption></figcaption></figure>

You can view the recorded data in the Profiles section of the Audience.

{% hint style="info" %}
To increase the number of identified users, configure Orbe to show the popup on every first visit and avoid including a close (“X”) button. This helps capture more user interactions and ensures preferences are stored and ready to sync once Klaviyo recognizes the visitor.
{% endhint %}

## Limitations

Due to Klaviyo’s new Shopify Web Pixel (Sandbox) system, user identification on the storefront now happens less frequently. Orbe continues to send data correctly, but only when Klaviyo identifies the visitor. This means that anonymous sessions cannot be linked to an email address until Klaviyo provides the identification event.

Additionally, Orbe does not create customer metafields in Shopify: those belong to Klaviyo. Orbe only sends the country and language properties, while Klaviyo decides when and how to store them in each profile.

{% hint style="warning" %}
Make sure Shopify’s automatic redirection is disabled. This ensures customers always interact with Orbe’s popup instead of being redirected automatically by Shopify.
{% endhint %}

## Why do you need this functionality? <a href="#why" id="why"></a>

If you send campaigns to customers in many countries, you do not need to build a different product URL for every country. Add the `country` parameter to your Klaviyo links so each visitor lands in the right country experience from the first click.

### Use the country parameter

Use `?country=XX`, where `XX` is the country code the storefront should load:

{% code title="Campaign URL" overflow="wrap" %}

```
https://your-store.com/products/example?country=GB
```

{% endcode %}

When a customer clicks a link with this parameter:

* **Country experience:** the storefront loads the right country directly.
* **Visitor preference:** Orbe saves that country for the visitor.
* **Popup behavior:** the geolocation popup does not need to appear in that flow.

If your URL already includes another parameter, use `&country=` instead of `?country=`.

### Build it dynamically in Klaviyo

In Klaviyo, use an `if` condition to add the country stored by Orbe. If that property is not available, fall back to Klaviyo's `$locale_country` property. If neither property is available, do not add the `country` parameter.

{% code title="Klaviyo campaign URL" overflow="wrap" %}

```django
https://your-store.com/products/example{% if person|lookup:'Country (Orbe)' %}?country={{ person|lookup:'Country (Orbe)' }}{% elif person|lookup:'$locale_country' %}?country={{ person|lookup:'$locale_country' }}{% else %}{% endif %}
```

{% endcode %}

Use `Country (Orbe)` first: it is already prepared for this parameter. `$locale_country` is also a valid fallback when available. If you use another Klaviyo property, make sure it uses the same country code format.

## FAQs

<details>

<summary>Why don’t I see the Orbe properties in Klaviyo?</summary>

This usually means Klaviyo didn’t identify the visitor during their session. Orbe sends country and language preferences only when Klaviyo’s `isIdentified` function is active. If Klaviyo doesn’t recognize the user (for example, they browse anonymously without being logged in or without coming from a tracked Klaviyo email), the data can’t be associated with their profile.

</details>

<details>

<summary>In which situations does Klaviyo identify users?</summary>

Klaviyo now identifies visitors only in specific cases:

* When they click a link from a Klaviyo email (with UTM parameters);
* When they are logged into their customer account;
* When Klaviyo explicitly identifies them in the frontend using `klaviyo.identify;`

If none of these conditions occur, Klaviyo won’t link the session to a known email address, and Orbe can’t send the properties.

</details>

<details>

<summary>Can Orbe associate anonymous visitors with emails?</summary>

No. For privacy and GDPR compliance, Orbe never stores or links user emails. The identification is entirely handled by Klaviyo. Once Klaviyo recognizes a user, Orbe automatically sends their country and language preferences.

</details>

<details>

<summary>Does Orbe create customer metafields in Shopify?</summary>

No. Orbe sends country and language properties to Klaviyo, where they appear as `Country (Orbe)` and `Language (Orbe)` in the user’s profile.

Klaviyo can then sync those custom profile properties back to Shopify as customer metafields if you enable it in Klaviyo’s Shopify integration settings. In Klaviyo, go to the **To Shopify** sync settings, enable profile and custom property sync, and select the Orbe properties you want to send to Shopify.

When this sync is enabled, Klaviyo creates the metafield definitions in Shopify and updates the corresponding customer values. This is managed by Klaviyo, not by Orbe. You can learn more in [Klaviyo’s Shopify sync documentation](https://help.klaviyo.com/hc/en-us/articles/360030919351).

</details>

<details>

<summary>Why do some users have Orbe properties while others don’t?</summary>

This depends entirely on whether Klaviyo identified those users. If the user visited your store anonymously or never interacted with the Orbe popup or selector, no preferences can be sent.

{% hint style="info" %}
To increase the number of identified profiles, configure Orbe to show the popup on the **first visit** for all users, and avoid adding a close (“X”) button so visitors are encouraged to interact and confirm their preferences.
{% endhint %}

</details>


# Global-e

Integration of Orbe with Global-e Native

{% hint style="success" %}
Orbe is an official Global-e partner. Orbe Geolocation is fully compatible with Global-e stores.
{% endhint %}

Orbe and Global-e work closely to help Shopify merchants deliver a clear, local buying experience across markets.

Global-e powers fiscal compliance, duties, and international shipping in Shopify through Global-e Native and Shopify Markets.

Orbe Geolocation complements that setup by ensuring each international visitor lands in the right country and language experience from the first visit, and stays in the correct experience throughout the buying journey.

## FAQs

<details>

<summary>How does Orbe integrate with Global-e Native?</summary>

Orbe integrates natively with Global-e Native if you have Orbe installed on your Shopify store. This seamless integration enables the synchronization of all your markets' data across all connected stores.

</details>

<details>

<summary>What happens if Global-e makes changes to my market settings?</summary>

If Global-e has made any changes in your market settings, there's no need to worry.

Simply click Orbe's "Refresh data" button to update those changes in your Orbe configuration. For a step-by-step guide, please refer to [Refresh data](/general/refresh-data).

If you don't see all your available countries after that, don't hesitate to [contact our support team](mailto:support@orbe.app). We're committed to assisting you.

</details>

<details>

<summary>Is the integration between Orbe and Global-e compatible with all Shopify stores?</summary>

Yes. Orbe Geolocation is fully compatible with Shopify stores using Global-e. As an official Global-e partner, we've built this integration to work reliably within Global-e Native and Shopify Markets setups.

</details>

<details>

<summary>What is Automatic Redirection by Global-e?</summary>

Global-e's automatic redirection feature redirects users based on their IP. While this automatic redirection feature might be appealing to some merchants, it's not recommended: [FAQs](/before-starting/faqs#why-a-popup-why-not-automatically-redirection)

Orbe will automatically redirect your users in their subsequent visits after giving you consent on their first visit. This approach offers users more flexibility to select their country preferences and language, creating a better international customer experience.

</details>

<details>

<summary>How do I disable the automatic redirection from Global-e?</summary>

{% hint style="warning" %}
This quick tutorial guides how to use a third-party app and is intended for **informational purposes only**.

Orbe does not have direct control over or support Global-e's functionalities.

We strongly recommend contacting your Global-e support team, who have the expertise to assist you in understanding and managing this feature.
{% endhint %}

Here's how you can disable this feature:

1. **Log into your Global-e Crossborder app on Shopify:**

   <figure><img src="/files/BywnEiJDtOBcZJItQRte" alt=""><figcaption></figcaption></figure>
2. **Go to&#x20;*****Settings*****:**

   <figure><img src="/files/QhvQkgjGv5nsShz9xJiw" alt=""><figcaption></figcaption></figure>
3. **Find and toggle off the automatic redirection option:**

   <figure><img src="/files/uS6AsdHRAvitFwbEPeB9" alt=""><figcaption></figcaption></figure>
4. **Save the changes**

</details>


# Connectif

Integration of Orbe with Connectif

{% hint style="info" %}
You can also find the integration steps in the [official Connectif documentation](https://support.connectif.ai/hc/en-us/articles/18793819923612-Integration-with-Orbe-App).
{% endhint %}

[Connectif](https://connectif.ai/) is an email and marketing automation platform. This integration allows you to send your customers' country and language preferences to each Connectif profile, enhancing their customer experience with more relevant content based on their country and language preferences.

## What does this integration do?

The Orbe integration with [Connectif](https://connectif.ai/) allows you to enrich your customer profiles with their country and language preference data. This means you can use Orbe’s data on Connectif to:

* Send emails in the user's preferred language.
* Localize your communication based on your customer's country.
* Segment your audience based on location preferences such as country, region, or city.

### How it works?

Orbe stores the user's **preferred country and language** anonymously. When a user selects their shopping experience (country and language) and provides consent, Orbe sends this information to Connectif as an event.

Connectif is responsible for **identifying the user** when possible. This typically happens when the user makes a purchase, signs up for a newsletter or clicks on an email and visits the website. Once Connectif successfully identifies the user, it **merges the session data** with their profile, storing country and language preferences as user attributes.

Orbe **never collects or processes personal information,** such as email addresses or customer identities. The integration is **completely secure and anonymous**, ensuring that all data belongs exclusively to the merchant, with no external access or third-party control.

### What data does Orbe sync with Connectif?

Orbe enables you to receive the following data in your Connectif customer profiles:

* `Country`**:** The country the user selected in Orbe where they want to receive their order and experience your store.
* `Language`: The language the user selected in Orbe to view the store and receive communications.
* `Region`: The user’s detected region based on their current location.
* `City`: The user’s detected city based on their current location.

These data points are only sent **after the user provides consent** in Orbe and selects their shopping experience (country and language).

{% hint style="warning" %}
The `Country` may differ from `Region` and `City` because the user can be physically in one country but choose to shop in another. The **user explicitly selects** the preferred `Country` and prefered `Language`, while `Region` and `City` are detected **based on their real-time location**.
{% endhint %}

## How to enable it

### 1. Create the integration in Connectif

Follow this [tutorial in your Connectif account](https://support.connectif.ai/hc/en-us/articles/18793819923612-Integration-with-Orbe-App#h_01H95VNEBAM599KADASP56TGTE).

### 2. Enable Connectif on Orbe

Once you've set up the integration in Connectif, navigate to the [Integrations tab inside Orbe](https://admin.shopify.com/apps/300c7396da3de51b6c2a5df448979f2a/integrations) and enable it:

<figure><img src="/files/aadCbasVydYx6C5AGP3s" alt=""><figcaption></figcaption></figure>

***


# Hreflang Manager

{% hint style="success" %}
Orbe has an exclusive partnership with another 3rd party app: [**Hreflang Manager**](https://apps.shopify.com/hreflang-manager?utm_source=partners\&utm_medium=help_center\&utm_campaign=orbe_geolocation_app\&utm_term=-20%25)
{% endhint %}

When you operate **multiple Shopify stores** catering to different countries or regions, ensuring that your customers are directed to the correct version of your website based on their location and language preference is crucial. This is where hreflang tags come into play.

## What Are Hreflang Tags?

Hreflang tags are snippets of HTML code that tell search engines like Google which language you are using on a specific page, so the search engines can serve that result to users searching in that language. This is especially important for businesses that have multiple international stores, ensuring that users are directed to the store most relevant to their region and language.

Google's documentation on [managing multi-regional and multilingual sites](https://developers.google.com/search/docs/specialty/international/localized-versions) offers comprehensive insights into the importance of correctly implementing hreflang tags.

## Shopify and Hreflang Tags

Shopify supports international selling and has its own system for managing hreflang tags, as detailed in their guide on [setting up international domains](https://help.shopify.com/en/manual/markets/international-domains/setting-up-unique-urls/hreflang-tags). However, Shopify's built-in solution does not cover all the complexities when you run multiple expansion stores for different markets.

## The solution: Using Hreflang Manager app

<figure><img src="/files/x0iW7SU8NVfanpMqGIXa" alt=""><figcaption></figcaption></figure>

To ensure your Hreflang tags are correctly implemented and managed across your multiple Shopify stores, we recommend using the [Hreflang Manager app](https://apps.shopify.com/hreflang-manager?utm_source=partners\&utm_medium=help_center\&utm_campaign=orbe_geolocation_app\&utm_term=-20%25). This app simplifies the process, ensuring your stores are properly indexed by Google and other search engines, enhancing your global SEO efforts.

{% hint style="success" %}

#### Special Offer for Orbe Users

As a valued user of Orbe, you're entitled to a **20% discount** on Hreflang Manager. To avail of this offer, you can directly mention that you're coming from Orbe when contacting [Hreflang Manager](https://apps.shopify.com/hreflang-manager?utm_source=partners\&utm_medium=help_center\&utm_campaign=orbe_geolocation_app\&utm_term=-20%25) or reach out to our support for an introduction.
{% endhint %}

Properly managing hreflang tags is vital for multi-regional Shopify stores. It ensures that your customers have a localized shopping experience, which can significantly improve your store's SEO and customer satisfaction. With the help of Hreflang Manager, you can streamline this process and focus on growing your international presence.

For further assistance or to get your discount, don't hesitate to contact our support team.


# Announcement Bar

How to create a dynamic Marketing Announcement Bar which changes for each market using Orbe and Translate & Adapt

Welcome to this tutorial on how to create a dynamic announcement bar for your store using Translate and Adapt and Orbe. This announcement bar can be customized to display different messages and personalize the shopping experience based on the country.

For example, let's say you offer free shipping up to a certain amount in different countries. With the dynamic announcement bar, you can display a message specific to each country's shipping threshold, letting your customers know exactly how much more they need to spend to qualify for free shipping. Or perhaps in some countries, the price includes duties and taxes, while in others, they will be added in the checkout. You can use the announcement bar to display this information, ensuring that your customers are fully informed about their purchases.

In this tutorial, we'll show you how to set up the dynamic announcement bar step by step, so you can start using this powerful tool to improve your store's customer experience. So, let's get started!

{% embed url="<https://www.loom.com/share/8f18b62431d24efda2c77fd795bf38ae>" %}


# Uninstall Orbe

## **Before saying goodbye...**

Most of the times, shop owners delete an app for one of the following reasons:

* trouble setting it up
* free trial period is almost ending
* reach for support

That is why our customer support team is available from Monday to Friday. Don't hesitate to write to us about anything that's on your mind, and we'll come back with an answer as soon as possible.

## If you have decided to say goodbye...

We are sorry that Orbe wasn't the perfect fit for your store. To uninstall Orbe and cancel the subscription, **you need to access the** [**Apps section of your Shopify admin**](https://www.shopify.com/admin/apps) **and delete the app.**

Just like with all Shopify apps, if you see ours still live on your store after refreshing a couple of times, it's because Shopify is using browser caching, and their page still contains our script. Just perform a hard refresh - CTRL + SHIFT + R or CMD + SHIFT + R (on Mac) and the cache is cleared.

After the Orbe app is uninstalled, **you don't need to remove any unused code snippets from your theme template.**

**If you have a payment plan, don't worry.** We automatically cancel the subscription when you uninstall the application.


# Getting started

Getting started with Orbe’s geolocation popup is fast and easy: it takes **less than 10 minutes** using the **Shopify Theme Editor**.

Orbe uses **Shopify's App Embed technology**, meaning:

* no extra code is added to your theme
* the integration is seamless
* ensuring your store performance remains unaffected

### Before you begin

We recommend reading these two short tutorials for full context:

* [How it works](/before-starting/how-it-works): understand why the popup appears when international customers land on the wrong shopping experience.
* [**Why we use consent**](/before-starting/faqs#is-it-possible-to-implement-automatic-redirections-instead-of-showing-a-popup): learn why we avoid automatic redirects on first visits, and how we handle user consent.

Ready? Let’s walk through the exact steps to customize the popup and activate geolocation on your Shopify store:

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>How to setup</strong></td><td>Configure and enable your welcome popup in the Shopify theme editor.</td><td><a href="/files/KEPDq60DOwRaomfZoVCy">/files/KEPDq60DOwRaomfZoVCy</a></td><td><a href="/pages/L2ydykzas2rWmGSapJgo">/pages/L2ydykzas2rWmGSapJgo</a></td></tr><tr><td><strong>How to customize</strong></td><td>The style, colors, and content of your welcome popup</td><td><a href="/files/ae0PKLOks23Hl0ikmoue">/files/ae0PKLOks23Hl0ikmoue</a></td><td><a href="/pages/z3neuFLLDn2hsLgVzg5H">/pages/z3neuFLLDn2hsLgVzg5H</a></td></tr></tbody></table>


# How to set up

To get started, open Orbe from your Shopify admin and click on **Customize popup**. This will take you directly to the **Shopify Theme Editor**, where you can manage how the popup appears on your storefront.

Once inside, make sure to activate the **App Embed** feature in the left-hand panel.

### Test mode

The **Test Mode** lets you preview and style the popup without publishing any changes live. While Test Mode is on, the popup will only be visible to you, allowing you to experiment safely with the design and content before going live.

<figure><img src="/files/wpfsSxqGbyCGQHeNUrfc" alt="" width="375"><figcaption></figcaption></figure>

{% hint style="warning" %}
**Remember:** once you’ve finished configuring, make sure to **disable Test Mode** so the popup no longer appears in preview. It is only a checkbox while you want to customize the popup in the Theme Editor.
{% endhint %}

### Enable the welcome popup <a href="#enable" id="enable"></a>

Watch this **quick tutorial** to see exactly how to set it up in just one minute.

{% embed url="<https://www.loom.com/share/ea2e7671b5364d5ab9d164b858d99951?sid=63c2159b-8357-4b9c-ae5f-eaa19d9413da>" %}


# How to customize

Orbe’s popup is fully flexible, from content and style to behavior and localization. Below, you’ll find all the settings you can adjust to make it perfectly match your brand and guide users smoothly to the right shopping experience.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Content</strong></td><td>How to customize text, flags, currency, and images.</td><td><a href="/files/PU5nz2EIbibJ9mbHbczt">/files/PU5nz2EIbibJ9mbHbczt</a></td><td><a href="/pages/qL3fwm91zAbu5I51xg2P">/pages/qL3fwm91zAbu5I51xg2P</a></td></tr><tr><td><strong>Style</strong></td><td>How to adjust fonts, colors, button styles, and layout.</td><td><a href="/files/fd0BZvehrudPIP5VjFbc">/files/fd0BZvehrudPIP5VjFbc</a></td><td><a href="/pages/Sx2DLLfCpw7TrPJ7K80O">/pages/Sx2DLLfCpw7TrPJ7K80O</a></td></tr></tbody></table>


# Content

Control every piece of text and information your customers see, from the popup title to the country, language, and currency they’re shown.

This section lets you tailor the message, behavior, and logic of the popup to ensure it feels relevant, helpful, and aligned with your brand’s voice.

## **Close button**

Enabling this option allows customers to manually close the geolocation popup. If they do, they’ll stay in the shopping experience they initially landed in, and **no redirection** will occur.

If the popup is closed without selecting a country or market, Orbe will **save that decision for 7 days**, so the popup won’t show again during that time.

{% hint style="info" %}
To ensure customers are always guided to the correct version of your store, we recommend keeping this option disabled. With the close button turned off, users will continue by clicking “Shop now”, and Orbe will automatically preselect their country based on IP.
{% endhint %}

<div data-full-width="false"><figure><img src="/files/hT7l17P2Oy83LQsCCTD9" alt="" width="375"><figcaption></figcaption></figure></div>

{% hint style="info" %}
**Accessibility tip**: while you can customize many aspects of the modal, we strongly recommend not hiding the 'Shop now' button. Doing so would trigger an automatic redirection as soon as the country is selected, resulting in an unannounced context change for users relying on screen readers (WCAG 2.2 – 3.2.2 On Input, Level A).
{% endhint %}

## **Recommended country flag**

Enable this option to show the **flag of the customer’s current location** in the popup, a small detail that adds a more localized and familiar touch.

For example, a visitor from Spain will see the Spanish flag displayed next to the country name.

You can choose the shape that best fits your design: rounded, square, or circular.

<figure><img src="/files/9dvYN0iRKbvVPv8Zrkrk" alt="" width="375"><figcaption></figcaption></figure>

## **Market currency**

This setting controls how currency details appear in the **country selector**. By default, only the country name is shown, but you can choose to include currency information to make things clearer for your customers.

You can display:

* the **`{currency_code}`** (e.g. United States (USD))
* the **`{currency_symbol}`** (e.g. United States ($))
* or **both** (e.g. United States (USD $))

You can also combine this with the **country flag** for a more informative and localized display.

<figure><img src="/files/MbqOWbrGzZ9eXzxqM4pE" alt="" width="375"><figcaption></figcaption></figure>

## **Languages**

If your store supports **multiple languages**, we recommend enabling the **language selector**. This allows customers to easily switch to their preferred language directly from the popup, improving clarity and reducing friction.

*Want to make the most of this feature? Check out our Language Selector tutorial for best practices.*

<figure><img src="/files/cOMXoqsXiPtuVpEvaBpL" alt="" width="375"><figcaption></figcaption></figure>

## **Country search**

Make it easier for users to find their country by letting them **search as they type**. This is especially helpful if you sell in **many markets**. It saves time and improves the overall experience.

<figure><img src="/files/z9ZkI3AYm03doUhnDiq3" alt=""><figcaption></figcaption></figure>

## **Title, text, helper text, and button text** <a href="#content" id="content"></a>

You can fully customize the **title**, **body text**, **helper text**, and **button label** shown in the popup. This gives you the flexibility to reflect your brand’s tone of voice or communicate any important details before customers are redirected to the correct shopping experience.

{% hint style="info" %}
Learn [how to translate popup content](https://help.orbe.app/geolocation-popup/translations) into different languages based on the user’s browser settings.
{% endhint %}

<figure><img src="/files/3mltSB4nbj8u6q66XPxh" alt="" width="375"><figcaption></figcaption></figure>

{% hint style="info" %}
**Accessibility tip**: we advise against removing the title text, since it serves as the announcement of the popup for screen readers used by people with visual impairments. You may, however, customize its appearance with custom CSS to better align with your branding while maintaining accessibility. (WCAG 2.2 - 1.3.1 Info and Relationships (Level A), 2.4.6 Headings and Labels (Level AA), 4.1.2 Name, Role, Value, (Level A)).
{% endhint %}

## **Fallback text**

This text will appear **in place of the popup title** for customers located in countries where your store doesn’t offer shipping. It’s a simple way to set clear expectations and avoid confusion when no shopping experience is available for a given region.

You can utilize the dynamic variables provided to personalize the message for each country:

* **`{country}`***: displays the customer's country. Example: Spain*
* **`{currency_code}`**: *displays the country's currency code. Example: EUR*
* **`{currency_symbol}`**: *displays the country's currency symbol. Example: €*

For instance, if your customer is in Spain and you want the title to read "We ship to Spain", you can achieve that using this variable.

{% hint style="info" %}
Learn [how to translate popup content](https://help.orbe.app/geolocation-popup/translations#fallback-translation-for-unsupported-countries) into different languages based on the user’s browser settings.
{% endhint %}

<figure><img src="/files/StaK82Anenbu8Pqx1EDt" alt="" width="375"><figcaption></figcaption></figure>

## **Background image**

You can add a custom image to your popup to make it more visually engaging. Choose whether the image appears on the left or right side, depending on your layout preferences.

To keep the design clean, we recommend keeping the helper text under 200 characters when using an image.

Recommended sizes:

* desktop: 408 × 680 px
* mobile: 342 × 363 px

<figure><img src="/files/8Ah4hCyZSM45eJNOJdoP" alt="" width="375"><figcaption></figcaption></figure>


# Style

Match the look and feel of the popup with your storefront design. No coding required.

From buttons to colors, these settings let you control the visual experience and make the popup feel fully integrated with your brand.

## **Button and selector style**

Choose between **rounded** or **squared** corners to better match your store’s design aesthetic.

<figure><img src="/files/oEStQbmyct38Xfl1uIoA" alt="" width="375"><figcaption></figcaption></figure>

## **Selector type**

Decide how visible you want the selector to be: pick between **outlined**, **underlined**, or a minimal look with **no lines**.

<figure><img src="/files/WPnHjurg9B9oCxm60Tzv" alt="" width="375"><figcaption></figcaption></figure>

## **Button alignment**

Position your action button wherever it works best: **left**, **center**, **right**, or stretch it to be **full-width**.

<figure><img src="/files/R58UxOXf8dAYnrVRzY91" alt="" width="375"><figcaption></figcaption></figure>

## **Font size**

Fine-tune the popup’s appearance by setting the **title and body text sizes** in pixels. Simple and precise.

<figure><img src="/files/kWZ5Z4H0DzREq4A1xY34" alt="" width="375"><figcaption></figcaption></figure>

## **Blurred background**

Hide product prices and content until the customer selects their shopping experience. This feature is ideal if your store has region-specific pricing, as it prevents price confusion and keeps your presentation consistent across markets.

A smart way to keep sensitive info hidden until customers land in the right version of your store.

<figure><img src="/files/H8qnp4XMiaoS2As3Nc1X" alt=""><figcaption></figcaption></figure>

## **Colors**

Make the popup feel native to your storefront by **customizing its colors** to match your brand identity.

<figure><img src="/files/iNbHObz3UEm8t0YcABba" alt="" width="375"><figcaption></figcaption></figure>

{% hint style="info" %}
**Accessibility tip**: when setting modal colors, especially the button, make sure it’s easy to see for everyone. The button color should contrast at least **3:1** with the modal background (WCAG 2.2 – 1.4.11 Non-text Contrast, Level AA), and the button text should contrast at least **4.5:1** with the button color (WCAG 2.2 – 1.4.3 Contrast (Minimum), Level AA).
{% endhint %}


# Translations

Welcome your customers in their preferred browser language

{% hint style="info" %}
Exclusive feature available in the **Advanced** and **Plus** plans.
{% endhint %}

You should use a third-party translation app to translate your store, but not the Orbe app embed.

Orbe has its own technology to translate its popup because Orbe is designed to **show its geolocation popups** when customers **are in the wrong localized experience**.

For example, if a customer is browsing your store in English but their browser is set to Spanish, and you have a Spanish experience available, Orbe will automatically display the message in Spanish.

<figure><img src="/files/sg7ySVNeQ4Xw5QreAwTJ" alt=""><figcaption></figcaption></figure>

This ensures that Orbe will guide the customer to **the right country experience** in their **preferred language**. You have the flexibility to customize the popup in multiple languages, ensuring that your users receive the best recommendation experience based on their browser language.

## How does it work?

After configuring the popup in multiple languages, if a user's browser language matches one available, that version will be displayed, considering it as the user's preferred language. Here are some examples:

* If your store has English, French, and Spanish, and a user's browser is set to Spanish, the popup will be displayed in Spanish, even if they visit from a United Kingdom IP address.
* If the browser is in a language not available in your store, the popup will be shown in the default language you set up in the Orbe editor.

This tutorial will walk you through the process, explaining how Orbe functions and guiding you on how to activate the multilingual popup.

## Translate your welcome popup

{% hint style="info" %}
You can customize the popup **in the languages already configured in your Shopify store**. If a language is missing, it won't appear in Orbe’s options, so make sure all required languages are added to your Shopify settings.
{% endhint %}

Translating your Orbe popup is simple and effective. Check out this video tutorial on how to translate your popup:

{% embed url="<https://www.loom.com/share/f493d95357c14f2aa642c7d8cfcf83a7?sid=fc3f216d-960a-44f2-af94-3242cef1df64>" %}

### **Dynamic Variables**

Orbe also allows you to include dynamic variables that adapt to the user's location and preferences:

* **{country}**: Shows the customer’s country (e.g., Spain)
* **{currency\_code}**: Displays the country’s currency code (e.g., EUR)
* **{currency\_symbol}**: Displays the currency symbol (e.g., €)

### **Pre-fill templates**

<figure><img src="/files/1YzFLGdrQPr0KeI5Cn7w" alt=""><figcaption></figcaption></figure>

You can easily use these templates by clicking on "Use a Template." These templates are fully customizable, allowing you to adjust the message as needed to match your brand's voice.

Orbe provides pre-set templates for the following languages:

* English
* French
* Spanish
* Italian
* German
* Portuguese
* Swedish

You'll need to manually input the translation for languages not covered by our templates.

## Customize your welcome popup by country

{% hint style="info" %}
This feature is available only for **Plus** and **Enterprise** plans.
{% endhint %}

Orbe allows you to adapt the content of the welcome popup based on the customer’s country. This feature gives you the flexibility to display specific messages, such as:

* The **shipping threshold** for their country
* Their **local payment method** available at checkout
* **Taxes** and **duties** information
* Custom messages or offers

By doing so, you can welcome your international users, enhance their experience, and **build trust** from the very first interaction.

<figure><img src="/files/Im3JVGsdw8gfprHOztW2" alt=""><figcaption></figcaption></figure>

### How does it work?

Once you're on the Plus or Enterprise plan, navigate to the **"Translations"** section. There, you’ll find a new selector called **"Adaptations"** located next to the "Language" dropdown. This allows you to create a version of the popup that displays **country-specific content** while still respecting the user's browser language.

When international visitors land on your store for the first time, Orbe will display a welcome popup with the customized information you’ve tailored for their location and language. For example:

* You can create unique content for **Canada** in both **Spanish** and **French**. The popup will prioritize the language of the customer's browser but adjust based on the country.
* If there’s no country-specific translation, the default language version will be shown.

Customization is done manually per country, but you can easily use the `Apply to multiple countries` option to manage multiple locations with the same shipping or payment conditions.

Dynamic variables like `{country}`, `{currency_symbol}`, and `{currency_code}` are available to ensure flexibility.

Check out this tutorial to learn how to use it:

{% embed url="<https://www.loom.com/share/4f5b07397d4e4600a24399fe4175a20b?sid=9b5c8364-a40e-4fc6-b826-33a8530d43d8>" %}

## Fallback translation for unsupported countries

In cases where a customer visits from a country where you don’t sell, Orbe allows you to fully customize the popup with a fallback translation. This means that, **for unsupported regions**, you can **change all popup texts to notify the customer that you don’t ship to their location** and provide a list of alternative countries where they can shop.

You can set a specific fallback message for each available language, ensuring that even users from unsupported regions receive clear guidance.

Watch this video to see how the fallback feature works and how to set it up:

{% embed url="<https://www.loom.com/share/5a5155fd4ccc481f8603f5d2e9655e05>" %}

## Preview your translations <a href="#preview" id="preview"></a>

Before saving any changes, you can preview exactly how the popup will look with your translations applied. This lets you verify the copy, formatting, and dynamic variables (like `{country}` or `{currency_symbol}`) before publishing any changes.

To use it, make your edits in the Translations editor and click **Preview**. A live preview of the popup will appear showing how it will be displayed to your visitors.

{% embed url="<https://www.loom.com/share/77c2eca8d4e044359915362f428498f1>" %}


# Common issues

How to confirm if Orbe is working?

Often, some brands contact our support team to ask if Orbe is working. In this tutorial, we explain the three main reasons and how you can check them:

1. Orbe is working, but you cannot see the popup
2. Orbe works, but the popup keeps reappearing repeatedly
3. Orbe works, but Shopify's Automatic Redirection is on
4. The test mode doesn't work
5. Orbe doesn't change the currency per country

## Orbe works, but you cannot see the popup

Orbe syncs with the Shopify settings to know in which countries you are selling. It creates a custom-designed popup to make recommendations to customers depending on their geographic location and preferred browser language. When an international user visits your store, Orbe will recommend moving them to their localised experience. In subsequent visits, it will automatically redirect them to that experience. Some examples of use:

* When a US user visits the US experience: as the user is in the correct localised experience, Orbe will not bother them.
* When a French user visits the US experience: the Orbe popup will show up and recommend the French experience. If, in the future, this French user goes again to the US experience, it will automatically be redirected to the French experience.

Because of this first example, when some brands install Orbe, the country coincides between their primary market and the IP address where they are testing it. That's why Orbe doesn't bother them.

{% hint style="info" %}
If you want to test Orbe in this situation, add your domain followed by ***?showOrbe***. For example, <https://mushdesk.com/?showOrbe>
{% endhint %}

<figure><img src="/files/uvkJOfoLc5EjOKwdMJ2V" alt=""><figcaption></figcaption></figure>

## Orbe works, but Shopify's Automatic Redirection is on

Merchants often find themselves with the Automatic Redirection feature enabled by default on their Shopify stores. However, it's essential to note that Shopify itself acknowledges in its documentation that this option can be detrimental to your SEO efforts. It hinders web crawlers from effectively indexing your localized shopping experiences and ranking them on Google and other search engines.

<figure><img src="/files/QkVm30Z4B2OX8YjmKfHt" alt=""><figcaption></figcaption></figure>

Additionally, it's worth mentioning that implementing automatic redirects without obtaining user consent may lead to non-compliance with data protection laws worldwide.

In contrast, Orbe offers automatic redirects, but with a crucial distinction – only after obtaining the user's consent. This approach ensures that we are both SEO-friendly and fully compliant with global data protection regulations.

Likewise, in cases of a subfolder domain strategy (e.g., <https://orbe.app/es-es> and <https://orbe.app/fr-fr>) or a multi-language website within a single domain (e.g., [https://orbe.app/es ](https://orbe.app/es)and <https://orbe.app/fr>), automatic redirection only works on the user's first visit. Without a geolocation solution like Orbe, returning users may experience incorrect shopping pages.

To disable the automatic redirect feature provided by Shopify, simply follow these steps:"

<figure><img src="/files/dUsnzlcGCbv5Rnm6ZUYy" alt=""><figcaption></figcaption></figure>

## The test mode doesn't work.

A few times, in the editor, some brands have activated the app embed and activated the test mode. However, the popup doesn't show up.

In these cases, these brands have contacted our support team, and we have always identified the same problem: there is an **error in the Shopify app blocks** for any of the following reasons which **affect Orbe but also your store performance:**

1. You have a label in the theme.liquid without closing. For example, \</head>.
2. The object {{ content\_for\_header }} o {{ content\_for\_layout }} is missing.

If you don't find the problem, don't hesitate to ask our team. We will be glad to help.

## Orbe doesn't change the currency per country

Please note that Orbe is not a currency conversion app. Instead, Orbe is a geolocation app that guides users to the shopping experience that corresponds to their location and preferences. Therefore, we do not perform currency conversions.

The setup for local currency sales is handled directly through Shopify Markets and is only available in countries where Shopify Payments is enabled. This means that brands located in countries where Shopify Payments is not available will need to seek an independent alternative to Orbe for currency conversions.

{% hint style="info" %}
If you want to check the list of countries where Shopify Payments is available, we recommend visiting the [Shopify Help Center](https://help.shopify.com/en/manual/payments/shopify-payments/supported-countries).
{% endhint %}

If Shopify Payments is available in your country, you can activate local currency sales as demonstrated below:

<figure><img src="/files/5LLGs4lIPLmOowF7Zklw" alt=""><figcaption></figcaption></figure>

## Currency Display Issues for Local Currencies

Orbe serves as a geolocation application that redirects users to the appropriate shopping experience based on their location and preferences. Brands craft their diverse shopping experiences within Shopify Markets, where they customize products, prices, currencies, languages, and content.

If Orbe redirects you to a country where products are sold in the store's primary currency instead of the local currency, the initial step is to verify whether Local Currencies have been activated in the relevant market. For example, if you sell in Mexico and it's included in the "International" market, you need to navigate to the "International" market settings and ensure that the "Local currencies" option is enabled.

<figure><img src="/files/4Dk0PFVbXt7A7zPGWr8j" alt=""><figcaption></figcaption></figure>

If enabling this option doesn't resolve the issue, it's crucial to check if the country in question has a volatile currency, according to Shopify. To check volatile currencies, it's recommended to refer to the tutorial in the [Shopify Help Center](https://help.shopify.com/en/manual/markets/pricing/volatile-currencies).

In the case of the Mexican peso being a volatile currency, its fluctuation can significantly impact your business. Under such circumstances, if you still wish to enable payments in Mexican pesos, you'll need to create a dedicated market specifically for Mexico, where you manually indicate that you want to sell in Mexican pesos.

<figure><img src="/files/96bmFXVgccRf9F4ViWmt" alt=""><figcaption></figcaption></figure>

## Why doesn’t Orbe switch to the default language of a new country when I change countries?

Orbe is a native app **built for Shopify International**, seamlessly integrated with Shopify’s country and language selectors. This means that Orbe does not control the language behavior—this is the standard Shopify response when using their country and language selection tools.

When you switch countries without explicitly selecting a language, Shopify will **keep the current language** if **it’s available** in the new country.

* If the current language exists in the new country’s setup, Shopify will display that country in the same language.
* If the current language isn’t available, Shopify will default to the primary language of the new country’s market, which is the expected behavior.

**Example:**

Imagine you have the following configuration:

* **Market Germany**: Available languages - German (default) and English (secondary).
* **Market France**: Available languages - French (default) and English (secondary).

If a user lands in Germany and is browsing in English, and they switch to France using only the country selector, they will see the French site in English, as English is available in France. However, if they are browsing in Germany in German and switch to France, they will see the French site in French (the default for France) because there is no German language option for France.

To ensure users always see the correct language for each country, we **strongly recommend enabling the language switcher in Orbe** whenever you have multiple languages. This way, users can choose both country and language, providing a more accurate and seamless browsing experience.

## Orbe is not working properly on Instagram browser

If you are a staff user or store owner on your Shopify store and you want to access your store on Instagram or any other social media platform from different locations, you can do so.

However, you must note that your users should not change their location using a VPN or test from different locations.

If you want to **replicate the experience of a particular user** in a specific country, you must follow these steps on Instagram:

1. Access to the Instagram Browser > Click on settings (3 dots at the right top) > Browser settings > Clear cookies and cache
2. Go to your VPN and change your location
3. Access again

See exactly how in this quick video testing it on an actual Orbe merchant store:

{% embed url="<https://www.loom.com/share/929c71153fda40f3bdd8f0b44d9832fc?sid=8ca59317-c1a3-4cf1-ab4f-22fd4b72d359>" %}


# Overview

Orbe’s geolocation technology is designed to remember your **customers’ country and language preferences**. This ensures that once a customer selects their preferences, they won’t be prompted again on future visits. Additionally, if a customer ends up on the wrong country version of your site, Orbe will automatically guide them back to the correct experience based on their saved preferences.

To keep these preferences updated, it’s essential to **offer customers a way to select their country** (and language, if applicable) with **a selector that’s integrated with Orbe**. This integration ensures that any changes are stored properly and applied in future visits.

## **Why integration with Orbe is important?**

If your selector isn’t integrated with Orbe, customer changes **won’t be saved**, and Orbe may keep redirecting users based on old preferences. Orbe relies on these preferences for:

* **Automatic redirection** to the right experience
* **GDPR-compliant** consent storage and **SEO-safe** redirection
* **Accurate data sync** with tools like Klaviyo

If the selector doesn’t update Orbe, these systems break and the user experience becomes **inconsistent**.

To avoid this, make sure **your country and language selector is connected to Orbe**. Choose the option that fits your store best:

<table data-column-title-hidden data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td><strong>Geolocation Button</strong></td><td>Opens Orbe’s popup so users can update their country or language.</td><td><a href="/pages/8n5gzdwapHV5rnKQe8IJ">/pages/8n5gzdwapHV5rnKQe8IJ</a></td><td><a href="/files/kVpIvscs4c4LUObMi4Lh">/files/kVpIvscs4c4LUObMi4Lh</a></td></tr><tr><td><strong>Country Selector</strong></td><td>Let users manually switch to another country.</td><td><a href="/pages/r2Vi9gWBeem7C6jVqOlu">/pages/r2Vi9gWBeem7C6jVqOlu</a></td><td><a href="/files/6yh0Mt4BglzONUCRzRRS">/files/6yh0Mt4BglzONUCRzRRS</a></td></tr><tr><td><strong>Language Selector</strong></td><td>Let users manually change their language.</td><td><a href="/pages/5YV9ZuQ1E5G2V6HSOMLp">/pages/5YV9ZuQ1E5G2V6HSOMLp</a></td><td><a href="/files/C7wqzN9ukYk9YvCj7mFd">/files/C7wqzN9ukYk9YvCj7mFd</a></td></tr><tr><td><strong>Modal Selector</strong></td><td>A selector with all country and language options in a modal format.</td><td><a href="/pages/RYZCCtsQlhDgcabByD64#how-to-setup">/pages/RYZCCtsQlhDgcabByD64#how-to-setup</a></td><td><a href="/files/QDxPtMexaSw0t7bpz2Tc">/files/QDxPtMexaSw0t7bpz2Tc</a></td></tr><tr><td><strong>Integrate your selector</strong></td><td>If your theme already includes its own selector, you can integrate it with Orbe (developer required).</td><td><a href="/pages/ABefaBuHR2ZhyxEs406Y">/pages/ABefaBuHR2ZhyxEs406Y</a></td><td><a href="/files/uVnFiFhWFOCAeantM7PQ">/files/uVnFiFhWFOCAeantM7PQ</a></td></tr></tbody></table>


# Geolocation Button

The Geolocation Button is an **app block** that allows you to add a customizable country and language selector anywhere on your Shopify store.

This button enables your customers to **select their preferred country and language**, enhancing their shopping experience by ensuring they see the correct content and currency based on their choices.

{% embed url="<https://www.loom.com/share/5ce17db546a0462587188818bb128d06?sid=997da58f-e78f-4c27-91ad-c21c8ebff76f>" %}

The **Geolocation Button** can open either the **Geolocation Popup** or the **Market Selector modal**.

## How to use it

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>➕ <strong>How to add</strong></td><td>Step-by-step instructions on adding the app block to your Shopify theme.</td><td><a href="/pages/RYZCCtsQlhDgcabByD64#how-to-add">/pages/RYZCCtsQlhDgcabByD64#how-to-add</a></td></tr><tr><td>🌟 <strong>How it works</strong></td><td>Quick start guide to get your Geolocation Button up and running.</td><td><a href="/pages/RYZCCtsQlhDgcabByD64#how-to-setup">/pages/RYZCCtsQlhDgcabByD64#how-to-setup</a></td></tr><tr><td><strong>📍 Selector Placement</strong></td><td>How to position the Geolocation Button anywhere in your theme.</td><td><a href="/pages/bkhYXErQ1PnQMpNfErOs">/pages/bkhYXErQ1PnQMpNfErOs</a></td></tr><tr><td><strong>🎨 Variables</strong></td><td>Customize the button’s appearance to create a personalized look and feel.</td><td><a href="/pages/S8ghNZhCDAgqcWcvIApZ">/pages/S8ghNZhCDAgqcWcvIApZ</a></td></tr><tr><td><strong>⚒️ Custom Code</strong></td><td>Use custom CSS o JavaScript inside the app.</td><td><a href="/pages/qj7m9ofsuOmVYitM2zru">/pages/qj7m9ofsuOmVYitM2zru</a></td></tr></tbody></table>


# How it works

## How to add

If you have a newer Shopify theme compatible with app blocks (any public theme version [after March 2023](https://shopify.dev/changelog/we-are-introducing-sections-liquid-tag-and-section-groups)), you can add the Geolocation Button app block directly to your header or footer using **section groups**.

To add the Geolocation Button, go to the **Shopify Theme Editor**, navigate to your desired section (header or footer), and insert the app block directly.

{% embed url="<https://www.loom.com/share/f410fbdb0f6642358c6d79f71d8f8446?sid=834b954f-2a12-47c6-a037-5da53d6cbc6e>" %}

However, many themes are not compatible with adding **app blocks** in a section that appears in all your theme pages (like the **header** or the **footer** sections).

If that is your case, follow this tutorial:

### **Update your theme to be compatible with App Blocks**

{% embed url="<https://www.loom.com/share/65a8ebd4ce8f4ca0be359a4c9aa3d9a8?sid=86ea5101-5af9-4bc4-a9f7-95736917abb3>" %}

Here’s how to do it:

1. **Edit your theme:** Go to **Online Store > Themes > Edit code** in your Shopify admin.
2. **Check your sections folder.** Look for a section in this folder called `apps.liquid`. If it does not exist, create the file and insert this code:

   ```liquid
   <div>
     {%- for block in section.blocks -%}
       {% render block %}
     {%- endfor -%}
   </div>

   {% schema %}
   {
     "name": "Apps",
     "tag": "section",
     "blocks": [
       {
         "type": "@app"
       }
     ],
     "presets": [
       {
         "name": "Apps"
       }
     ]
   }
   {% endschema %}

   ```
3. **Create a new file.** Insert a new file in the `sections` folder with the name: `app-group.json`. And insert this code:

   ```json
   {
     "type": "aside",
     "name": "Apps",
     "sections": {
       "main": {
         "type": "apps",
         "settings": {
         }
       }
     },
     "order": [
       "main"
     ]
   }
   ```
4. **Edit theme.liquid.** Go the theme.liquid file and insert this after closing the `<body>` tag or after the section `header` / section `footer`.

   ```liquid
   {% sections 'app-group' %}
   ```
5. **Theme Editor.** Click on "Customize" your theme, and you will see a new section called `Apps` only for adding app blocks to your installed apps.

### Your section is not supported in a section group

<figure><img src="/files/tXVcj3STpRESyWIiye66" alt=""><figcaption></figcaption></figure>

If you see a message like **“Section xxx is not supported in section groups”** when trying to add an app block to the header or footer, this is a **theme limitation**.

Some themes disable app sections in certain groups using the `disabled_on` property in the section schema. When `header` or `footer` are included, Shopify won’t allow the app block to be added there.

Example of code that causes this issue:

```json
"disabled_on": {
  "groups": ["header", "footer"]
}
```

#### How to fix it

Edit the section code in your theme and remove the `disabled_on` property from the schema.\
After saving the changes, the app block can be added to the header or footer normally.

## How to setup

### Enable the correct App Embed

The **Geolocation Button** can open either the **Geolocation Popup** or the **Market Selector modal**.

To ensure the Geolocation Button works properly, you need to enable the correct app embed based on your selected option. Otherwise, the button will not function as expected. Follow these steps to set it up:

* If you choose the **Geolocation Popup**, make sure the `Geolocation Popup` app embed is enabled.
* If you select the **Market Selector modal**, ensure the [`Market Selector`](/selectors/market-selector#modal-selector) app embed is enabled with the **Modal** option selected.

This setup is essential for the button to display the correct selector when clicked.

{% embed url="<https://www.loom.com/share/45a000c524b547278c72bd03f5aa8363?sid=17924c65-5e5c-4337-8638-47786dc8f809>" %}

## Learn more about

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Selector Placement</strong></td><td>Learn how to position your selector exactly where you want in your theme.</td><td><a href="/files/RzUsklrBbNZGo2rjxOVW">/files/RzUsklrBbNZGo2rjxOVW</a></td><td><a href="/pages/bkhYXErQ1PnQMpNfErOs">/pages/bkhYXErQ1PnQMpNfErOs</a></td></tr><tr><td><strong>Enable the Market Modal</strong></td><td>Learn how to customize the modal selector to combine it with the Geolocation Button</td><td><a href="/files/QDxPtMexaSw0t7bpz2Tc">/files/QDxPtMexaSw0t7bpz2Tc</a></td><td><a href="/pages/OnaZZjK87dwNMxTsv1Ji#modal-selector">/pages/OnaZZjK87dwNMxTsv1Ji#modal-selector</a></td></tr></tbody></table>


# Selector Placement

The **Selector Position** input in the Geolocation Button app block lets you control exactly where the button will appear within your theme. By specifying a particular container's CSS class or ID, you can place the Geolocation Button precisely where you want it in your store’s layout.

## How to use it

{% embed url="<https://www.loom.com/share/925da472e97e456ba4de1f59d3a4c89d?sid=80024471-df79-4cae-8cea-e92372ba2d60>" %}

In the **Selector Position** field, enter the class or ID of the container where you want the Geolocation Button to appear. Use the format:

* For a CSS ID: `#id-name` (e.g., `#shopify-section-footer`)
* For a CSS class: `.class-name` (e.g., `.header-section`)

{% hint style="info" %}
**Multiple locations**\
If you want the Geolocation Button to appear in multiple locations (for example, in both the header and footer), **you need to duplicate the app block**.

By duplicating the app block and entering a unique class or ID for each position, you have the flexibility to show the selector in multiple places on your site, such as the header, footer, drawer menu or any other section.
{% endhint %}

{% hint style="info" %}
**Accessibility tip**: the Geolocation Button lets users reopen Orbe from anywhere in your store. Make sure its placement isn’t hidden (on desktop or mobile) by other elements like floating buttons (WCAG 2.2 – Focus Not Obscured, Level AA).
{% endhint %}

### How to find the `class` or `ID` using the Browser Inspector

To identify the exact class or ID of the container where you want to place the Geolocation Button, you can use the **Inspector** tool available in most browsers. Here’s how:

1. **Open the Inspector**:
   * Go to your store’s frontend and right-click on the area where you want to place the Geolocation Button.
   * Select **Inspect** (in Chrome) or **Inspect Element** (in Firefox) to open the Developer Tools.
2. **Locate the Container’s Class or ID**:
   * In the HTML structure that appears, hover over different elements until you find the container that matches the section you want (e.g., header, footer).
   * Look for the `id` or `class` attribute of that container. These attributes are usually displayed in the Inspector window.
3. **Copy the Selector**:
   * Once you’ve identified the right `id` or `class`, copy it.
   * For an ID, you’ll use `#id-name` (e.g., `#shopify-section-footer`).
   * For a class, you’ll use `.class-name` (e.g., `.header-section`).
4. **Paste into the Selector Position Field**:
   * Return to the Geolocation Button app block settings.
   * Paste the copied selector into the **Selector Position** field.

This method ensures the Geolocation Button is positioned exactly where you need it in your theme, creating a seamless customer experience.


# Variables

The Geolocation Button app block provides a range of customizable variables, allowing you to adjust its appearance to match your store's style and needs. These variables can display country flags, currency symbols, and other relevant details to create a localized experience for your customers.

Below is a list of available variables and examples of how to combine them to create unique button styles.

## Available variables

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><code>{square_flag}</code></td><td>Displays a square version of the country flag.</td><td><a href="/files/J1idWmntW7dfZ6LSeFXv">/files/J1idWmntW7dfZ6LSeFXv</a></td></tr><tr><td><code>{rounded_flag}</code></td><td>Shows a rounded version of the country flag.</td><td><a href="/files/vzXxoDIWG4VD7V0d4vF5">/files/vzXxoDIWG4VD7V0d4vF5</a></td></tr><tr><td><code>{circle_flag}</code></td><td>Displays a circular version of the country flag.</td><td><a href="/files/P87rB6ujUgrMDzY9aGis">/files/P87rB6ujUgrMDzY9aGis</a></td></tr><tr><td><code>{icon}</code></td><td>The icon you have uploaded in the icon input.</td><td><a href="/files/JERV0jijSzRRDHz0xS7W">/files/JERV0jijSzRRDHz0xS7W</a></td></tr><tr><td><code>{icon_code_svg}</code></td><td>The SVG icon you have pasted inside the Icon (SVG code) input.</td><td><a href="/files/JERV0jijSzRRDHz0xS7W">/files/JERV0jijSzRRDHz0xS7W</a></td></tr><tr><td><code>{country}</code></td><td>Full country name (e.g., "United States").</td><td><a href="/files/WSl6VLfY35umr5AKoipc">/files/WSl6VLfY35umr5AKoipc</a></td></tr><tr><td><code>{country_code}</code></td><td>2-letter ISO code of the country (e.g., "US").</td><td><a href="/files/fYOMQk5TZCaJagE7wtSB">/files/fYOMQk5TZCaJagE7wtSB</a></td></tr><tr><td><code>{currency_symbol}</code></td><td>Currency symbol (e.g., "$" or "€").</td><td><a href="/files/NneOUDaaXaDLX5u3gf3T">/files/NneOUDaaXaDLX5u3gf3T</a></td></tr><tr><td><code>{currency_code}</code></td><td>Abbreviated currency code (e.g., "USD" or "EUR").</td><td><a href="/files/aRkh0pajOW5U5fEmmhA1">/files/aRkh0pajOW5U5fEmmhA1</a></td></tr><tr><td><code>{language}</code></td><td>Language name (e.g., "English", "Spanish").</td><td><a href="/files/akM1hsUzaFQDVIWX38AR">/files/akM1hsUzaFQDVIWX38AR</a></td></tr><tr><td><code>{language_code}</code></td><td>Language code in ISO 639-1 format (e.g., "en", "es").</td><td><a href="/files/mLZhvxYJKd62fiTQyR4k">/files/mLZhvxYJKd62fiTQyR4k</a></td></tr><tr><td><code>{disclosure}</code></td><td>An arrow or disclosure icon indicating additional options or a dropdown menu.</td><td><a href="/files/TtpardkXMUbx8mbGtuQs">/files/TtpardkXMUbx8mbGtuQs</a></td></tr></tbody></table>

### Combined examples

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><code>{circle_flag} {country} ({currency_code})</code></td><td><a href="/files/SOISKY0EdTCUVtKrgg7q">/files/SOISKY0EdTCUVtKrgg7q</a></td></tr><tr><td><code>{square_flag} {country_code}</code></td><td><a href="/files/35Ka9W5fViGyxJCP9R5Z">/files/35Ka9W5fViGyxJCP9R5Z</a></td></tr><tr><td><code>{icon} {currency_code}</code></td><td><a href="/files/pt7u07UQ37fwisb81BpH">/files/pt7u07UQ37fwisb81BpH</a></td></tr><tr><td><code>{square_flag} {currency_code} {disclosure}</code></td><td><a href="/files/rDqzeQXq6wriMw9nKXXy">/files/rDqzeQXq6wriMw9nKXXy</a></td></tr></tbody></table>

## Learn more about

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Custom CSS</td><td><a href="/files/WEAzUklc6tJ0GZMT10G9">/files/WEAzUklc6tJ0GZMT10G9</a></td><td><a href="/pages/qj7m9ofsuOmVYitM2zru">/pages/qj7m9ofsuOmVYitM2zru</a></td></tr><tr><td>Custom JavaScript</td><td><a href="/files/YtkEk9eFzzqUO5EEeT2W">/files/YtkEk9eFzzqUO5EEeT2W</a></td><td><a href="/pages/qj7m9ofsuOmVYitM2zru#custom-javascript">/pages/qj7m9ofsuOmVYitM2zru#custom-javascript</a></td></tr></tbody></table>


# Custom Code

## Use your theme’s CSS classes <a href="#css-classes" id="css-classes"></a>

<figure><img src="/files/Q4cCvBt4KQd33pyXW064" alt="" width="375"><figcaption></figcaption></figure>

You can reuse existing CSS classes from your Shopify theme to style the Geolocation Button without extra code.

This is especially useful if you're a developer looking to maintain consistency in your storefront.

To apply existing classes:

1. Open your theme code or inspect your site to identify the CSS classes you want to reuse.
2. Copy and paste the classes into the **Add CSS classes** field inside the Geolocation Button settings.\
   \&#xNAN;*(Separate multiple classes with a space, e.g., `my-class another-class`.)*

The Geolocation Button will now include your theme's CSS classes. If your theme's CSS allows it, the button will inherit these styles automatically.

## Custom CSS

The **Custom CSS** input allows you to add additional styles to the Geolocation Button, providing flexibility for adapting the selector’s appearance to match your theme. This is particularly useful if you need styling options beyond those available directly in the app block settings.

You’ll need some knowledge of CSS to apply these custom styles effectively and to select the correct classes. For example:

```css
.md-orbe-country-selector__icon {
    margin: 0 !important;
}
```

This code ensures there’s no margin around the icon, allowing for a tighter, more customized layout.

Add as many custom styles as needed to adapt the Geolocation Button to your store’s design.

## Custom JavaScript

The **Custom JS Function** input allows you to insert JavaScript for advanced actions, such as triggering other elements or custom behaviors **when the button is clicked and just before opening the corresponding selector**.

This is ideal for scenarios where additional actions are needed prior to displaying the Geolocation Popup or Market Selector modal, such as inserting a selector inside a drawer menu.

### Selector inside a drawer menu

If you place the Geolocation Button inside a drawer menu, you may want the drawer to close automatically when the button is clicked, just before the selector opens. You can add a small JavaScript snippet in the **Custom JS** **Function** field to achieve this.

{% code overflow="wrap" %}

```javascript
document.querySelector('.drawer-menu__close').click();
```

{% endcode %}

where:

* `document.querySelector('.drawer-menu__close')`: This part of the code selects the close button of the drawer menu. Replace `.drawer-menu__close` with the specific class used in your theme to target the drawer close button.
* `.click()`: This triggers a click on the close button, causing the drawer menu to close automatically when the Geolocation Button is clicked.

#### **How to find the correct `class` for the close button**

To find the correct class for your drawer’s close button:

1. Open your store in **Preview** mode.
2. Right-click on the close button in the drawer menu and select **Inspect** to open the browser’s Developer Tools.
3. Look for the class name associated with the close button element, and use that class name in place of `'.drawer-menu__close'` in the code snippet.


# Country Selector

The Country Selector allows you to give customers full control over their shopping experience. By adding a selector to your store, visitors can easily **switch between countries** and access the most relevant version of your site.

This feature is fully flexible: **you decide where to place it and how it looks**, ensuring it blends seamlessly with your brand while keeping the buying journey transparent and intuitive.

<figure><img src="/files/6yh0Mt4BglzONUCRzRRS" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
If you want to add a language selector to your website, you can use the app block [Language Selector](/selectors/language-selector)
{% endhint %}

## How to use it

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>➕ How to add</strong></td><td>Step-by-step instructions on adding the app block to your Shopify theme.</td><td><a href="/pages/1lbhGXFrs8VHzwgA5BTD#how-to-add">/pages/1lbhGXFrs8VHzwgA5BTD#how-to-add</a></td></tr><tr><td><strong>🌟 How it works</strong></td><td>Quick start guide to get your Country Selector up and running.</td><td><a href="/pages/1lbhGXFrs8VHzwgA5BTD">/pages/1lbhGXFrs8VHzwgA5BTD</a></td></tr><tr><td><strong>📍 Selector Placement</strong></td><td>How to position the Country Selector anywhere in your theme.</td><td><a href="/pages/bkhYXErQ1PnQMpNfErOs">/pages/bkhYXErQ1PnQMpNfErOs</a></td></tr><tr><td><strong>🎨 Variables</strong></td><td>Customize the selector’s appearance to create a personalized look and feel.</td><td><a href="/pages/qXWWOoSK8ByzXYtPyn2G">/pages/qXWWOoSK8ByzXYtPyn2G</a></td></tr><tr><td><strong>⚒️ Custom Code</strong></td><td>Use custom CSS or JavaScript inside the app.</td><td><a href="/pages/qj7m9ofsuOmVYitM2zru">/pages/qj7m9ofsuOmVYitM2zru</a></td></tr></tbody></table>


# How it works

## How to add

If you have a newer Shopify theme compatible with app blocks (any public theme version [after March 2023](https://shopify.dev/changelog/we-are-introducing-sections-liquid-tag-and-section-groups)), you can add the Country Selector app block using **section groups**.

To add the Country Selector, go to the **Shopify Theme Editor**, navigate to your desired section, and insert the app block directly.

{% embed url="<https://www.loom.com/share/2d978197aa594734848eaad5559957dd?sid=302e30fa-b413-4e1c-9546-e455f98fb593>" %}

{% hint style="warning" %}
Many themes are not compatible with adding **app blocks** in a section that appears in all your theme pages (like the **header** or the **footer** sections).

If that is your case, follow this tutorial: [How it works](/selectors/geolocation-button/how-it-works#update-your-theme-to-be-compatible-with-app-blocks)
{% endhint %}

## How to setup

The **Country Selector** lets your customers manually choose their preferred country, giving them full control over their shopping experience. You can place it in the area of your store that works best for your design and user flow.

To make sure the Country Selector works properly, you’ll need to check that it’s correctly enabled in your theme settings. If it’s not active, the selector won’t display as expected.

Below, you’ll also find a short video tutorial showing exactly how to set it up step by step.

{% embed url="<https://www.loom.com/share/fa633c94a44c497c8ec2511519b9b8d5?sid=137af32f-729f-43f9-952a-d19a9e5dbb28>" %}


# Variables

The **Country Selector** app block comes with a set of customizable variables, letting you tailor its look and feel to fit seamlessly with your store’s design. You can display country flags, names, codes, and other details to create a clear and localized selection experience for your customers.

Below you’ll find the list of available variables and examples of how to combine them to build the selector style that best matches your brand.

## Available variables

### Country selector layout <a href="#selector" id="selector"></a>

Variables available for the Country selector layout.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td><code>{square_flag}</code></td><td>Displays a square version of the country flag.</td><td><a href="/files/J1idWmntW7dfZ6LSeFXv">/files/J1idWmntW7dfZ6LSeFXv</a></td></tr><tr><td><code>{rounded_flag}</code></td><td>Shows a rounded version of the country flag.</td><td><a href="/files/vzXxoDIWG4VD7V0d4vF5">/files/vzXxoDIWG4VD7V0d4vF5</a></td></tr><tr><td><code>{circle_flag}</code></td><td>Displays a circular version of the country flag.</td><td><a href="/files/P87rB6ujUgrMDzY9aGis">/files/P87rB6ujUgrMDzY9aGis</a></td></tr><tr><td><code>{country}</code></td><td>Full country name (e.g., "United States").</td><td><a href="/files/WSl6VLfY35umr5AKoipc">/files/WSl6VLfY35umr5AKoipc</a></td></tr><tr><td><code>{country_code}</code></td><td>2-letter ISO code of the country (e.g., "US").</td><td><a href="/files/fYOMQk5TZCaJagE7wtSB">/files/fYOMQk5TZCaJagE7wtSB</a></td></tr><tr><td><code>{currency_symbol}</code></td><td>Currency symbol (e.g., "$" or "€").</td><td><a href="/files/NneOUDaaXaDLX5u3gf3T">/files/NneOUDaaXaDLX5u3gf3T</a></td></tr><tr><td><code>{currency_code}</code></td><td>Abbreviated currency code (e.g., "USD" or "EUR").</td><td><a href="/files/aRkh0pajOW5U5fEmmhA1">/files/aRkh0pajOW5U5fEmmhA1</a></td></tr><tr><td><code>{icon}</code></td><td>The icon you have uploaded in the icon input.</td><td><a href="/files/JERV0jijSzRRDHz0xS7W">/files/JERV0jijSzRRDHz0xS7W</a></td></tr><tr><td><code>{icon_code_svg}</code></td><td>The SVG icon you have pasted inside the Icon (SVG code) input.</td><td><a href="/files/JERV0jijSzRRDHz0xS7W">/files/JERV0jijSzRRDHz0xS7W</a></td></tr><tr><td><code>{language}</code></td><td>Language name (e.g., "English", "Spanish").</td><td><a href="/files/akM1hsUzaFQDVIWX38AR">/files/akM1hsUzaFQDVIWX38AR</a></td></tr><tr><td><code>{language_code}</code></td><td>Language code in ISO 639-1 format (e.g., "en", "es").</td><td><a href="/files/mLZhvxYJKd62fiTQyR4k">/files/mLZhvxYJKd62fiTQyR4k</a></td></tr></tbody></table>

### Country dropdown layout <a href="#dropdown" id="dropdown"></a>

Variable available for the Country dropdown layout.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td><code>{square_flag}</code></td><td>Displays a square version of the country flag.</td><td><a href="/files/J1idWmntW7dfZ6LSeFXv">/files/J1idWmntW7dfZ6LSeFXv</a></td></tr><tr><td><code>{rounded_flag}</code></td><td>Shows a rounded version of the country flag.</td><td><a href="/files/vzXxoDIWG4VD7V0d4vF5">/files/vzXxoDIWG4VD7V0d4vF5</a></td></tr><tr><td><code>{circle_flag}</code></td><td>Displays a circular version of the country flag.</td><td><a href="/files/P87rB6ujUgrMDzY9aGis">/files/P87rB6ujUgrMDzY9aGis</a></td></tr><tr><td><code>{country}</code></td><td>Full country name (e.g., "United States").</td><td><a href="/files/WSl6VLfY35umr5AKoipc">/files/WSl6VLfY35umr5AKoipc</a></td></tr><tr><td><code>{country_code}</code></td><td>2-letter ISO code of the country (e.g., "US").</td><td><a href="/files/fYOMQk5TZCaJagE7wtSB">/files/fYOMQk5TZCaJagE7wtSB</a></td></tr><tr><td><code>{currency_symbol}</code></td><td>Currency symbol (e.g., "$" or "€").</td><td><a href="/files/NneOUDaaXaDLX5u3gf3T">/files/NneOUDaaXaDLX5u3gf3T</a></td></tr><tr><td><code>{currency_code}</code></td><td>Abbreviated currency code (e.g., "USD" or "EUR").</td><td><a href="/files/aRkh0pajOW5U5fEmmhA1">/files/aRkh0pajOW5U5fEmmhA1</a></td></tr></tbody></table>


# Language Selector

The Language Selector gives your customers full control over how they browse your store. By adding it to your site, visitors can easily **switch between languages** and access the version that feels most natural to them.

This feature is fully flexible: **you decide where to place it and how it looks**, so it blends seamlessly with your brand while keeping the shopping journey clear and intuitive.

<figure><img src="/files/C7wqzN9ukYk9YvCj7mFd" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
If you want to add a country selector to your website, you can use the app block [Country Selector](/selectors/country-selector)
{% endhint %}

## How to use it

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>➕ How to add</strong></td><td>Step-by-step instructions on adding the app block to your Shopify theme.</td><td><a href="/pages/lPCYnOsyWb4OxJPJKZlT#how-to-add">/pages/lPCYnOsyWb4OxJPJKZlT#how-to-add</a></td></tr><tr><td><strong>🌟 How it works</strong></td><td>Quick start guide to get your Language Selector up and running.</td><td><a href="/pages/lPCYnOsyWb4OxJPJKZlT">/pages/lPCYnOsyWb4OxJPJKZlT</a></td></tr><tr><td><strong>📍 Selector Placement</strong></td><td>How to position the Language Selector anywhere in your theme.</td><td><a href="/pages/bkhYXErQ1PnQMpNfErOs">/pages/bkhYXErQ1PnQMpNfErOs</a></td></tr><tr><td><strong>🎨 Variables</strong></td><td>Customize the button’s appearance to create a personalized look and feel.</td><td><a href="/pages/zm9tIlrPz1b64PqjIoaD">/pages/zm9tIlrPz1b64PqjIoaD</a></td></tr><tr><td><strong>⚒️ Custom Code</strong></td><td>Use custom CSS or JavaScript inside the app.</td><td><a href="/pages/qj7m9ofsuOmVYitM2zru">/pages/qj7m9ofsuOmVYitM2zru</a></td></tr></tbody></table>


# How it works

## How to add

If you have a newer Shopify theme compatible with app blocks (any public theme version [after March 2023](https://shopify.dev/changelog/we-are-introducing-sections-liquid-tag-and-section-groups)), you can add the Language Selector app block using **section groups**.

To add the Language Selector, go to the **Shopify Theme Editor**, navigate to your desired section, and insert the app block directly.

{% embed url="<https://www.loom.com/share/43b5a7447c6d440c95239b874e781f8d?sid=d9e92db3-4850-4d9b-8986-86439ebdb4b5>" %}

{% hint style="warning" %}
Many themes are not compatible with adding **app blocks** in a section that appears in all your theme pages (like the **header** or the **footer** sections).

If that is your case, follow this tutorial: [How it works](/selectors/geolocation-button/how-it-works#update-your-theme-to-be-compatible-with-app-blocks)
{% endhint %}

## How to setup

The **Language Selector** lets your customers manually choose their preferred language, giving them full control over how they navigate your store. You can place it wherever it best fits your design and user flow.

To ensure the Language Selector works properly, make sure it’s correctly enabled in your theme settings. If it’s not active, the selector won’t appear as expected.

Below, you’ll also find a short video tutorial that walks you through the setup step by step.

{% embed url="<https://www.loom.com/share/938cf541738c465182a9bf77fca07f7f?sid=8353463c-2821-4962-b811-df2aef3999d3>" %}


# Variables

The **Language Selector** app block includes a set of customizable variables, allowing you to adjust its look and feel so it fits seamlessly with your store’s design. You can display language names, codes, and other details to create a clear and intuitive selection experience for your customers.

Below you’ll find the list of available variables and examples of how to combine them to build a selector style that best reflects your brand.

## Available variables

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td><code>{language}</code></td><td>Language name (e.g., "English", "Spanish").</td><td><a href="/files/akM1hsUzaFQDVIWX38AR">/files/akM1hsUzaFQDVIWX38AR</a></td></tr><tr><td><code>{language_code}</code></td><td>Language code in ISO 639-1 format (e.g., "en", "es").</td><td><a href="/files/mLZhvxYJKd62fiTQyR4k">/files/mLZhvxYJKd62fiTQyR4k</a></td></tr></tbody></table>

{% hint style="warning" %}
**Why flags aren’t available in the Language Selector**

\
Flags represent **countries**, not **languages**, and one language can be spoken in many countries. To avoid confusion and ensure accessibility, our Language Selector doesn’t include flags as a variable.\
This gives you a clean, consistent, and accurate language selection experience for your customers.\
\
Want to learn more? Read the full article [“Why flags do not represent language”](https://www.flagsarenotlanguages.com/blog/why-flags-do-not-represent-language/) to understand why this design choice matters.
{% endhint %}


# Market Selector

In this tutorial, we'll guide you through the process of activating and customizing our Market Selector app embed within the Shopify Theme Editor. Furthermore, we'll delve into advanced settings that necessitate custom code, empowering you to position the country selector in the header with a unique layout.

## How to setup

To begin, launch the Shopify Theme Editor and navigate to the "App Embeds" section. There, locate and activate the "Market Selector" App Embed.

<figure><img src="/files/VIrN67haojBvaFTCOA6q" alt=""><figcaption></figcaption></figure>

Following that, you have the option to select your preferred selector type from the following choices:

* **Classic Selector:** A country and language selector that is prominently displayed.

<div align="center" data-full-width="true"><figure><img src="/files/6asjG5LtnbeMOnqjL5xi" alt=""><figcaption></figcaption></figure></div>

* **Modal Selector:** This selector features country flags, allowing users to easily explore various country options.

<figure><img src="/files/4SOlIQ2irY40IRyTqXPZ" alt=""><figcaption></figcaption></figure>

* **Geolocation Popup:** To display the [Geolocation Popup](broken://pages/wrGyhLrpQEPenokIHrt0) selector, you must have the Embed Geolocation Popup App activated.

  <br>

  <figure><img src="/files/DrYO4h8v4nL8OvuUiUwK" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Depending on your selector choice, you can tailor various options while bypassing the others to suit your specific needs.
{% endhint %}

### Classic Selector

You can show or hide the language selector. We recommend adding this option from Orbe if your store is available in multiple languages. Then, as we made in the geolocation popup, you can also personalize the corners & buttons and the selector's colours.

<figure><img src="/files/nSeITbmWPGxlgzoyfp40" alt=""><figcaption></figcaption></figure>

You also have the option to display the flag of the recommended country or the market currency with various styles.

<figure><img src="/files/7791vm0kQe4aJupVzHYN" alt=""><figcaption></figcaption></figure>

Finally, you can enable the country search to make it easier for your users to find their desired country.

<figure><img src="/files/i0ELnkGCiZHe8OsCYKlV" alt=""><figcaption></figcaption></figure>

### Modal Selector

If you choose this selector, you can decide if you want to display the flags, the market currency, and its style –for example, EUR or €, USD or $–.

<figure><img src="/files/Cl990QiRQInvGN1h168J" alt=""><figcaption></figcaption></figure>

Additionally, you can modify the title and the language title.

<figure><img src="/files/22oZV3IBzkKvLqNZxRXc" alt=""><figcaption></figcaption></figure>

#### Global Settings

Last but not least, you can choose which position to add the footer: left, centre or right.

<figure><img src="/files/MjslV90YXVdTzzGSrItT" alt=""><figcaption></figcaption></figure>

Real customer examples:

* <https://naakbar.com/>
* <https://rondorff.com/>

{% hint style="info" %}
If you have an **Orbe paid plan**, our team can add a custom country selector to any position in your theme. [**Contact support for help**](mailto:support@orbe.app).
{% endhint %}


# Notifications

You can adjust your preferences to ensure you only get the updates that matter most.

Orbe uses your Shopify login to identify you and connect your account. When you access Orbe, your Shopify email is automatically registered, and from the [**Settings**](http://admin.shopify.com/apps/300c7396da3de51b6c2a5df448979f2a/settings) page, you can manage your email preferences.

You can choose between two types of communications:

* **Product updates**: stay informed about the latest enhancements and new features.
* **Marketing**: stay subscribed to receive full benefits and maximize your Orbe experience.

To update your preferences, simply log in with the specific Shopify user you want to manage, go to **Settings**, and check or uncheck the boxes under **Email preferences**. Each user can manage their own preferences independently.

{% hint style="info" %}
Please note that essential **transactional emails** (such as error notifications, required updates, or important Shopify changes) will continue to be sent as long as the app is installed. These communications are **required** to keep <code class="expression">space.vars.geolocation\_app</code> running correctly in your store.
{% endhint %}


# Geolocation

In any Orbe paid plan, you can configure **advanced geolocation behaviors** beyond the default settings. This tutorial explains the available geolocation options, allowing each brand to tailor them to their specific needs.

{% hint style="info" %}
All these settings are compatible with [Share Settings](https://help.orbe.app/general/connect-stores/settings#shared-settings). If you have connected stores and you enable it, all the configuration will sync across all of them automatically.
{% endhint %}

## When a customer visits for the first time <a href="#first-visit" id="first-visit"></a>

{% hint style="warning" %}
This setting is only available on **paid** plans.
{% endhint %}

This setting enables you to customize **Orbe's behavior when a customer visits your store for the first time**.

<figure><img src="/files/aWWwmPaT6PhFtqaVKU63" alt=""><figcaption></figcaption></figure>

### Show always on the first visit regardless of the user's location <a href="#always-first-visit" id="always-first-visit"></a>

This is the default option. It functions as a welcome popup that appears to **all customers on their initial visit**, prompting them to select their preferred experience.

{% hint style="info" %}
**Example**

If a user visits the Spanish experience from Spain, the popup will appear, allowing the user to confirm their preferences.
{% endhint %}

This option is highly recommended for customers using the [**Klaviyo integration**](/general/integrations/klaviyo), as it enables Orbe to save country and language preferences and send them to Klaviyo for personalized email marketing campaigns.

### Show only when the user is in the incorrect experience <a href="#only-incorrect" id="only-incorrect"></a>

This option ensures that the geolocation popup is displayed **only when the user is in the wrong shopping experience**. When an international user visits an incorrect shopping experience, Orbe will recommend redirecting them to their localized experience.

{% hint style="info" %}
**Example**

When a US user visits the US experience, Orbe will not bother the user since they are in the correct localized experience.

When a French user visits the US experience, the Orbe popup will appear, recommending the French experience.
{% endhint %}

We recommend using this option if you want to show the welcome popup only for your international customers.

## When a customer comes back <a href="#second-visit" id="second-visit"></a>

This setting allows you to configure **Orbe's behavior on the second and subsequent visits** of a customer when they are in the incorrect experience.

<figure><img src="/files/ezFf5A77N6nMeaOavH3r" alt=""><figcaption></figcaption></figure>

### Redirect only if the current country and preference match <a href="#redirect-on-match" id="redirect-on-match"></a>

This option (enabled by default) only redirects users when their **current location matches the country they previously selected**.

If the user is now in a different country, Orbe won’t force a redirect or show the popup again.

{% hint style="info" %}
**Example**

* **Store they are browsing:** United States
* **Country selected on first visit:** United Kingdom
* **Current location:** Spain

Because the user’s current location (Spain) doesn’t match their saved preference (United Kingdom), Orbe does nothing. The user keeps browsing the **US store** without interruption.
{% endhint %}

### Always redirect based on country preference <a href="#always-redirect" id="always-redirect"></a>

With this option, Orbe **always redirects users to the country they previously selected**, no matter where they are located.

Once a user chooses a country, Orbe treats that choice as the source of truth.

{% hint style="info" %}
**Example**

* **Store they are browsing:** United States
* **Country selected on first visit:** United Kingdom
* **Current location:** Spain

Orbe ignores the user’s current location and redirects them to the **UK store** every time.
{% endhint %}

## Language selector behavior

{% hint style="warning" %}
This setting is only available on **paid** plans.
{% endhint %}

This setting allows you to configure **how you want a default language to be suggested** in the language selector.

<figure><img src="/files/yTpsUYGBfVZz0UMyI0Ow" alt=""><figcaption></figcaption></figure>

### Defaultly suggest the user's browser language <a href="#browser-language" id="browser-language"></a>

This is the default and recommended option, as users typically set their browsers to their preferred language or a language they are comfortable with. Therefore, if the language of their browser is available, it is advisable to suggest that language. Otherwise, the default language configured in Shopify Markets for the respective country will be recommended.

### Defaultly suggest the language configured for each market in the settings of Shopify Markets <a href="#market-language" id="market-language"></a>

With this option, Orbe will suggest the default language you’ve set for each market in Shopify Markets. That means visitors will automatically see the language you’ve defined for the market they’re browsing (even if it doesn’t match their browser’s language).

## Language Settings

{% hint style="warning" %}
This setting is only available on **paid** plans.
{% endhint %}

Sometimes users reach the correct shopping experience but still **see the store in a language that doesn’t match their preferences**. This often happens in places like Canada, where different regions use English or French, or when users are living abroad, traveling, or browsing from a temporary location. In these situations, customers may receive the right prices, products, and currency for their location, yet the store may not appear in their preferred language, even when that language is available.

Orbe allows you to configure how language should be suggested in these situations, with multiple behavior options that can work together.

<figure><img src="/files/JX63adz5wdr28GZQFKjQ" alt=""><figcaption></figcaption></figure>

### Show Orbe if the user is in the correct experience but not using their browser language <a href="#show-incorrect-language" id="show-incorrect-language"></a>

This option triggers the popup when a user is in the correct country, experiencing accurate pricing, product availability, and currency settings. If they are not browsing the store in their preferred language based on their browser settings, the system will recommend switching to their preferred language.

### Automatically redirect if they're in the right store for their country but browsing in a different language than their preferred one <a href="#language-redirect" id="language-redirect"></a>

This option is particularly beneficial when the store's 'Language Settings' are configured to show Orbe if the user is in the correct experience but not using their browser language (the previous setting). It acts as a complementary feature.

For instance, if a brand's primary language for the United Kingdom is English and Spanish is also available, a user choosing the Spanish market as their preference will consistently be redirected to the Spanish experience. Not selecting this option would result in the user visiting the store in English on subsequent visits, even if Spanish is their preferred language.

{% hint style="warning" %}
Please bear in mind that activating '*Automatically redirect if they're in the right store for their country but browsing in a different language than their preferred one*' and using your own language selectors (not ours) requires syncing your language selector with Orbe. This synchronization is crucial to allow us to refresh the cookies when users actively change their language preferences. Failure to perform this synchronization could result in your **language selector ceasing to function properly**. Consequently, users may encounter difficulties in changing their language preferences seamlessly.
{% endhint %}

## Popups Display Order <a href="#popup-order" id="popup-order"></a>

{% hint style="warning" %}
This setting is available on **Orbe paid** plans.
{% endhint %}

The **Popups display order** setting controls when the Geolocation popup appears in relation to other banners and popups on your store (such as cookie consent banners).

You can find this setting in **Settings →** [**Geolocation**](https://admin.shopify.com/apps/300c7396da3de51b6c2a5df448979f2a/settings/geolocation)

{% embed url="<https://www.loom.com/share/0be23482d8e84c2fb14841ae8f00be5f>" %}

{% hint style="info" %}
Keep in mind that **Orbe is not a cookie management tool**. Its Geolocation popup serves a different purpose: helping visitors understand which market they're browsing before anything else loads. This setting simply gives you control over the order in which popups appear (there's no wrong choice, it's purely a matter of user experience).
{% endhint %}

### No specific behaviour option

<figure><img src="/files/Y2j0lymJ2esg2WMD3Ql7" alt=""><figcaption></figcaption></figure>

This is the default option. With it, **the Geolocation popup appears without a specific order,** whichever loads first will show first. This works fine if you don't have other popups on your store, or if you don't mind them appearing at the same time.

If you want it to show after your cookie banner, you'll need to configure that directly in your cookie management app.

### Show before other popup option

<figure><img src="/files/oUoZ5QscW0osa6PYVXDK" alt=""><figcaption></figcaption></figure>

**The Geolocation popup appears before any other popups or banners on your store**. This is useful if, for example, you want visitors to select their country before they see a cookie consent banner or a promotional popup.

When you select this option, you'll need to add the CSS classes or IDs of the popups you want to delay; this tells Orbe which banners to hold back until the visitor has interacted with the Geolocation popup.\
\
For example, if you're using the official cookie banners from Shopify, you'd add `#shopify-pc__banner`.

## Preferences duration

Preferences duration lets you decide **how long Orbe should remember a visitor’s choice** before showing the geolocation popup again.

This gives you full control over **how often visitors are asked to confirm their country or language again**. It’s a simple way to ensure the popup appears **when it makes sense**, and stays out of the way when it doesn’t.

{% hint style="warning" %}
This setting is available on **Orbe Plus** and **Enterprise** plans.
{% endhint %}

<figure><img src="/files/fIXEXnqnSMPF8L6FWF1H" alt=""><figcaption></figcaption></figure>

### After visitor closes popup <a href="#after-closing-popup" id="after-closing-popup"></a>

Use this option to decide how long the popup stays hidden when a visitor **closes it without selecting anything**.

You can choose a number of days (minimum: 1, default: 7). During that time, the popup won’t appear again.

<figure><img src="/files/LCZrtZFHeaw3j2F5YsCG" alt="" width="563"><figcaption></figcaption></figure>

{% hint style="info" %}
**Example**

If you set this to **3 days**, a visitor who closes the popup will not see it again for the next 3 days, even if they return multiple times. On day 4, the popup appears again so they can confirm their location.
{% endhint %}

#### **Hide the popup only for the current browser session** <a href="#close-popup-only-session" id="close-popup-only-session"></a>

{% hint style="success" %}
**Recommended for most stores.** We recommend this option to guarantee the best overall geolocation experience.
{% endhint %}

With this option, the popup stays hidden **only while the current browser session is active**.

Once the visitor closes their browser, the session resets and the popup will appear again on their next visit. It’s an easy way to hide the popup temporarily without choosing a fixed number of days.

{% hint style="info" %}
**Example**

A visitor closes the popup and keeps browsing your store. As long as they keep the same browser session open, the popup stays hidden. If they close their browser at night and return the next morning, the session resets and the popup will appear again immediately.
{% endhint %}

### **After visitor selects country and language** <a href="#after-selecting-preferences" id="after-selecting-preferences"></a>

Adjust this setting to control **how long Orbe keeps a visitor’s confirmed country and language** before asking again. It’s useful when you want to double-check that the shopper is still in the right store and their context hasn’t changed.

<figure><img src="/files/q01e8XMOg8W0p01eKoBE" alt="" width="563"><figcaption></figcaption></figure>

During this time, Orbe uses those preferences to **automatically guide visitors to the right storefront** without showing the popup again.

By default, Orbe remembers the selection for **60 days**, but you can shorten this period if you want to reconfirm preferences more often and give visitors the chance to choose again.

{% hint style="info" %}
**Example**

If you set this to **15 days**, Orbe will use the visitor’s selected country and language to automatically guide them to the right store for the next 15 days, without showing the popup again.

On day 16, the popup appears again so the visitor can confirm or update their preferences if their situation has changed.
{% endhint %}


# Countries

The Countries tab in Settings centralizes all configuration related to how countries are displayed, ordered, and suggested across your store.

## Rename countries

{% hint style="warning" %}
This setting is only available on **paid** plans.
{% endhint %}

<figure><img src="/files/0uh81lYD8xNaCeiKBpC6" alt=""><figcaption></figcaption></figure>

This setting controls **how country names appear** across all selectors in your store.

You can select a country name template to define the format used for country names. The **Default** option uses Orbe’s standard naming format. Selecting **English** displays country names in English, while **Native** displays them in their native language. The **English / Native** option shows the English name followed by the native name.

You can also add custom country names. Any country added here will override the selected template and use the custom name instead.

## Highlight countries

{% hint style="warning" %}
This setting is only available on **Plus** and **Enterprise** plans.
{% endhint %}

<figure><img src="/files/BCyYrdTHPU2oBkSLhYjv" alt=""><figcaption></figcaption></figure>

In **Highlight countries**, you can define which countries appear at the top of the selector. Highlighted countries are shown first, while all other countries appear below. This order is applied across all active selectors and helps prioritize key markets and make country selection faster for users.

<figure><img src="/files/o4UipLxr90r9jskkkXYj" alt=""><figcaption></figcaption></figure>

## Fallback country

{% hint style="warning" %}
This setting is only available on **paid** plans.
{% endhint %}

<figure><img src="/files/swf7x0EAR5zOS8ex1s61" alt=""><figcaption></figcaption></figure>

The **Fallback country** defines which country is suggested to visitors coming from regions you don’t ship to. By default, in this scenarios, the welcome popup will preselect the Backup region of your Shopify store, but if you want to change it you can do it selecting it here.\
\
This setting is configured per store and does not affect automatic country detection for supported regions. It is only used when no valid country match is available.

{% hint style="info" %}
These settings are **not compatible with** [**Share Settings**](/general/connect-stores/settings#shared-settings).

However, for **Plus or Enterprise plans with connected stores**, the following applies:

* **Country ordering** is automatically synced across all connected stores;
* **Custom country names** are also synced;
* When editing these settings, you will see all countries from connected stores in the same view.

The *fallback country* is **not synced** and remains a store-specific setting.
{% endhint %}


# Custom code

How do I apply CSS code to personalize the geolocation popup?

Many brands enhance their geolocation popups by adding identifying elements like their logo.

If you have a paid Orbe plan, you can customize the Geolocation Modal CSS through the "Settings" menu. Our editor allows you to apply CSS for customizing the modal.

<figure><img src="/files/hRbsn8DsWRomWJfYIQZu" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Consider that the Custom CSS editor won't appear in your settings until you upgrade your plan.
{% endhint %}

## Do you not know CSS?

Our Help Center has a collection of CSS Snippets available exclusively for users of our paid plan. These snippets make it easy for you to customize your popup's appearance without any coding knowledge. With just a few clicks, you can effortlessly enhance your storefront and create a unique brand style.

By simply copying and pasting these pre-written snippets into the 'Custom CSS' section of our app's Advanced Settings, you can instantly transform the look and feel of your popup. It's that simple!

To explore and leverage these powerful CSS Snippets, visit our dedicated page in the Help Center. Unleash your creativity and make your popup truly stand out!

<table data-view="cards"><thead><tr><th></th><th data-hidden></th><th data-hidden></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><p><strong>Snippets</strong></p><p>See our Snippets</p></td><td></td><td></td><td><a href="/files/n0Kzy9MbneUQGE5v5t8L">/files/n0Kzy9MbneUQGE5v5t8L</a></td><td><a href="/pages/OUejfgXTW1RxTBjpkhBx">/pages/OUejfgXTW1RxTBjpkhBx</a></td></tr></tbody></table>


# CSS

Use Orbe CSS to customize your storefront

{% hint style="info" %}
**Developers only:** This documentation is intended for developers with technical knowledge and experience in Shopify Theme Development.
{% endhint %}

## User Location

To customize your theme files, you can use CSS variables to add your styles. Orbe adds a custom class to the body element of the theme, which can be used to apply customizations throughout the entire theme.

The CSS class is named `orbe-country-code--COUNTRYCODE`, where `COUNTRYCODE` is the ISO two-letter code (alpha-2) of the country where the customer is located. For example, if the customer is in the United Kingdom, the following class will be added to the body element:

```html
<body class="orbe-country-code--GB"></body>
```

You can find the global list of country ISO two-letter codes at [https://countrycode.org/](https://countrycode.org).

{% hint style="success" %}
You can add your custom CSS in the Advanced CSS section inside Orbe: [Custom code](/settings/custom-code). This ensures the CSS is always available in any theme where the Orbe app is enabled.
{% endhint %}

## Country Flags

If you want to customize your Shopify store and display the flag of any country, Orbe provides a set of auxiliary classes that can be used. These classes enable you to incorporate country flags into your design in various ways.

The country selectors mentioned here are just one example of how you can utilize these classes.

#### Usage Example:

To display the flag of Australia, you can use the following HTML:

```html
<div class="orbe-flags-au"></div>
```

This will render the flag of Australia as the background image of the `<div>` element.

You can replace "au" in the class name with the appropriate two-letter country code to display the flag of any desired country.

You can even use liquid code to show the country flag of the current experience dynamically. For example:

```html
<div class="orbe-flags-{{ localization.country.iso_code | downcase }}"></div>
```

This will dynamically render the flag of the current country experience by retrieving the appropriate country code from the `localization` object.

Please note that the provided classes are not limited to selectors and can be used in any way you see fit for your customization needs.

## Popup State

Orbe provides a way to customize your store’s behaviour when the popup is open.

A specific class, `orbe--opened`, is added to the `body` element of the theme whenever the Orbe popup is visible. This class is automatically removed when the popup is closed.

The **most common use case** for this class is to **ensure that other popups are displayed only after** the **Orbe popup has been closed**, avoiding overlapping or distracting user experiences.

### Example

To hide another popup while the Orbe popup is open:

```css
.orbe--opened .your-popup-class { 
    display: none !important;
}
```

Replace .your-popup-class with the `class` or `ID` of the popup you want to hide.

For example, to hide Shopify’s default cookie banner:

```css
.orbe--opened #shopify-pc__banner { 
    display: none !important;
}
```

This ensures **other popups appear only after the Orbe popup is closed**, creating a smooth user experience.

Add this CSS to the [Custom code](/settings/custom-code) section inside Orbe. It will be available in any theme with Orbe enabled.


# JavaScript

Use Orbe's variables and functions for your custom localization needs

{% hint style="info" %}
**Developers only:** This documentation is intended for developers with technical knowledge and experience in Shopify Theme Development.
{% endhint %}

## Functions

<table data-full-width="false"><thead><tr><th>Geolocation popup</th><th>Market Selector Popup</th></tr></thead><tbody><tr><td><img src="/files/uRIrtHH3S8DLUpk55pPR" alt="" data-size="original"></td><td><img src="/files/nhSqbZI7WMREixQfWuuo" alt=""></td></tr><tr><td><code>md-app-embed__modal</code></td><td><code>md-app-embed__footer-popup</code></td></tr></tbody></table>

Use these JavaScript functions to manage popup behavior:

<table data-full-width="false"><thead><tr><th width="378">Function</th><th>Description</th></tr></thead><tbody><tr><td><code>orbito.openAndRefreshModal();</code></td><td>Opens the "Geolocation Popup" and automatically updates to match the user's current location and browser language preferences.</td></tr><tr><td><code>orbito.openModalWithoutRefresh();</code></td><td>Opens the "Geolocation Popup" but maintains the user's current selections within the Shopify storefront, avoiding any refresh.</td></tr><tr><td><code>orbito.openModal('md-app-embed__footer-popup');</code></td><td>Opens the "Market Selector" modal type.</td></tr><tr><td><code>orbito.closeModal('md-app-embed__modal');</code></td><td>Closes the "Geolocation Popup".</td></tr><tr><td><code>orbito.closeModal('md-app-embed__footer-popup');</code></td><td>Closes the "Market Selector" Popup</td></tr></tbody></table>

{% hint style="warning" %}
**Important notice**

To utilize these JavaScript functions effectively, ensure that the corresponding app embeds are enabled.
{% endhint %}

## Object

Orbe creates a JS object called `orbito` with both properties and methods to access geographical information about the user’s location.

#### Summary of `orbito` methods:

<table><thead><tr><th width="342">Method</th><th width="224">Description</th><th>Example output</th></tr></thead><tbody><tr><td><code>orbito.getRemoteCountryCode()</code></td><td>Country code based on the user location</td><td><code>GB</code>, <code>US</code></td></tr><tr><td><code>orbito.getRemoteRegionCode()</code></td><td>Region/state short code (FIPS or ISO format) directly based on the user location</td><td><code>CA</code> (For California in US), <code>MD</code> (For Madrid in Spain)</td></tr></tbody></table>

Here is an example of how to use the method `orbito.getRemoteCountryCode()`:

```javascript
var myCustomVar = '';
 setTimeout(() => {
   orbito.getRemoteCountryCode().then((value) => {
    myCustomVar = value;
    if (myCustomVar === 'GB') {
      console.log("User is in the UK");
    }
  });
}, 1000);
```

This code will log the message "User is in the UK" to the console only if the user is located in the United Kingdom, based on the `orbeCountryCode` object. You can modify the message to suit your needs and use this code as a starting point for implementing other customizations based on the user's location.

For instance, you could show a message on the product pages of users in the UK saying "2-hour delivery". Here's some sample code to achieve this:

```javascript
setTimeout(() => {
  orbito.getRemoteCountryCode().then((value) => {
    if (value === 'GB') {
      document.querySelector('.delivery-message').innerHTML = '2-hour delivery';
    } else if (value === 'US') {
      document.querySelector('.delivery-message').innerHTML = '1-day delivery';
    }
  });
}, 1000);
```

Note that you can adjust the delivery message based on the customer's country code, and the code above assumes you have a div element on your product pages with the class `.delivery-message` where you want to show the delivery message.

***

If you have any questions or need additional assistance, please don't hesitate to [contact us](https://orbe.app/contact).


# Relocating the Market Selector

{% hint style="info" %}
**Developers only:** This documentation is intended for developers with technical knowledge and experience in Shopify Theme Development.
{% endhint %}

The Orbe's Country and Language Selector (also known as "Market Selector") from the embed app can be easily relocated to any part of the theme. This guide will show you how to accomplish this task.

The Market Selector is a key feature that provides the flexibility of allowing users to select their preferred market and language on your storefront. It's usually placed in the footer, but sometimes, you might want to relocate it for a better user experience or to match your theme's design requirements.

### How to move the Market Selector

To move the Market Selector, add the following `div` tag to any part of your theme's code where you'd like to place it:

```html
<div id="custom__md-footer-selector-block"></div>
```

You can place this `div` anywhere within your HTML theme files, depending on where you want the Market Selector to appear. The Market Selector's functionality remains the same, no matter where it's located within your theme.

For instance, if you wish to move the Market Selector to the header of your theme, you can add the `div` into your header's HTML file. Similarly, to position it inside your footer, you could incorporate the `div` within the respective HTML file.

#### Note

This only changes the position of the Market Selector within your theme. It does not alter the Market Selector's style, functionality, or its default appearance settings. If you want to change these aspects, you'll need to customize it [using CSS](/settings/custom-code) or use additional JavaScript.

This solution offers a high degree of flexibility, enabling you to customize the position to match your theme's layout and design, while still maintaining the functionality of the Market Selector.

Please remember to test the new placement of the Market Selector in various browsers and screen sizes to ensure optimal user experience.

{% hint style="info" %}
**Accessibility tip**: when moving the Market Selector, make sure its placement isn’t hidden (on desktop or mobile) by other elements like floating buttons (WCAG 2.2 – Focus Not Obscured, Level AA).
{% endhint %}


# Integrate your selector

{% hint style="info" %}
**Developers only:** This documentation is intended for developers with technical knowledge and experience in Shopify Theme Development.
{% endhint %}

{% hint style="danger" %}
Please **don't follow this article** if you have **multiple stores to redirect with Orbe**. Your selector should be any one created by the Orbe app. Follow this article: [Geolocation Button](/selectors/geolocation-button)
{% endhint %}

In our app Orbe, we have an app embed called "Market Selector" that allows any Shopify merchant to add and customize a country and language selector in the footer of any Shopify Theme. These selectors use the Orbe technology.

However, some merchants would like to use their native Shopify theme country and language selector with Orbe because they want its style and UX in their theme. They can work with a developer to synchronize this theme selector with Orbe for that case.

## Tutorial

{% hint style="info" %}
If you are on a **paid Orbe subscription** and would like to use your theme’s native selector, please [**contact us**](https://orbe.app/contact)**.** Our development team will handle the integration for you.
{% endhint %}

This tutorial provides a straightforward and effective method for integrating a country selector with Orbe, ensuring a seamless user experience.

### 1. Retrieve the store domain

First, ensure we correctly set cookies across your Shopify store by capturing the domain.

This can be achieved using Orbe's `getCountryDomain` function. If this function does not provide a result, we'll use `window.location.hostname` as a reliable fallback.

{% code overflow="wrap" %}

```javascript
let shopDomain = (typeof orbito !== 'undefined' && orbito.getCountryDomain) ? (orbito.getCountryDomain() || window.location.hostname.replace(/^www\./, '')) : window.location.hostname.replace(/^www\./, '');
```

{% endcode %}

### 2. Customize the onItemClick event handler

Locate the function in your Shopify theme that triggers when a user selects a country or language. This function usually handles the event and submits the form in the last step.

\
Here you have an example of the code for the selector of the [official Shopify documentation](https://shopify.dev/docs/themes/markets/multiple-currencies-languages#the-country-selector):

```csharp
onItemClick(event) {
    event.preventDefault();
    const form = this.querySelector('form');
    this.elements.input.value = event.currentTarget.dataset.value;
    if (form) form.submit();
}
```

For each scenario, it is super important that you update this:

* **Country change:** Update the cookie `mdApp_countryCodeDomain` and indicate in a URL parameter this update to Shopify Markets. This is only necessary for country change as you may set up a different subdomain or domain for a market, and you will move these preferences throughout the URL parameter to Shopify Markets.
* **Language change**: Update the cookie `mdApp_showRecommendationLang`.

Here is the code improvement based on the above example:

{% code overflow="wrap" fullWidth="false" %}

```javascript
onItemClick(event) {
    event.preventDefault();
    const form = this.querySelector('form');
    const inputType = event.currentTarget.dataset.input;
    const value = event.currentTarget.dataset.value;

    // Determine if it is a country_code or language_code change
    const inputCountry = form.querySelector('input[name="country_code"]');
    const inputLanguage = form.querySelector('input[name="locale_code"]');

    // Get the return_to
    const returnToInput = form.querySelector("input[name='return_to']");

    if (inputCountry) {
        // Check if the 'country' parameter exists and if not add it to the URL
        if (returnToInput.value.match(/(\?|&)country=[^&]*/)) {
            // Replace the existing country parameter
            returnToInput.value = returnToInput.value.replace(/(\?|&)country=[^&]*/, `$1country=${value}`);
        } else {
            // Add the country parameter
            if (returnToInput.value.includes('?')) {
                returnToInput.value += `&country=${value}`;
            } else {
                returnToInput.value += `?country=${value}`;
            }
        }
        // Update the Orbe cookie for country code
        document.cookie = `mdApp_countryCodeDomain=${value}; domain=${shopDomain}; path=/; max-age=${60 * 60 * 24 * 60};`;

    } 
    
    if (inputLanguage) {
        // Update the Orbe cookie for language code
        document.cookie = `mdApp_showRecommendationLang=${value}; domain=${shopDomain}; path=/; max-age=${60 * 60 * 24 * 60};`;
    }

    // Update the form's input field and submit the form
    this.elements.input.value = value;
    if (form) form.submit();
}
```

{% endcode %}

## Real example

Here is an example of how the entire code might look, based on the JavaScript for the [official Shopify country selector documentation](https://shopify.dev/docs/themes/markets/multiple-currencies-languages#javascript-submission-of-the-localization-form):

{% code overflow="wrap" %}

```javascript
class LocalizationForm extends HTMLElement {
    constructor() {
        super();
        this.elements = {
            input: this.querySelector('input[name="language_code"], input[name="country_code"]'),
            button: this.querySelector('button'),
            panel: this.querySelector('ul'),
        };
        this.elements.button.addEventListener('click', this.openSelector.bind(this));
        this.elements.button.addEventListener('focusout', this.closeSelector.bind(this));
        this.addEventListener('keyup', this.onContainerKeyUp.bind(this));

        this.querySelectorAll('a').forEach(item => item.addEventListener('click', this.onItemClick.bind(this)));
    }

    hidePanel() {
        this.elements.button.setAttribute('aria-expanded', 'false');
        this.elements.panel.setAttribute('hidden', true);
    }

    onContainerKeyUp(event) {
        if (event.code.toUpperCase() !== 'ESCAPE') return;

        this.hidePanel();
        this.elements.button.focus();
    }

    onItemClick(event) {
        event.preventDefault();
        const form = this.querySelector('form');
        const value = event.currentTarget.dataset.value;

        // Shop domain
        let shopDomain = (typeof orbito !== 'undefined' && orbito.getCountryDomain) ? (orbito.getCountryDomain() || window.location.hostname) : window.location.hostname;

        // Determine if it is a country_code or language_code change
        const inputCountry = form.querySelector('input[name="country_code"]');
        const inputLanguage = form.querySelector('input[name="locale_code"]');

        // Get the return_to
        const returnToInput = form.querySelector("input[name='return_to']");

        if (inputCountry) {
            // Check if the 'country' parameter exists and if not add it to the URL
            if (returnToInput.value.match(/(\?|&)country=[^&]*/)) {
                // Replace the existing country parameter
                returnToInput.value = returnToInput.value.replace(/(\?|&)country=[^&]*/, `$1country=${value}`);
            } else {
                // Add the country parameter
                if (returnToInput.value.includes('?')) {
                    returnToInput.value += `&country=${value}`;
                } else {
                    returnToInput.value += `?country=${value}`;
                }
            }
            // Update the Orbe cookie for country code
            document.cookie = `mdApp_countryCodeDomain=${value}; domain=${shopDomain}; path=/; max-age=${60 * 60 * 24 * 60};`;
        }
        
        if (inputLanguage) {
            // Update the Orbe cookie for language code
            document.cookie = `mdApp_showRecommendationLang=${value}; domain=${shopDomain}; path=/; max-age=${60 * 60 * 24 * 60};`;
        }

        // Update the input value and submit the form
        this.elements.input.value = value;
        if (form) form.submit();
    }

    openSelector() {
        this.elements.button.focus();
        this.elements.panel.toggleAttribute('hidden');
        this.elements.button.setAttribute('aria-expanded', (this.elements.button.getAttribute('aria-expanded') === 'false').toString());
    }

    closeSelector(event) {
        const shouldClose = event.relatedTarget && event.relatedTarget.nodeName === 'BUTTON';
        if (event.relatedTarget === null || shouldClose) {
            this.hidePanel();
        }
    }
}

customElements.define('localization-form', LocalizationForm);
```

{% endcode %}


# Snippets

Customize Your Storefront with CSS Snippets

Use these CSS snippets to adjust the Welcome popup and selectors when the app embed settings are not enough.

Copy the snippet you need and paste it in [Custom code](/settings/custom-code).

## Snippets library

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Create a full-screen popup</strong></td><td>Turn the Welcome popup into a full-screen experience.</td><td><a href="/pages/XmldqCEJX11tLstARqnX">/pages/XmldqCEJX11tLstARqnX</a></td></tr><tr><td><strong>Country order</strong></td><td>Move selected countries to the top of the country selector.</td><td><a href="/pages/gYwDSy5ZcPT2W8bc54Db">/pages/gYwDSy5ZcPT2W8bc54Db</a></td></tr><tr><td><strong>Language order</strong></td><td>Move selected languages to the top of the language selector.</td><td><a href="/pages/INfzowozismrCuEcD7An">/pages/INfzowozismrCuEcD7An</a></td></tr><tr><td><strong>Hide the popup in a country</strong></td><td>Hide the Welcome popup for visitors from specific countries.</td><td><a href="/pages/3xQcWgSDDL5RoqnZ2vZz">/pages/3xQcWgSDDL5RoqnZ2vZz</a></td></tr><tr><td><strong>Change popup fonts</strong></td><td>Apply custom fonts to specific popup elements.</td><td><a href="/pages/wvnEwdfan5w9CT0cVuy0">/pages/wvnEwdfan5w9CT0cVuy0</a></td></tr><tr><td><strong>Customize dropdown chevron</strong></td><td>Change, hide, or replace the dropdown chevron.</td><td><a href="/pages/QVzy23dXDvdI0eOqoi4Y">/pages/QVzy23dXDvdI0eOqoi4Y</a></td></tr><tr><td><strong>Lock background scroll</strong></td><td>Keep the page behind the Welcome popup from scrolling.</td><td><a href="/pages/7Nxl7R8N10uVINF8tl4V">/pages/7Nxl7R8N10uVINF8tl4V</a></td></tr><tr><td><strong>Hide countries</strong></td><td>Hide specific countries from the Welcome popup or Market selector.</td><td><a href="/pages/Gxwv2w1TdPPRKZYLIfNe">/pages/Gxwv2w1TdPPRKZYLIfNe</a></td></tr></tbody></table>


# Create a full-screen popup

Want to make a bold statement? Transform your Geolocation popup into a full-screen welcoming banner for your customers. Here's how:

<div><figure><img src="/files/4Wd2xKAXZYwKqwhbV4kK" alt=""><figcaption><p>Before</p></figcaption></figure> <figure><img src="/files/Q9GCFqODLrSSjOUbgbif" alt=""><figcaption><p>After</p></figcaption></figure></div>

CSS snippet:

```css
.md-modal__backdrop {
    background:
        -webkit-gradient(
            linear,
            left top, left bottom,
            from(rgba(0, 0, 0, 0.6)),
            to(rgba(0, 0, 0, 0.6))
        ),
        url('[YOUR-URL-IMAGE]');
    background:
        -o-linear-gradient(
            rgba(0, 0, 0, 0.6),
            rgba(0, 0, 0, 0.6)
        ),
        url('[YOUR-URL-IMAGE]');
    background:
        linear-gradient(
            rgba(0, 0, 0, 0.6),
            rgba(0, 0, 0, 0.6)
        ),
        url('[YOUR-URL-IMAGE]');
    background-size: cover;
    background-repeat: no-repeat;
    background-position: center;
}

.md-modal__content {
    background: transparent !important;
    -webkit-box-shadow: none !important;
            box-shadow: none !important;
}

.md-modal__header__title {
    -webkit-box-pack: center;
        -ms-flex-pack: center;
            justify-content: center
}

.md-modal__bodyContent p {
    text-align: center !important;
}
```

**Things to Note**:

* **Image background**: Replace `[YOUR-URL-IMAGE]` with the URL of the background image you desire. To find the URL of your image, navigate to `Content > Files` in your Shopify admin. Need more guidance? [Learn more about uploading files on Shopify](https://help.shopify.com/en/manual/shopify-admin/productivity-tools/file-uploads).
* **Background opacity with linear gradient**: The `linear-gradient` inside the `background` CSS property applies a semi-transparent black overlay on top of your image. This can make text overlaid on the image more readable against its background. If you'd prefer the image without this darkened effect, you can remove the `linear-gradient` sections from the CSS snippet.
* **Solid color background**: If you'd prefer a solid color as a background instead of an image, replace `url('[YOUR-URL-IMAGE])'` with a CSS color code (e.g., `#FF5733`).
* **Stay within the app**: Before diving into custom CSS, check Orbe's features in the Shopify Theme Editor. There might be options to achieve what you want without custom code (e.g., removing the close button, adjusting the button position, modifying font colors).


# Country Order Customization

Country Order Customization in Orbe's Selector

## **Geolocation Popup**

In Orbe, the country list within the selector is alphabetically ordered by default. However, it's possible to customize this order using CSS, allowing you to prioritize certain countries by placing them at the top of the list.

For example, in this country selector, you can see that the United States and the United Kingdom are at the top when you open the selector:

<figure><img src="/files/LtkwbFltuTdPZz5mpLxA" alt=""><figcaption></figcaption></figure>

Here's a step-by-step guide on how to achieve this through Custom CSS:

**Step 1: Modify the Display of the List**

To start, we need to change the display setting of the country list to a grid layout. This allows us to reorder the countries:

```css
.md-form__select__country__list {
    display: grid;
}

.md-form__select__country__list[hidden] {
    display: none;
}
```

**Step 2: Set Default Order**

Next, set a default order for all countries in the list. This ensures that any country not explicitly reordered will follow this default setting:

```css
.md-form__select__country__list li {
    order: 2;
}
```

**Step 3: Reorder Specific Countries**

Now, you can select specific countries and assign them a different order. In this example, we're moving the United States (US) and the United Kingdom (GB) to the top of the list:

{% code overflow="wrap" %}

```css
.md-form__select__country__list li[data-country="US"], .md-form__select__country__list li[data-country="GB"]{
    order: 1;
}
```

{% endcode %}

By adding these CSS classes, you can easily customize the order of countries within the Orbe selector.

Simply replace "GB" and "US" with the country codes of your preferred countries to tailor the list to your needs. This refers to the ISO two-letter code (alpha-2) of the country. You can find the global list of country ISO two-letter codes at [https://countrycode.org/](https://countrycode.org).

### CSS

Here's the complete CSS snippet for repositioning the United States and the United Kingdom at the top of the list:

```css
.md-form__select__country__list {
    display: grid;
}

.md-form__select__country__list[hidden] {
    display: none;
}

.md-form__select__country__list li {
    order: 3;
}

.md-form__select__country__list li[data-country="US"] {
    order: 1;
}
.md-form__select__country__list li[data-country="GB"] {
    order: 2;
}
```

With this customization, you can enhance the user experience by highlighting the most relevant countries for your business.

{% hint style="info" %}
**Accessibility tip**: if countries are visually reordered with CSS, the underlying order in the code (DOM) stays the same. This isn’t fully compliant with accessibility standards (WCAG 2.2 – Meaningful Sequence, Level A). We know highlighting certain countries is important and are working on a solution that allows this without affecting accessibility.
{% endhint %}

### JavaScript

You can also achieve this by using this JavaScript code and adding it to your theme code:

```javascript
document.addEventListener("DOMContentLoaded", function() {
    setTimeout(function() {
        const countryList = document.querySelector("#orbeCountryList");
        const priorityCountries = ["US", "GB"];
        // Loop through each country in reverse order and move it to the top
        priorityCountries.reverse().forEach(countryCode => {
            const countryItem = countryList.querySelector(`li[data-country="${countryCode}"]`);
            if (countryItem) {
                countryList.insertBefore(countryItem, countryList.firstChild);
            }
        });
    }, 1000);
});
```

## Popup Selector

In Orbe's **Market Selector** Popup, you can customize the country order using CSS.

Unlike the Geolocation Popup, the parent container already uses a `grid` display by default, so **you only need to adjust the order of the individual items**.

<figure><img src="/files/mGOF5ol765dCAZDVgljw" alt=""><figcaption></figcaption></figure>

Set all items to a default order and prioritize the desired countries:

```css
.md-modal__footer-selector-modal__region-list-item {
    order: 3;
}

.md-modal__footer-selector-modal__region-list-item[data-country="FR"] {
    order: 1;
}

.md-modal__footer-selector-modal__region-list-item[data-country="ES"] {
    order: 2;
}
```

In this example:

* France (`FR`) appears first.
* Spain (`ES`) appears second.
* All other countries are shown below.

Replace the country codes (`ES`, `FR`) with your preferred ISO alpha-2 codes as needed. You can find the global list of country ISO two-letter codes at [https://countrycode.org/](https://countrycode.org).


# Language Order Customization

In Orbe, the language list within the selector is ordered by default according to how it's being added to Shopify. However, it's possible to customize this order using CSS, allowing you to prioritize certain languages by placing them at the top of the list.

For example, in this language selector, you can see that Dansk and Italian are at the top when you open the selector:

Here's a step-by-step guide on how to achieve this through Custom CSS:

<figure><img src="/files/9YxpJh10rtR3fn6lln7u" alt=""><figcaption></figcaption></figure>

**Step 1: Modify the display of the list**

To start, we need to change the display setting of the language list to a grid layout. This allows us to reorder the languages:

```css
.md-form__select__language__list {
    display: grid;
}

.md-form__select__language__list[hidden] {
    display: none;
}
```

**Step 2: Set Default Order**

Next, set a default order for all languages in the list. This ensures that any language not explicitly reordered will follow this default setting:

```css
.md-form__select__language__list li {
    order: 2;
}
```

**Step 3: Reorder Specific Languages**

Now, you can select specific languages and assign them a different order. In this example, we're moving English (EN) and Spanish (ES) to the top of the list:

```css
.md-form__select__language__list li[data-locale="it"], 
.md-form__select__language__list li[data-locale="da"] {
    order: 1;
}
```

Adding these CSS classes allows you to customize the order of languages within the Orbe selector easily. Just replace `"it"` and `"da"` with the language codes of your preferred languages to tailor the list to your needs. This refers to the ISO two-letter code (alpha-2) of the language.

## Complete Code Example

Here's the complete CSS snippet for repositioning Italian and Dansk at the top of the list:

```css
.md-form__select__language__list {
    display: grid;
}

.md-form__select__language__list[hidden] {
    display: none;
}

.md-form__select__language__list li {
    order: 2;
}

.md-form__select__language__list li[data-locale="it"], 
.md-form__select__language__list li[data-locale="da"] {
    order: 1;
}
```

With this customization, you can enhance the user experience by highlighting the most relevant languages for your customers.


# Hide the popup in a country

Orbe allows you to hide the modal in specific countries using custom CSS classes based on the customer's location.

{% hint style="warning" %}
**Warning:** This approach is not recommended.

Orbe's purpose is to always guide users to the correct store version, as Shopify storefronts are designed per country not market. Even if prices or currencies appear the same, other configurations—such as shipping, customs, taxes, or content—can vary by country.

Use this method only if you fully understand the potential negative impact on user navigation.
{% endhint %}

To hide the modal in specific countries, you can use CSS variables. Orbe adds a custom class to the theme's body element, which can be used to apply customizations across the entire theme.

The CSS class is named orbe-country-code--COUNTRYCODE, where COUNTRYCODE is the two-letter ISO code of the country where the customer is located. We will also add the class md-app-embed to ensure proper functionality.

For example, if we want to hide the Orbe modal in the French, we would need to add the following CSS code.

```css
.orbe-country-code--FR .md-app-embed {
	display: none !important;
}
```


# Change popup fonts

To change the `font-family` of specific parts of the popup, you need to target the appropriate CSS class for that element.

{% hint style="warning" %}
**Important:** Make sure the font you want to use is already installed in your theme or actively loaded; otherwise, it won’t work.
{% endhint %}

For example, to change only the font of the popup title, use the following CSS in [Custom code](/settings/custom-code):

```css
.md-modal__header__title span {
    font-family: 'Gluten';
}
```

Replace `'Gluten'` with the desired font-family name of your theme.

{% hint style="info" %}
**Accessibility tip**: if you change the font or font size, use relative units (like rem or %) instead of fixed pixels. Text should scale up to 200% in browser settings without losing content or functionality (WCAG 2.2 – Resize Text, Level AA).
{% endhint %}

## Popup element classes

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><strong>Title</strong></td><td><code>.md-modal__header__title span</code></td><td><a href="/files/RB8hQPx4tFmkMXuHMBvu">/files/RB8hQPx4tFmkMXuHMBvu</a></td></tr><tr><td><strong>Text</strong></td><td><code>.md-modal__bodyContent p</code></td><td><a href="/files/solzAI990e7s8a7ZON0G">/files/solzAI990e7s8a7ZON0G</a></td></tr><tr><td><strong>Helper text</strong></td><td><code>.md-modal__bodyContent__helperText</code></td><td><a href="/files/tpAi8lPQK2iQrC91nn77">/files/tpAi8lPQK2iQrC91nn77</a></td></tr><tr><td><strong>Labels</strong></td><td><code>.md-modal__formContent__selectLabel</code></td><td><a href="/files/1XnHvLi6Vqa2sUr4Sday">/files/1XnHvLi6Vqa2sUr4Sday</a></td></tr><tr><td><strong>Selectors</strong></td><td><code>#md-app-embed__modal .md-form__select, #md-app-embed__modal .md-form__select__country__list-link-wrapper span</code></td><td><a href="/files/1MWaXlIA6Xq5um14rKEb">/files/1MWaXlIA6Xq5um14rKEb</a></td></tr><tr><td><strong>Button</strong></td><td><code>.md-btn__primary</code></td><td><a href="/files/G7qbw7UrmDVSQRK2U1K4">/files/G7qbw7UrmDVSQRK2U1K4</a></td></tr></tbody></table>

{% hint style="info" %}
You can also use these CSS classes to apply additional specific styles **that are not available in the app embed settings**. If a style is already provided in the app embed, please use that option instead.
{% endhint %}


# Customize dropdown chevron

Change, hide, or replace the dropdown chevron with Custom CSS.

The Geolocation Popup chevron is not a separate HTML element. It is an SVG used as the dropdown button's CSS `background-image`.

This is generic Orbe CSS, not theme-specific. Paste it in Orbe Geolocation under [Custom code](/settings/custom-code)

Override both the closed and open states, and keep `!important`.

```css
#md-app-embed__modal .md-form__select {
    background-image: url("YOUR_CSS_SVG_HERE") !important;
}

#md-app-embed__modal .md-form__select[aria-expanded="true"] {
    background-image: url("YOUR_CSS_SVG_HERE") !important;
}
```

**Do not paste a raw SVG into CSS.** Edit the SVG, convert it with the free [SVG to CSS tool](https://www.svgbackgrounds.com/tools/svg-to-css/), then paste the resulting value into `background-image`.

You can use this override to:

* Change the chevron color, thickness, or shape with a converted SVG.
* Hide it with `background-image: none !important;`.
* Use an icon file with `background-image: url("https://example.com/icon.svg") !important;`.

The default position is `background-position: right 6px center;`.

For the Country Selector app block or the Market Selector app embed using the dropdown type, keep the same `background-image` override, open state, `!important`, and SVG conversion. Only change the parent wrapper to `.md-orbe-selector__content` for the Country Selector or `.md-footer-selector__content` for the Market Selector.


# Lock background scroll

Lock the page background while the Orbe Welcome popup is open.

Use this CSS to stop the page behind the Welcome popup from scrolling while the popup is open.

Paste it in Orbe, under [Custom code](/settings/custom-code).

```css
body.orbe--opened {
    overflow: hidden !important;
}

html:has(> body.orbe--opened) {
    overflow: hidden !important;
}

body.orbe--opened #orbeCountryList,
body.orbe--opened #orbeLanguageList {
    overflow-y: auto !important;
    overscroll-behavior: contain;
    -webkit-overflow-scrolling: touch;
}
```

Orbe adds `orbe--opened` to the `body` when the Welcome popup is open. The class is removed automatically when the popup closes, so the background scroll is locked only while the popup is visible.

The country and language lists remain scrollable.


# Hide countries

{% hint style="warning" %}
In Orbe, we do not recommend excluding countries for the following reasons:

1. **Automatic Preselection:** Our technology automatically preselects the country based on the user's location. Therefore, if your concern is that the list will appear too large, it's not an issue, as the user's country will already be preselected by default.
2. **Maintaining user experience:** We advise against hiding countries from the selector because if a country is included in the list, it's because it's configured as a country you ship to in your Shopify Markets settings. Thus, the customer can still place an order from that country when they reach the checkout. Excluding it from your country selector or geolocation popup only makes their experience more frustrating without any real benefit.
3. **Shopify's localization structure:** It's crucial to understand that on Shopify, localized experiences are based on countries and not markets. E.g. Even if you have a market for the EU with several European countries, each country has its own frontend experience in Shopify's backend and server rendering. This differentiation is necessary because each country within a region may have different shipping policies, product availability, or tax regulations.
   {% endhint %}

## **Tutorial**

Considering these factors, if you still wish to hide a country from the **Orbe Geolocation Popup** selector, you can do so by adding the following CSS:

```css
.md-form__select__country__list li[data-country="XX"] {
    display: none !important;
}
```

Here, "XX" refers to the ISO two-letter country code. You can find a global list of country ISO two-letter codes at [countrycode.org](https://countrycode.org/).

**Example:** Suppose you want to hide Germany, the United Kingdom, and Japan. You can achieve this with the following CSS:

```css
.md-form__select__country__list li[data-country="DE"],
.md-form__select__country__list li[data-country="GB"],
.md-form__select__country__list li[data-country="JP"] {
    display: none !important;
}
```

This CSS will hide the specified countries from the Orbe Geolocation Popup selector. Remember to replace "DE," "GB," and "JP" with the appropriate country codes for the countries you want to hide.

If you want to achieve the same customization in the **Market Selector**, you can use a similar CSS approach.

To hide a specific country from the Market Selector, apply the following CSS:

```css
.md-modal__footer-selector-modal__region-list li[data-country="XX"] { 
    display: none !important;
}
```

**Example:** Suppose you want to hide Germany, the United Kingdom, and Japan. You can achieve this with the following CSS:

```css
.md-modal__footer-selector-modal__region-list li[data-country="DE"],
.md-modal__footer-selector-modal__region-list li[data-country="GB"],
.md-modal__footer-selector-modal__region-list li[data-country="JP"] {
    display: none !important;
}
```

This CSS will hide the specified countries from the Market Selector. Remember to replace "DE," "GB," and "JP" with the appropriate country codes for the countries you want to hide.

By following these steps, you can customize both the Geolocation Popup selector and the Market Selector to suit your specific needs. However, we recommend careful consideration before hiding countries to ensure your customers' best possible user experience.