Custom integration

To get started, please contact our sales team to create an account and sign the agreement. Once the agreement is signed, you'll receive two micro deposits in your account that need to be verified.

Please email these micro deposit amounts to accounting@zonos.com with your Dashboard store ID (CC your sales rep).

Once verified, your banking details will display in Dashboard -> Settings -> Billing.

After creating your Zonos account, you'll need to configure settings in Dashboard to ensure Checkout works properly with your store. This section covers all the essential Dashboard configurations.

Set up payouts

Connect a bank account to receive timely payouts from Checkout. Payouts are processed daily within a 2-day delay from the captured payment. To do this, please follow these steps:

1. Navigate to Dashboard -> Settings -> Checkout settings .
2. Click Add bank account
3. You will be taken to a Stripe portal to complete set up and provide the following information:
   • Bank account information.
   • Company EIN.
   • Social Security Number of a 25% company owner. For more details on why this is required see Stripe's documentation.

Note: If you need to update your payout schedule, please contact support@zonos.com

Set up allowed domains

The Zonos JS script requires a list of allowed domains for security purposes. This prevents unauthorized sites from loading the script and ensures it only runs on your approved domains. Without this configuration, the script will return permission errors.

To set this up:

1. Navigate to Dashboard -> Settings -> Checkout settings
2. Under URLs, add your full domain and any subdomains where Checkout will be used. For example, if your domain is example.com, you should add example.com and test.example.com.

Customize branding settings

Configure your branding settings in Dashboard to match your store's look and feel.

To do this, please follow these steps:

1. Navigate to Dashboard -> Settings -> Checkout settings -> Branding
2. Configure the following settings:
   • Logo.
   • Brand and accent color.
   • Theme, Style, and Font.

For more information on branding settings, see our documentation.

Connect a shipping carrier

To quote shipping at checkout, you'll need to connect a shipping carrier to your Zonos account. This will allow you to enable specific shipping service levels at checkout.

To connect a shipping carrier, please follow these steps:

1. Navigate to Dashboard -> Settings -> Shipping -> Rates
2. Click Add carrier
3. Follow the carrier setup instructions.

For more details on connecting carrier accounts, see our documentation.

Set up shipping zones

Shipping zones allow you to configure which shipping carriers and service levels are available for different regions of the world.

To set up shipping zones, please follow these steps:

1. Navigate to Dashboard -> Settings -> Shipping -> Locations
2. Click New zone
3. Enter a zone name and select the countries you want to ship to.
4. Select the carrier and service level you want to offer.

For more details on shipping zones, see our documentation.

Set up a fall back country of origin and HS code

The country of origin and HS code are used to calculate accurate duties and taxes.

If you do not provide a specific country of origin or HS code, we will use the fallbacks set up in Dashboard.

To set your fallback Country of Origin and HS code:

1. Navigate to Dashboard -> Settings -> Shipping -> Catalog.
2. For the country of origin, select the country where the majority of your products are manufactured in.
3. For the HS code, enter the HS code of your most common product. If you don't have a HS code, navigate to Classify in Dashboard and enter the name and description of your product to generate an accurate HS code.

The Zonos JS snippet is a client-side JavaScript integration that enables global checkout functionality on your site. It serves as the bridge between your ecommerce platform and Zonos services, handling:

• Checkout Experience: Renders the checkout UI and processes payments.
• Location Services: Detects visitor location and manages currency conversion.
• Cart Integration: Connects with your existing cart and order system.
• Security: Validates domains and authenticates API requests.

The snippet is loaded asynchronously to prevent any impact on your site's performance. It initializes with your store's API credentials and handles all client-side interactions securely. The implementation is designed to be non-intrusive, requiring minimal changes to your existing checkout flow.

Below is a complete example that includes script loading, initialization, and event handling to reference when integrating Checkout.

<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", () => {
        window.Zonos.init({
          checkoutSettings: {
            createCartId: async () => {
              // Replace with your server-side cart creation logic
              return {
                cartId: "cart_73e707c0-c161-4c37-9581-4da1b1115777",
              };
            },
            placeOrderButtonSelector: "#placeOrder, .place-order", // Replace with your actual selector(s)
          },
          helloSettings: {
            currencyElementSelector: ".price",
            onInitSuccess: () => {
              Zonos.openHelloDialog();
            },
          },
          storeId: 7744, // Replace with your actual store ID
          zonosApiKey: "credential_live_7a128f4e-f192-4232-8992-94dd09eb4437", // Replace with your actual API key
        });
      });

      document.head.appendChild(script);
    }
  })();
</script>

Note: Replace the placeholder values (storeId, zonosApiKey, selectors, etc.) with your actual values from your Zonos Dashboard.

Handling browser caching

We 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. This is shown in line 10 of the complete example.

      script.src = `https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/loadZonos.js?timestamp=${timestamp}`;

Authenticate the Zonos JS snippet

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

To find your store ID and API key, navigate to Dashboard -> Settings -> Integrations. Ensure that you do not use a Secret API key, as it is not designed to be used in frontend code. This is shown in lines 29 and 30 of the complete example.

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

Hello is required when using Checkout.

Hello is responsible for detecting the visitor's location, language, and currency, and displaying the appropriate information to them. You can configure all Hello settings in Dashboard or in the Zonos JS script. If you have already configured Hello in Dashboard, the script will load those settings and use them. If you specify any values in the helloSettings property of the Zonos.init function, the script will use those values instead as shown below.

Configure currency conversion in Hello in JS Script

Hello uses CSS selectors to identify elements on your site that display currency information. Pass these selectors to the helloSettings.currencyElementSelector property of the Zonos.init function so that Hello can detect and display the correct currency of the international shopper.

You can use any valid CSS selector here, for example #price, .price to select multiple different elements. This is shown in lines 23 and 24 of the complete example.

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

Automatically open Hello on page load

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. This is shown in lines 25 and 26 of the complete example.

Zonos.init({
  // ... other fields
  helloSettings: {
    // ... other hello settings
    onInitSuccess: () => {
      Zonos.openHelloDialog();
    },
  },
});

Checkout is responsible for allowing the customer to enter their shipping and billing information, calculate landed cost, collect payment, and complete the order.

Checkout will share contextual data with Hello, such as the visitor's location, language, and currency. This ensures that the customer's experience is consistent across the entire shopping process.

You can configure all Checkout settings in both Dashboard and the Zonos JS script. If you have already configured Checkout in Dashboard, the script will load those settings and use them. If you specify any values in the checkoutSettings property of the Zonos.init function, the script will use those values instead.

Configure the 'place order' button in JS Script

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 for each button. For example, #placeOrder, .place-order.

This is shown in line 21 of the complete example.

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

Securely create cart details on server-side

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 that you use to authenticate the Zonos JS script. This token can be retrieved in Dashboard -> Settings -> Integrations. The secret token needs to be passed as a header in your API call.

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

// Create new cart from serverside
async function createCart() {
  /**
   * Full cart mutation schema: https://zonos.com/developer/mutations/cartCreate
   * */
  const graphql = JSON.stringify({
    query: `
mutation cartCreate($input: CartCreateInput!){
  cartCreate(input: $input) {
    id
    adjustments {
      amount
      currencyCode
      description
      productId
      sku
      type
    }
    items {
      id
      name
      amount
      currencyCode
      quantity
      sku
      description
      metadata {
        key
        value
      }
    }
    metadata {
      key
      value
    }
  }
}`,
    variables: {
      /**
       * input for the cartCreate is this schema https://zonos.com/developer/types/CartCreateInput
       */
      input: {
        /**
         * Cart adjustment input: https://zonos.com/developer/types/CartAdjustmentInput
         */
        adjustments: [
          {
            amount: -10,
            currencyCode: "USD",
            /**
             * Enum value: https://zonos.com/developer/types/CartAdjustmentType
             */
            type: "CART_TOTAL",
          },
        ],
        /**
         * Cart item input: https://zonos.com/developer/types/ItemInput
         */
        items: [
          {
            name: "Item 1",
            amount: 150.99,
            currencyCode: "USD",
            description: "Item 1 description",
            quantity: 2,
          },
        ],
        /**
         * Cart metadata input: https://zonos.com/developer/types/CartMetadataInput
         */
        metadata: [
          {
            key: "key1",
            value: "value1",
          },
        ],
      },
    },
  });

  const response = await fetch("https://api.zonos.com/graphql", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      credentialToken: "credential_live_xxxxxxxxx", // Replace with your actual SECRET credential token (found in Dashboard)
    },
    body: graphql,
  });

  const { data } = await response.json();
  return data.cartCreate.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.

Pass cart ID to Checkout via frontend

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. See the code example below.

The value of the createCartId cannot be a static value, it must be a function.

Zonos.init({
  // ... other fields
  checkoutSettings: {
    // 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
    },
  },
});

To synchronize orders between your system and Zonos Dashboard, implement these API calls and webhooks:

Required Mutations

Required Webhooks

Before going live with your Checkout integration, it's important to thoroughly test all aspects of the integration to ensure a smooth customer experience. This includes testing the checkout flow, payment processing, order creation, and webhook functionality.

Follow our testing guide to verify that your integration is working correctly and to identify and fix any issues before launching to production.

Below are some common questions about the integration process.

How does Zonos handle order confirmation?

Zonos provides a built-in thank you page that you can use for order confirmations. This page will always be shown, even if an order fails to import into your system, ensuring that customers always receive confirmation of their purchase.

Can I be notified when an order is created?

Yes. If you want to receive notifications when an order is created, in Dashboard under the Email section of Checkout settings, you can enter the email address of the team members that should be notified when an order is created, shipped, or cancelled.