Zonos js


Zonos JS integration

Learn how to integrate Checkout using Zonos JS.

Zonos JS allows you to integrate Zonos Checkout without development on your part, even when we do not have a pre-built plugin for your platform. With Zonos JS, our engineers create a script that will redirect your international customers to Checkout. This script is customized to your website and will pull the item details from your cart page through to Checkout. Completed orders will appear in Dashboard, where you can easily generate international shipping labels.

Note: By default, orders placed in Checkout will only appear in Dashboard. They will not appear in your ecommerce platform. If you need your international orders to import into your ecommerce platform, build our Retrieve an Order API.


Seamlessly integrate Checkout using Zonos JS by following the steps in this section.


Get started

Start by completing our sign-up form. Onboarding will commence once your account agreement is in place.



Within 24 hours of signing up, a dedicated onboarding representative will contact you to kick off a tailored integration process.

Important: The steps listed below are for your reference and you will be guided through them by your onboarding representative.

While you are configuring your account, Zonos engineers will write a custom script for your store.


Add script to your website

Once the script is ready, your onboarding Project Manager will provide it to you. Use the instructions below to add it to your website:

Custom platform

Add the following Zonos JS script tag to your <head> tag:

Script tag

<script src="{supplied scriptURL}"></script>

When you add your custom Zonos JS script to your site, it will initially be in test mode. During test mode, Hello will be active on your site, but your international customers will still go through your current native checkout flow (they will not get to Zonos Checkout).


Test the script on your site

To test the functionality of Checkout, you will need to tell the browser to load the page as if Zonos is live on your site. You can do this by manually adding ?zonos=true to the end of your URL (on each page you visit), or by adding the key zjs_debug with a value of false to your local storage for your website.

Here are the items you should test while the script is in test mode:

Your domestic checkout process is unaffected.

Elements that are not applicable to your international shoppers are hidden on the cart and product pages.

The following information is collected from the cart page and presented in Checkout: product price, discounted prices, add-ons, images, quantity, and promo codes.

Currency conversion is working properly (if enabled).

The item weight, HS code, country of origin, and dimensions are used as provided.

Ensure the shipping rates that return in Checkout align with the rates provided by your shipping carrier.

Place a test order in Checkout using your own email address. Confirm that you receive an email confirmation of the order.

Print a label in Dashboard -> Orders.


Go live!

Once you have verified that the script is working correctly, and are ready to go live, contact your onboarding Project Manager to have them activate your Zonos JS Script to make Checkout live on your site.

Important: Since Zonos JS is customized to your site's layout and code, if you change your site layout or code your custom script may stop working or have issues. You will likely need to have your script updated to work with the new version of your site.

Frequently asked questions 

Product-specific information is not required for Zonos to return a quote. However, the more product-specific information provided, the more accurate our calculations will be. The most helpful product details for improved accuracy are listed below.

All of the following product details can be received with Zonos JS if they are available to scrape from your cart page or you can add the information to Zonos Catalog.

  • Weights
  • Dimensions
  • HS codes
  • Country of origin

Learn more.

Was this page helpful?