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.

Customize Hello to display in the bottom left

By default, Hello will float in the bottom right corner of your website. If you already have a floating content dialog in the bottom right, you can move Hello to the left with the following JavaScript:

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

If your website already has floating content dialogs in both bottom corners of your site, Zonos recommends hiding one of the floating content dialogs for international customers.

.z-intl .your-dialog { 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’.