DOCS

E2e integration

/

Custom integration for platforms

Build an end-to-end Checkout integration into your ecommerce platform.

Advanced


If you are a platform or plugin developer, you may want to build a custom integration of Zonos Checkout into your platform. This will allow you to offer the most seamless experience for your merchants and their customers by leveraging your platform's existing features and functionality with Zonos Checkout.

Advantages of a custom integration include:

  • Seamless experience - Your merchants and their customers will have a seamless experience with installing and configuring Checkout on your platform.
  • More secure - You can securely pass cart items to Checkout without exposing them to the customer's browser.
  • More flexible - You can configure Checkout to work with your platform's existing features and functionality.
  • Bidrectional order sync - You can make international orders processed through Checkout available in your platform's admin panel, in addition to the Zonos Dashboard.

This guide will walk you through the steps to build a complete end-to-end integration of Zonos Checkout into your ecommerce platform, with the same functionality and feature set as our in-house ecommerce plugins. It is intended for plugin and platform developers - if you are a merchant, please see our other integration guides.

Perform a custom integration 

Follow the steps below to build a complete end-to-end integration of Zonos Checkout into your ecommerce platform:

1

Install the Zonos Elements script

Your custom integration will need to include the Zonos Elements script. This script is responsible for rendering the Checkout UI, Zonos Hello, and handling the payment processing. The script needs to be installed on the frontend of your storefronts automatically when a merchant installs your plugin or platform, and it needs to be configured with the merchant's own Zonos API key.

The Zonos Elements script is available at the following URL:

Zonos JS snippet

1
<script src="https://js.zonos.com/dist/scripts/loadZonos.js" />

Additionally, we offer a pre-release URL that is always up-to-date with the latest version of the script. This URL is intended for testing purposes only, and should not be used in production:

Zonos JS snippet (pre-release)

1
<script src="https://alpha.js.zonos.com/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:

Zonos JS snippet

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<script>
  (async function () {
    const timestamp = new Date().getTime();
    const zonosScript = document.querySelector(
      `script[src*="https://js.zonos.com/dist/scripts/loadZonos.js"]`,
    );

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

Initialize with API key

In order to function, Checkout needs to be able to authenticate with Zonos using the merchant's Zonos API key. Each merchant will have their own API key, so you will need to allow them to enter their API key into your platform, typically on a settings page.

Once entered, the API key can be used to authenticate the Elements script via the Zonos.init function. The API keys used to authenticate Checkout are designed to be publishable, meaning they can be safely used in the frontend of your platform without exposing any sensitive information.

Zonos JS snippet

1
2
3
4
zonos.init({
  // ... other fields
  zonosApiKey: 'API KEY', // Replace with your merchant's actual API key
});
3

Set allowed domains

In order to ensure that Checkout is only used on the merchant's domain, you will need to set the allowedDomains property of the CheckoutSettings object. This property accepts an array of domains that are allowed to use Checkout. If the current domain is not in the array, Checkout will not load.

Setting these automatically as part of your integration will create the smoothest experience for your merchants by reducing the number of steps they need to take to get Checkout working on their end.

You can update allowedDomains via the GraphQL API. Ideally you will build this into whatever "activate" or "install" flow you have for your platform/plugin.

4

Configure the 'place order' button

The Elements 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 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 JS snippet

1
2
3
4
5
6
7
zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    placeOrderButtonSelector: '#placeOrder', // Replace with your actual selector(s)
  },
});
5

Display cart details in Checkout

The buildCartDetail callback is responsible for returning cart details in a format that the Checkout interface can understand and display. This function is called as soon as the customer arrives at the checkout page, ensuring that the cart details are displayed accurately on the first page of Checkout. Please note that this is not used for calculations - that is handled in the next step.

Zonos JS snippet

1
2
3
4
5
6
7
8
9
10
zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    buildCartDetail: async () => {
      // ... Your existing buildCartDetail implementation
      // This should return cart details for UI display
    },
  },
});

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

Calculate landed cost

The buildLandedCost handles securely calculating the landed cost. It is invoked after the customer enters their shipping information. This function calculates the shipping rates and other necessary costs, which are then displayed on the subsequent page of Checkout.

It is important that you handle the landed cost calculation logic on the server-side, as this is the only way to ensure that the cart details are not exposed to the customer's browser. If you are using a serverless architecture, you can use a serverless function to handle the landed cost calculation. The buildLandedCost function should simply call the serverless function/API endpoint and return the result.

See our guide on calculating landed cost for more information on how to build this integration.

Zonos JS snippet

1
2
3
4
5
6
7
8
9
10
zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    buildLandedCost: async (checkoutSessionId, contact, shippingAddress) => {
      // ... Your existing buildLandedCost implementation
      // This should return the landed cost calculation
    },
  },
});
7

Import orders back to your platform

A critical piece of an end-to-end integration is the ability to import orders processed through Checkout back into your platform. This allows you to provide a complete order management experience for your merchants, and allows them to manage all of their orders in one place.

You can use the GraphQL API to fetch orders details and then import them into your platform.

Was this page helpful?