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 process 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 add a duty and tax quote, place the following script after the custom Hello script:

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",
    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 (HS code) for your product
brand String unique name, term that defines the product service (e.g. Nike)
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 Zonos Hello flag and information dialog location

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 using 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; }

Turn on/off Zonos Hello splash

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

zonos.config({showSplash:true});

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

zonos.config({showSplash:false});

Hiding Zonos Hello

Hide Zonos Hello for all countries

Find the .z-intl section of the CSS, then add #zonos as a section in the CSS. The line should look something like this:

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

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:

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

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

(premium)

For premium customers who have currency conversion enabled, you can provide Zonos Hello with the css selectors to the price elements on your site. Zonos Hello will take the text of the elements and convert it to the foreign currency. You can pass the css selectors into config with the currencySelectors property.

zonos.config({currencySelectors: '.money, .price, #subtotal'});

You can re-trigger the currency conversion by calling the following JavaScript:

zonos.displayCurrency()

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

If further customization is needed, you can provide a custom converter. The converter should be a javascript function that takes three arguments. The first argument is a function that takes a number and will return a string with the converted price formatted for display. The second argument is a function that takes a number and will return the converted price as a number. The third argument is a function that takes a number in the foreign currency and will return a string formatted for display.

zonos.config({
  currencyConverter: function(convertAndFormat, convert, format) {
    // todo: get all the prices on your page
    // given a single price you could do the following with that value

    // a price from your page
    var price = 12.34;

    // a formatted string (ie "CA$17.60")
    var displayPrice = convertAndFormat(price);

    // a number (ie. 17.6)
    var foreignPrice = convert(price);

    // a formatted string (ie "CA$17.60")
    var displayPriceAgain = format(foreignPrice);

    // todo: update the price element from your page with the displayPrice
  }
});

Events

z-country-change

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"
}

z-duty-tax-quote

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
     }
 }

z-message-change

This event will fire each time the message that Hello displays is changed. The event detail property will be an object that includes the message.

Property Description
message Html string of the currently displayed message
{
    "message": "<div>Welcome ...</div>"
}

Zonos Hello methods

Utility methods you can use to integrate 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 incompatibilities

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