Zonos logo
DOCS

Integrating hello

/

Install Zonos Hello on your site 

Learn how to install Zonos Hello for your store website. 

If you are using Shopify, BigCommerce, Magento, Miva, or X-Cart, see our plugins section.

The script below will add the Zonos Hello flag to your site, recognize the country your customers are visiting from, greet them, and give general duty and tax information for their country.

Additional features are available with minimal development work (shown below).

Instructions

SKILLS NEEDED : Basic web skills

To install Hello, apply the custom script containing your unique site key into your website before the closing body tag.

Hello integration script

1
<script src="https://hello.zonos.com/hello.js?siteKey=YOURSITEKEY"></script>

Zonos Hello must be loaded before any additional functionality is added. Please include any additional features after the above script.


Don’t already have a script? Click here to download.

Generate an estimated duty and tax quote

SKILLS NEEDED : Basic developer skills

When this feature is enabled, Hello can provide duty and tax estimates when a product is viewed or added to the cart. Hello can also display full duty and tax quotes to the whole cart when the page is viewed.

The duty and tax quote can go on each product page or your main product page, depending on how your platform is set up.

To add the duty and tax quote, apply a script that looks like the one shown below. The two required fields are name and price.

Hello integration script

1
2
3
4
5
6
7
8
9
10
11
zonos.quote({
    items: [{
        name: "The name of the product",
        price: 19.95,
        quantity: 2,
        image: "https://example.com/product-123.png",
        url: "https://example.com/product-123",
        sku: "123"
    }],
    currencyCode: "USD",
})

Scripts that can be used will need to be adjusted to make them work for your site. Please make sure any of the following scripts you use are placed after the initial Zonos Hello Script.

If you are not using a platform, you can use the following to dynamically grab your product details. This script will grab the first product available. You can also adjust this script to be used on the cart page of your site. You will need to loop through all products and their data, then send that to the zonos.quote.

Hello integration script

1
<script>
  var zPrice = '';
  var zName = '';
  var zImg = '';

try {
if (document.querySelector('ID OR CLASSNAME') != null) {
zPrice = document.querySelectorAll('ID OR CLASSNAME').innerText;
}

    if (document.querySelector('ID OR CLASSNAME') != null) {
      zName = document.querySelector('ID OR CLASSNAME').innerText;
    }

    if (document.querySelector('.ID OR CLASSNAME') != null) {
      zImg = document.querySelector('ID OR CLASSNAME').src;
    }

    zonos.quote({
      items: [{
        name: zName,
        price: zPrice,
        image: zImg
      }],
      currencyCode: "USD",
    });

}
catch(error){}

</script>

You can add additional values from the item fields down below and also change the currencyCode to be your default currency.

Shopify

If you are using Shopify as your platform, we have a script you can use that will pull the product data from your Shopify product details.

The below code has a function that will run on the product pages and the cart page.

Hello integration script

1
<script>
  function znDutyTaxEstimateOnDetailPage() {
      {% if product and product.price %}
        zonos.quote({
          items: [{ price: "{{ product.price | money_without_currency }}", name: "{{product.title | replace: '"', '\"'}}", url: "{{ shop.secure_url }}{{ product.url }}", image: "https:{{ product.featured_image | product_img_url: 'medium' }}"}],
          currencyCode: '{{ shop.currency }}'

        });

    {% endif %}

}

function znDutyTaxEstimateOnCartPage() {
if (window.location.href.indexOf("cart") > -1) {
zonos.quote({
items: [
{% for item in cart.items %}
{ price: "{{ item.price | money_without_currency }}", quantity: {{item.quantity}}, name: "{{ item.title | replace: '"', '\"'}}", url: "{{ shop.secure_url }}{{item.url}}", image: "https:{{item.image| product_img_url: 'medium'}}"},
{% endfor %}
],currencyCode: '{{ shop.currency }}'});
}
}

znDutyTaxEstimateOnDetailPage();
znDutyTaxEstimateOnCartPage();

</script>

BigCommerce

If BigCommerce is your shopping cart platform, we have a script you can use that will pull product information directly from your product details for the Zonos quote.

You will need to add one or both of these scripts (depending on your preference) to your BigCommerce Script Manager.

The following script will run Hello quotes on your product pages.

Hello integration script

1
<script>
    if(window.location.href.indexOf("/cart.php") == -1) {
            let cc = getCookie('currencyCode');
            if(!cc){
                cc = "USD";
            }
        zonos.quote({
            items: [{
                price: "{{#if product.price.with_tax}}{{product.price.with_tax.value}}{{else}}{{product.price.without_tax.value}}{{/if}}",
                name: "{{product.title}}",
                url: "{{product.url}}",
                image: "{{getImage product.main_image 'zoom_size' (cdn theme_settings.default_image_product)}}",
            }],
            currencyCode: cc
        });
    }
    function getCookie(cname) {
          var name = cname + "=";
          var decodedCookie = decodeURIComponent(document.cookie);
          var ca = decodedCookie.split(';');
          for(var i = 0; i <ca.length; i++) {
              var c = ca[i];
              while (c.charAt(0) == ' ') {
                  c = c.substring(1);
              }
              if (c.indexOf(name) == 0) {
                  return c.substring(name.length, c.length);
              }
          }
          return "";
      }
</script>

The following will run quotes on your cart page.

Hello integration script

1
<script>
    if(window.location.href.indexOf("/cart.php") > -1) {
        let cc = getCookie('currencyCode');
        if(!cc){
            cc = "USD";
        }
        try {
            var xhr = new XMLHttpRequest();
            var i = 0;
            xhr.open('GET', '/api/storefront/carts');
            xhr.setRequestHeader('Content-Type', 'application/json');
            xhr.onload = function () {
                if (xhr.status === 200) {
                    try {
                        var cid = JSON.parse(xhr.responseText);
                        lineItems = cid[0].lineItems.physicalItems;
                        var items = [];
                        for(var i in lineItems){
                            items.push({
                                price: lineItems[i].salePrice,
                                name: lineItems[i].name,
                                url: lineItems[i].url,
                                image: lineItems[i].imageUrl
                            });
                        }
                        zonos.quote({
                            items: items,
                            currencyCode: cc
                        });
                    } catch (e) {}
                }
            };
            xhr.send();
        } catch (e) {}
    }
    function getCookie(cname) {
          var name = cname + "=";
          var decodedCookie = decodeURIComponent(document.cookie);
          var ca = decodedCookie.split(';');
          for(var i = 0; i <ca.length; i++) {
              var c = ca[i];
              while (c.charAt(0) == ' ') {
                  c = c.substring(1);
              }
              if (c.indexOf(name) == 0) {
                  return c.substring(name.length, c.length);
              }
          }
          return "";
      }
</script>

Quote fields

FieldData typeDescription
itemsarray REQUIREDA list of items to include in the quote
currencyCodestringThe item prices will display in the currency specified by the three-character currency code. Default: USD
includedTaxRatenumberThe item tax rate if the item includes tax
showDecimalboolToggles on | off showing the decimal value on converted currencies

Item fields

FieldData typeDescription
namestring REQUIREDThe product name
pricenumber REQUIREDUnit price of a single product
quantityinteger NOT REQUIREDThe number of products in the cart. Default: 1
imagestring NOT REQUIREDURL of the product image
urlstring NOT REQUIREDURL to the individual product
hsCodestring NOT REQUIREDThe Harmonized Code (HS code) for your product
categorystring NOT REQUIREDThe product’s category on your site
countrystring NOT REQUIREDTwo-character ISO code of the country this product originated from
customizationstring NOT REQUIREDProduct customization (e.g. size, color)
descriptionstring NOT REQUIREDThe detailed description of the product
skustring NOT REQUIREDThe UPC or SKU of the product

As you provide more details to Zonos about your product, the accuracy of the estimate will usually be improved.

Change the Zonos Hello flag and information dialog location

SKILLS NEEDED : Basic developer skills

By default, the Zonos Hello flag will appear in the lower right corner of your page.

Here you will find some information on how to change the location of the flag as well as hiding certain elements of your website that you don't want internationals to see.

Example: Hiding free shipping from internationals; this will also enable you to hide Zonos Hello from domestic customers and specific countries.

If the location is left blank, the code will use the default.\

Hello integration script

1
2
zonos.config({location: 'right bottom attached'});
zonos.config({location: ''});

For the bottom-left corner:

zonos.config({location: 'left'});

For the top-left corner with a floating information dialog:

zonos.config({location: 'left top floating'});

  • floatingrefers to the Hello information dialog that floats in the center of the page.
  • attached refers to the Hello information dialog to open over the flag.
  • floating is preferred when positioning the flag at the top.

Hide specific content for Zonos Hello

SKILLS NEEDED :** Basic developer skills**

The z-intl class is based off of the current domestic country. If Hello is set to an international country, the z-intl class will act as a hidden class, hiding the content that .z-intl is tied to.

Use the following CSS to hide content. Replace .your-content with floating content you want hidden.
.z-intl .your-content { display: none; }

Now you can hide Hello from your domestic customers so other dialogs are visible again.

Hello integration script

1
2
 #zonos { display: none; }
 .z-intl #zonos { display: block; }

Hide Zonos Hello for specific countries

Add the #zonos id combined with the country code that doubles as the CSS class for that country to the .z-intl { display: none; } function.

The line should look something like this:

Hello integration script

1
.z-intl #zonos.US { display: none };

Turn on/off Zonos Hello splash

SKILLS NEEDED :** Basic developer skills**

Splash refers to the pop-up and enlargement of the Zonos dialog box, which contains additional information regarding their country’s specific duty and tax policy.\

If you would like to turn ON and display the Zonos Hello splash for your customers’ first visit:

Hello integration script

1
zonos.config({showSplash:true});

If you would like to turn OFF the Zonos Hello splash for your customers’ first visit:

Hello integration script

1
zonos.config({showSplash:false});

Next steps

  • Hello settings - Easily configure Hello settings, including enabled countries, site placement, and more.
  • Zonos Landed Cost - Need duty and tax calculations at checkout? Learn how you can get automated landed cost for your business.
  • Zonos Checkout - Learn about the best international checkout to simplify the cross-border buying experience.

Related Decoder Guides

FAQ

I’m not a developer and need assistance. What are my options?

Zonos offers custom development work at an additional cost. Pricing will vary depending on the amount of work requested.