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. 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. Plugins
  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.
  6. Copy the Zonos Hello Site Key value, then paste it in your Account Settings section in the Zonos/iGlobal app for Shopify page. Zonos Hello site key
  7. Confirm that all your information is correct, then click Save again. Confirm changes
  8. We recommend using your Shopify emails for customers; that way, the emails will match the aesthetic of your store.
  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.
  10. Make sure to Save after any setting changes.
  11. In your Zonos/iGlobal app for Shopify page, at the top left - select Installation Instructions from the top menu. Make sure to keep this tab open for grabbing information. Installation instructions
  12. Copy the {% include 'iglobal' %} from this page.
  13. Right-click on the layout/theme.liquid link to open a new tab that will redirect you to the appropriate file. Online store
  14. You can also select Online Store > Select your current theme > Go to Actions > Edit Code.
  15. In layout/theme.liquid file, paste the code from step 12 to the bottom of your theme.liquid file before the closing body tag (i.e. </body>).

For example: iGlobal snippet

Getting to international checkout

In your Shopify store, go to Online Store > 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.


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

(a) 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)" Redirect
  2. We recommend opening your website and placing an item in your cart. From there, go to your cart page or open your side cart.
  3. Right-click and open the Developer Tools, and Inspect the checkout button.
  4. As you can see, this checkout button has some unique attributes: “data-role”, “title”, and the “class”. You can use these to find the checkout button in your theme files.
(b) 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. 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. 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. Once you have inserted your attribute, click Save. Attribute placement
  5. If the checkout buttons are not in cart-template.liquid, try cart.liquid and theme.liquid.

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

(c) 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. (You may also need to clear your cache.)
  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.

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.

Checkout buttons

Calculate shipping

  1. To hide domestic elements, go to the Shopify admin > Apps > iGlobal Stores > Hide Domestic Elements. 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. 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.)
    • Save the new domestic selectors.
  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.)

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”. Hide me

  1. Right-click the product, then select Inspect. Inspect
  2. Your computer will pull 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. Dev tools Highlighted
  4. 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.
  5. 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 “.”.
  6. 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.
  7. 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
  8. Return to your cart page and enter ?zonos=true in the URL to activate test mode.
  9. Toggle Zonos Hello from a domestic country to an international country; the button should now be hidden.


Before cart


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: 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.

Note: Any other currency custom requests will be charged for by Zonos. The cost of the requests will be determined by the hours it takes the developer to complete.

Domestic redirect for Shopify Plus

Important: Do NOT start working on this section 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. 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. Create layout
  6. Add the following script to the file before the closing </body> tag:
{% include 'zonos-checkout' %}

Zonos checkout script

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. 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. 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”. Add snippet
  12. Paste the contents you previously copied into the newly created iglobal snippet.
    • CTRL-V for Windows/Linux
    • CMD-V for Mac
  13. Hide your domestic elements again.
  14. Also, set your “onclick” attribute for your checkout buttons to get to international checkout.

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.