Zonos Hello

Install Zonos Hello on your site

Include your custom Hello script with your unique site key. You can obtain the site key by completing the signup on hello.zonos.com.

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

The script should be placed before any calls to zonos.

Generate an estimated duty and tax quote

The duty and tax quote goes on each product detail page. As the customer views your product, they will know what duties and taxes to expect.

To create a duty and tax quote, you can send a list of items to Zonos with the following JavaScript:

    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",
    includedTaxRate: 0.05

Quote fields

Field Data Type Description
items Array (required) A list of items to include in the quote
currencyCode String The item prices will display in the currency specified by the three character currency code. Default: USD
includedTaxRate Number The item tax rate if the item includes tax

Item fields

Field Data Type Description
name String (required) The product name
price Number (required) Unit price of a single product
quantity Integer The number of products in the cart. Default: 1
image String Url of the product image
url String Url to the individual product
hsCode String The Harmonized Code for your product
brand String  
category String The product’s category on your site
country String Two character ISO code of the country this product originated from
customization String Product customizations (e.g. size, color)
description String The detailed description of the product
sku String The 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 Location of the Flag and Information Dialog

By default, Hello will float in the bottom right corner of your website. If you already have floating content in the bottom right, you can move Hello to the following positions with the Javascript below:

Default location is right bottom attached. If location is left blank, the code will use the default.

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'});

If you add floating to the location, this refers to the Hello information dialog to float in the center of the page. attached refers to the Hello information dialog to open over the flag. floating is preferred when making the flag positioned at the top.

If your website already has floating content in both bottom corners of your site, and you do not want the flag at the top, Zonos recommends hiding one of the floating content for international customers.

Use the following CSS to hide your content. Replace .your-content with the floating content you want to hide.

.z-intl .your-content { display: none; }

Then, you can hide Hello from your domestic customers, so the other dialogs are visible again.

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

Adjust the content displayed on your site for international customers

Zonos Hello will add a CSS class z-intl to the body tag in your html. By adding CSS style rules, you can hide content that does not apply to your international customers. For example:

.z-intl .free-shipping {
    display: none;

Currency conversion


For premium customers who have the currency conversion enabled, you can re-trigger the conversion by calling the following JavaScript:


Calling displayCurrency may be needed if your site is loading product information dynamically after the page has loaded.



This event will fire each time the country is changed, including the initial country selection. The event detail property will be an object that includes code and name.

Property Description
code Two character ISO code of the country the product originated from
name Country name
    "code": "US",
    "name": "United States"


This event will fire once a duty and tax quote response is recieved. The event detail property will be an object with the following properties:

Property Description
subtotal The item subtotal that the quote was based on
taxOrVat The estimated sales tax or vat amount quoted based on the subtotal
dutyTotal The estimated duty amount quoted based on the subtotal
dutyTaxTotal The combined values of taxOrVat and dutyTotal
foreign (premium) An object containing the same values as above, which is then converted into the foreign currency amount
     "subtotal" : 89.99,
     "taxOrVat": 18.00,
     "dutyTotal": 32.54,
     "dutyTaxTotal": 50.54,
     "foreign": { // only premium accounts will have the foreign values
        "currencyCode": "GBP",
        "subtotal" : 89.99,
        "taxOrVat": 18.00,
        "dutyTotal": 32.54,
        "dutyTaxTotal": 50.54

Zonos Hello methods

Utility methods you can use to integerate with your site.

Method Returns Description
zonos.isDomestic() Boolean True if the current country is domestic
zonos.country() String Get the currently selected country code
zonos.country(code) String Set the country manually and return it. code should be a two character ISO code

# Known incompatibilties

Zonos Hello is not compatible with themes that make use of Selectric (https://github.com/lcdsantos/jQuery-Selectric), unless it is configured to ignore Select elements that are identified by ‘select#countrySelect’.