DOCS

Javascript

/
Checkout•
HomeGlobal ecommerce Integration Integrate Checkout JavaScript

JavaScript integration

How to do a custom JavaScript Checkout integration.

Beta

If your website uses an ecommerce platform that we don't have a pre-built plugin for, you can integrate Zonos Checkout with JavaScript. This gives you the most flexibility in terms of customizing the look and feel of your checkout page.

This guide assumes that you have already created a Zonos account and that you are familiar with the basics of JavaScript/HTML. If you are not familiar with JavaScript/HTML, we recommend that you use one of our pre-built plugins instead if possible, or contact our Professional Services team for a custom development quote.

Custom JavaScript Checkout integration steps 

Perform the following steps to complete a custom JavaScript Checkout integration:

1

Copy the Zonos JavaScript snippet

You can retrieve your Zonos JavaScript snippet via Dashboard:

  1. Go to Dashboard -> Settings -> Checkout.
  2. At the bottom of the page, locate the Integration script section
  3. Copy your integration script.
2

Add to your site's HTML

Once you have located and copied your JavaScript snippet, insert right before your site's closing <body> tag.

It is important for the Zonos JS script to be loaded in your checkout page's body tag so that when the script runs, your page's content is available and Checkout can properly bind to your checkout button.

We recommend using a server-side template engine or other secure techniques to insert your API key into your HTML with an environment variable. This will avoid exposing your API key in your HTML source code.

3

Configure the Zonos JavaScript snippet

You can configure all Checkout settings in Dashboard and the JavaScript snippet will load them automatically. If you would like to override any settings per-page or do more advanced dynamic configuration, you can do so by passing in an object to the zonos.init() function.

Zonos JS snippet

1
2
3
4
5
6
7
<script src="YOUR SCRIPT URL HERE" />
<script>
  zonos.init({
    // .. other fields
    placeOrderButtonSelector: '#checkout-button', // Replace with your actual checkout button selector
  });
</script>
4

Pass your shopper's cart to Checkout

In order for Checkout to work, you need to pass your shopper's cart to Checkout. This is achieved by passing a buildCartDetail function to the zonos.init() function. This function is called when the shopper clicks your checkout button, allowing you to build the cart details dynamically.

Cart Item Schema

The buildCartDetail function should return an array of cart items. Below is a table detailing the structure of each CartItem object:

Field NameTypeRequiredDescription
amountNumberYesThe price amount of the item.
countryOfOriginStringNoThe country of origin of the item.
currencyCodeStringYesThe currency code for the amount.
descriptionStringNoDescription of the item.
hsCodeStringNoThe Harmonized System code for the item.
imageUrlStringNoURL of the item's image.
measurementsItemMeasurement[]NoArray of item measurements.
metadataObject (string/number pairs)NoAdditional metadata about the item.
nameStringYesName of the item.
productIdStringNoThe product ID.
quantityNumberYesQuantity of the item in the cart.
skuStringNoStock Keeping Unit identifier.

Example usage

Zonos JS snippet

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<script src="YOUR SCRIPT URL HERE" />
<script>
  zonos.init({
    // .. other fields
    buildCartDetail: async () => {
      const cartItems = await getCartItems(); // Replace with your actual cart items
      return cartItems.map(item => ({
        amount: item.salePrice,
        currencyCode: data.currency.code,
        imageUrl: item.imageUrl,
        name: item.name,
        quantity: item.quantity,
      }));
    },
  });
</script>
5

Test your integration

If you've configured everything properly, you should see the Zonos Checkout modal appear when you click your checkout button. If you don't see the modal, check your browser's console for any errors. See our Testing guide for full testing instructions.

Was this page helpful?

Questions?

Contact us.
© 2024 Zonoszonos.com
On this page:
  • JavaScript integration
  • Custom JavaScript Checkout integration steps