Custom integration

The Zonos Elements script is available at the following URL:

<script src="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/loadZonos.js" />

Handling browser caching

We also typically recommend appending a timestamp or other unique identifier to the URL to ensure that the script is not cached by the browser. This will ensure that the latest version of the script is always loaded. For example:

<script>
  (async function () {
    const timestamp = new Date().getTime();
    const zonosScript = document.querySelector(
      `script[src*="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/loadZonos.js"]`,
    );

    if (!zonosScript) {
      const script = document.createElement("script");
      script.src = `https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/loadZonos.js?timestamp=${timestamp}`;
      script.addEventListener(
        "load",
        () => {
          // Initialize the script here (instructions in next section)
        },
        false,
      );
      document.head.appendChild(script);
    }
  })();
</script>

Once you have loaded the Zonos JS script, you need to authenticate it by passing a Zonos API key and store ID into Zonos.init function. The API keys used to authenticate Checkout are designed to be publishable, meaning they can be safely used in frontend code without exposing any sensitive information.

Zonos.init({
  // ... other fields
  zonosApiKey: "API KEY", // Replace with your actual API key (found in Dashboard)
  storeId: "STORE ID", // Replace with your actual store ID (found in Dashboard)
  // ... other fields
});

In order to ensure that the Zonos JS script is only loaded on allowed sites, we filter requests based on a list of "allowed domains". This list is configured in Dashboard. Without this configuration, the Zonos JS script will return permission errors instead of loading properly.

To update your allowed domains:

1. Go to Dashboard -> Settings -> Checkout settings.
2. Under the Allowed domains section, add the domain(s) where you will be integrating Checkout.
3. Click Save.

Hello uses CSS selectors to identify elements on your site that display currency information. You will need to pass these selectors to the helloSettings.currencyElementSelector property of the Zonos.init function.

You can use any valid CSS selector here, for example #price, .price to select multiple different elements.

Zonos.init({
  // ... other fields
  helloSettings: {
    // ... other fields
    currencyElementSelector: "#price, .price", // Replace with your actual selector
  },
});

By default, Hello will only open when the visitor clicks on the flag button. If you would like to automatically open Hello when the page loads, you can call the Zonos.openHelloDialog() function once the Zonos script has loaded.

Zonos.init({
  // ... other fields
});

Zonos.openHelloDialog();

The Zonos JS script will automatically recognize international shoppers and direct them to the Checkout flow. However, you will need to configure the 'place order' button on your platform to open Checkout when clicked. This can be done by passing a CSS selector to the checkoutSettings.placeOrderButtonSelector property of the Zonos.init function.

If you have multiple buttons that can be used to place an order, make sure to pass in a selector that will match all of them. For example, #placeOrder, .place-order will match both #placeOrder and .place-order.

Zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    placeOrderButtonSelector: "#placeOrder", // Replace with your actual selector(s)
  },
});

In order to display the cart details to the customer, you need to create a server-side function that will call the Zonos API to create a cart, and then pass that cart ID back to your frontend. This will ensure that cart details are not exposed to the customer in a way that can be manipulated.

Your backend API call will use a secret GraphQL credential token, which is different than the public token which you use to authenticate the Zonos JS script. This token can be retrieved from Dashboard, and needs to be passed as a header in your API call.

The createCart mutation accepts a list of items, which should be formatted according to the cart item schema.

// Example cart creation with Node.js
async function createCart(someCartDetails) {
  const response = await fetch("https://api.zonos.com/graphql", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      credentialToken: "credential_live_xxxxxxxxxx", // Replace with your actual credential token (found in Dashboard)
    },
    body: `
      mutation {
        createCart(input: {
          cart: {
            items: ${JSON.stringify(someCartDetails)}
          }
        }) {
          id
        }
      }
    `,
  });

  const data = await response.json();
  return data.createCart.id; // Return the cart ID to your frontend
}

We suggest creating an API endpoint on your server-side and then calling that endpoint from your frontend JS integration, which is detailed in the next step.

Once you have created a cart on your server-side, you need to pass the cart ID to the Zonos JS script. This can be done by using the createCartId callback which is part of the Zonos.init function. Checkout will then securely retrieve the cart details from Zonos when opened, preventing any tampering with the cart.

Zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    placeOrderButtonSelector: "#placeOrder", // Replace with your actual selector(s)
    createCartId: async () => {
      const response = await fetch("https://api.merchant.com/api/get-cart", {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
        },
      });
      const json = await response.json();

      return json.id; // Only need to return the cart ID
    },
  },
});