Zonos for Shopify installation guide

Zonos Checkout is a private Shopify app not listed on the app store and includes Zonos Hello.

Please follow the instructions on this page or in the app once you have downloaded the extension.

IMPORTANT: Please note that any theme changes may “break” the current set-up. Please test once changes have been made to make sure functionality still remains.

Install the app

  1. Log in to your Shopify store.
  2. To install the app, go to https://plugins.iglobalstores.com/shopify/app.
  3. Paste your store domain in the following format: subdomain.shopify.com
  4. You will see the Shopify installation page. Click Install unlisted app. Fig. 1 - install app
  5. Once you install the app, you will be taken to the Zonos/iGlobal app for Shopify page to begin configuration.


  1. On the Zonos/iGlobal app for Shopify page, begin by choosing the activation level you want for Zonos Hello. We suggest you start with Test Mode. Fig. 2 - app page
  2. To find your Zonos Store ID Number and Zonos API Key, open a new tab and go to https://app.zonos.com
  3. Go to Plugins > Shopify. Fig. 3 - plugins Fig. 4 - Shopify plugin
  4. Copy the values for the Zonos Store ID Number and API Key and paste them into your Account Settings section in the Zonos/iGlobal app for Shopify page, then click Save.
  5. To find your Zonos Hello Site Key, go back to https://app.zonos.com > Zonos Hello on the left sidebar menu. Fig. 5 - Zonos Hello
  6. Enter your Store ID Number in the Zonos app search box, then find your store in the results.
  7. Copy the Zonos Hello Site Key value and paste in your Account Settings section in the Zonos/iGlobal app for Shopify page. Fig. 6 - Zonos Hello site key
  8. Confirm that all your information is correct, then click Save again.
  9. If you want to turn ON duty and tax quotes for Zonos Hello, check the boxes next to Enable Product Quote and Enable Cart Quote. Fig. 7 - duty and tax quotes
  10. If you would like to configure the rest of the fields on this page, you can follow the instructions in the following sections below; otherwise, you can move on to the next step.
  11. In your Zonos/iGlobal app for Shopify, select Installation Instructions from the top menu. Keep this tab open. Fig. 8 - installation instructions
  12. Right-click on the layout/theme.liquid link to open a new tab that will redirect you to the appropriate file. Fig. 9 - online store
  13. Select Actions > Customize > Edit code. This will take you to your theme files. Fig. 10 - edit code
  14. In layout/theme.liquid file, copy the following code and paste it to the bottom of your theme.liquid file before the closing body tag (i.e. </body>).
    {% include 'iglobal' %}

    For example: Fig. 11 - iglobal snippet

    • Note: If you cannot see the closing body tag, you may need to search using CMD-f on a MAC or CTRL-f on Windows/Linux. If there is not a closing body tag, place the code right after the opening body tag.
  15. Click Save.
  16. In a separate window, input the following URL: “yourdomain.myshopify.com?zonos=true”. This will enable Zonos Hello to show up in Test Mode.
  17. Check to see if Zonos Hello has shown up on your site. You can edit Zonos Hello’s serviced countries and placement in the app.zonos.com under the Zonos Hello tab.
    • Domestic and non-serviced countries will half-hide themselves. Fig. 12 - half Hello
    • International, serviced countries will display a floating Zonos Hello. Fig. 13 - floating Hello

Hide domestic elements for international customers

This section walks you through hiding any element that only needs to be shown to domestic customers. Some common elements to hide include features that will already be handled on the international checkout or found on the cart page.

Examples include any third-party checkout button (e.g. PayPal or Amazon Pay buttons), financing buttons, shipping estimates, and taxes.

Fig. 14 - checkout buttons

Fig. 15 - calculate shipping

  1. To hide domestic elements, go to the Shopify admin > Apps > iGlobal Stores > Hide Domestic Elements. Fig. 16 - hide domestic elements
  2. Add an item or product to the cart, then go to the cart page.
  3. Find the element’s selector. You can use any method, but we recommend using Inspect Element to find them. (Use a “#” for ids and a “.” for classes.)
    • If you do not know how to use inspect element to hide domestic, click here to review the instructions; otherwise, continue to the next step.  Fig. 17 - input selectors
    • The example selectors above work for hiding the shipping estimate form, PayPal button, and Amazon Pay button for the ig-dev site. (Note: By default, the iGlobalStores’ code will hide any elements under the classes: additional-checkout-button and additional-checkout-buttons.)
  4. Test on the site by changing the country to an international country to hide the selectors.
  5. Change the country back to a domestic to make sure the element displays again. (Note: Use ?zonos=true or zTestMode=true.)
  6. Click Save.

Using inspect element to hide domestic

Go to your store website, then add a product to your cart. Next, go to your cart page and take note of any buttons that you need to hide e.g. third-party checkout buttons like PayPal.

The following example tutorial will show you how to hide the button labeled “Hide Me”. Fig. 18 - hide me

  1. Right-click the product, then select Inspect. Fig. 19 - inspect
  2. Your computer will pul up Developer Tools to display either on the right or at the bottom of your browser.
    • You can also hover over the Developer Tools to make the different sections bigger or smaller.
    • Make sure you are on the Elements tab, which will show you all the HTML (or content) from your website in markup.
  3. The HTML of the button should be highlighted. Using your cursor, you can hover over the highlighted element in the Developer Tools to highlight the button. Fig. 20 - dev tools

Fig. 21 - highlighted

  1. Look at the class or id section of the button in HTML. There are three classes that define this element: btn, btn--small-wide, and hide-this-button.
  2. Because classes can be applied to multiple elements on the page, grab the MOST specific class you can find.
    • In this example, it is hide-this-button, because it is not a class that can usually be applied to other uses.
    • On your page, the element you likely need to hide is something like paypal-button or estimate-shipping.
    • If you need to grab an id, you would use a “#”. If you need to grab a class, you would use “.”.
  3. To make sure the correct button class is grabbed, you need to query the selector.
    • Go to the Console tab of Developer Tools. (Note: You can use a shortcut to get to the Console tab by hitting the ESC key.)
    • Write the following line of JavaScript in the Console tab: document.querySelectorAll('');
    • For example, to grab class="hide-this-button", you would put .hide-this-button in the quotes.
    • If the button you input does not hide in the element, you may need to find an element that is higher up in the HTML and encompasses the element that did not work.
    • In this example, only one result for the class=“hide-this-button” was found.
  4. Next, copy the selector e.g. hide-this-button into the Shopify admin > Apps > iGlobal Stores > Hide Domestic Elements section, then Save. Fig. 22 - hide domestic elements
  5. Return to your cart page and enter ?zonos=true in the URL to activate test mode.
  6. Toggle Zonos Hello from a domestic country to an international country; the button should now be hidden.


Fig. 23 - before cart


Fig. 24 - after cart

Enable currency conversion

  1. Go to the Shopify admin > Apps > iGlobal Stores, then click on the check box to enable currency conversion.
  2. In the Shopify sidebar menu, go to Settings > General > Store currency, then click on the Change formatting link.
  3. Change the currency format to look like below, then click Save.
    • HTML with currency: <span class='money'>${{amount}} USD</span>
    • HTML without currency: <span class='money'>${{amount}}</span>
  4. Immediately check the website for errors, and test to see if the currency is converting by doing the following:
    • Add ?zonos=true to the URL.
    • Switch Zonos Hello to an international country.


  1. If some but not all currency is converting, grab the currency selectors not converting and put them in the currency selector input box located in Shopify Admin > Apps > iGlobalStores > Foreign Currency. (Note: If you do not know how to grab selectors, click here to read the tutorial.)
    • Find the right selectors to pass into the configuration by going to each of the different page types on your website to inspect the currency.
    • Grab the selectors referencing the currency. Place them within the quotation marks, separating different selectors by commas.
    • Make sure to add .money in with the rest of your selectors (separated by commas and a space).
    • For example: Fig. 25 - Foreign Currency
  2. If no currency is converting, put double quotes around the money class in the settings as shown below:
    • HTML with currency: <span class="money">${{amount}} USD</span>
    • HTML without currency: <span class="money">${{amount}}</span>
  3. If you are experiencing double conversion, you may have added a parent selector and a child selector - so it is converting twice.
    • Example: <div class="product-price"> <span class="money">$49.99</span></div>`

      Note: Make sure you only grab .money and not .product-price or it will convert twice.

Getting to international checkout

In your Shopify store, go to Online Store > Themes.

Fig. 26 - themes

Click on the Actions button drop-down menu for the theme you want to work on (e.g. Current theme), then select Edit code.

Fig. 27 - Actions

As each Shopify theme is unique, you will need to do the following:

(1) Redirect buttons to the Zonos international checkout
  1. Place the following attribute on all buttons you need to redirect to the Zonos international checkout: onclick="zonosCheckout(event)"

Fig. 28 - redirect

(2) Manually search for the file with the correct checkout buttons.

As there is no easy, dynamic way to search for the correct checkout buttons you need to redirect, you will need to search manually for the file with the checkout buttons. Search for the likely places the correct checkout buttons may be, e.g. cart.liquid, cart-template.liquid, theme.liquid, sidecart.liquid, ajaxcart.liquid, or bag.liquid.

Recommendations: Look at the URL to figure out which file you need for finding the button or review your site’s shopping process, e.g. adding an item to the cart and where to check out on the site. For example, if you have a side cart that redirects to your checkout - in your theme files, you will want to search for sidecart.liquid or ajaxcart.liquid.

The following example tutorial will show you how to search in cart.liquid:

  1. Search for the file e.g. “cart” for cart.liquid. Fig. 29 - cart template
  2. Click on the cart-template.liquid.
  3. Search for the checkout buttons, using CTRL-f for Windows/Linux or CMD-f for Mac. The example below shows what a generic checkout button would look like. This may vary by store. Fig. 30 - generic checkout button
  4. The example below shows the attribute placement within the file. This attribute puts an onclick method onto your button so when the button is clicked, the function zonosCheckout will be triggered. This will take you to international checkout if Zonos Hello is set to a serviced, international country. It does not matter where you put the attribute, as long as it is within the HTML element. Fig. 31 - attribute placement
  5. Once you have inserted your attribute, click Save.
  6. If the checkout buttons are not in cart-template.liquid, try cart.liquid and theme.liquid.

Note: You can also download the theme and use an editor to search for the buttons.

(3) Test to make sure the buttons redirect to international checkout
  1. In a separate tab, go to your store site and do a hard refresh.
  2. Select a few different items for checkout, then go to the cart page. Make sure you add ?zonos=true in the URL.
  3. Check out using an international country to confirm it redirects to the international checkout. >*Note: You can check if the onclick=”zonosCheckout(event)” attribute got applied to the correct button by using Inspect Element.
  4. Check out using a domestic country to confirm you are still going to the domestic checkout.

Test your international checkout

  1. If you are in test mode, ensure you include the following in the URL to make the page temporarily enable Zonos Hello code: ?zonos=true
    • You can use the following if you want test mode to be turned ON the whole time you navigate to the site: ?zTestMode=true
    • To turn OFF test mode when using ?zTestMode=true, use ?zTestMode=false
  2. Click the checkout button.
  3. If the zonosCheckout() attribute is correctly placed on your checkout buttons, you will be able to reach the Zonos international checkout.
  4. While in test mode with ?zonos=true and ?zTestMode=true, also check for the following:
    • Confirm all items that must be hidden on international are hidden when Zonos Hello is not in US. Then, make sure the hidden items reappear when Zonos Hello is back in US.
    • Confirm that duty+tax gives each product a quote.
    • Confirm all checkout buttons get to Zonos Checkout on an international country and go to their domestic checkout on US.
    • Check all pop-ups and side carts.
    • Change the quantity of an item. Confirm that currency conversion and the checkout button still work.
    • Test on the mobile version of the site.
  5. If you feel confident with your installation and have verified all tests, go to Shopify admin > Apps > iGlobal Stores > Activate Zonos and click on the Enabled radio button to go LIVE with your site.

Shopify theme change

The following instructions address what you need to do when changing your Shopify theme.

  1. Open the iGlobal Stores app in your Shopify backend, then go to the Installation Instructions.
  2. In a new tab, open the theme.liquid file for your new Shopify theme.
  3. Add the iglobal snippet to the file. Fig. 32 - install iglobal snippet
  4. To confirm the iglobal.liquid file is present in your new theme files, go to your code editor and type “iglobal” in the top-left search bar. Fig. 33 - iglobal search
  5. If you find the iglobal file, you are done. If you do NOT find the iglobal file, proceed to the next step.
  6. Go to your previous theme files.
  7. Find the iglobal.liquid file via the top-left search bar.
  8. Highlight all the content of the iglobal.liquid file.
    • CTRL-A for Windows/Linux
    • CMD-A for Mac
  9. Copy the highlighted content.
    • CTRL-C for Windows/Linux
    • CMD-C for Mac
  10. Once copied, return to your new theme files.
  11. Under the Snippets section, select Add a new snippet, and name the file: “iglobal”.

Fig. 34 - add snippet

  1. Paste the contents you previously copied into the newly created iglobal snippet.
    • CTRL-V for Windows/Linux
    • CMD-V for Mac
  2. Hide your domestic elements again.
  3. Also, re-set your “onclick” attribute for your checkout buttons to get to international checkout.

Domestic redirect for Shopify Plus

Important: Do NOT follow the instructions below until you are ready to go live.

The instructions below are only applicable to Shopify Plus merchants. This section will show you how to redirect a Shopify Plus store from your domestic checkout when a customer selects an international country.

Note: Make sure you have checkout.liquid enabled in your theme files. If you do not, you need to call Shopify and have this feature enabled.

  • The Shopify checkout is updated twice a year. Updating may remove previous customizations that Zonos has made from the checkout.liquid file.
  1. In the theme files, under Snippets, select Add a new snippet. Fig. 35 - add snippet
  2. Name the file “zonos-checkout”. Then click on Create snippet. Create snippet
  3. In the Shopify service, pull up the file called zonos-checkout.liquid. Copy the contents of this file to the zonos-checkout.liquid file you just created.
  4. Under Layout in the theme files, select Add a new layout.
  5. Select Create a new layout from checkout called checkout and then, click on Create layout. Figure 36 - Create layout
  6. Add the following script to the file before the closing </body> tag:
{% include 'zonos-checkout' %}

Zonos checkout script

Zonos recommends

  • Ensure you ship your items DDP (Delivered Duty Paid) if taxes were paid in advance; otherwise, your customer will be billed at checkout and upon delivery.
  • Note that orders may be delayed on import if they are in a fraud review (validating) state to make sure fraudulent orders are not shipped out.

IMPORTANT: Please note that any theme changes may “break” the current set-up. Please test once changes have been made to make sure functionality still remains.