Integration checklist
Follow this comprehensive checklist to to set up your Zonos Dashboard account and integrate Zonos Checkout into your custom site or platform.
Create a Zonos account
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.
Configure Dashboard and Checkout settings
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:
- Navigate to Dashboard -> Settings -> Checkout settings .
- Click Add bank account
- 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:
- Navigate to Dashboard -> Settings -> Checkout settings
- Under URLs, add your full domain and any subdomains where Checkout will be used. For example, if your domain is
example.com
, you should addexample.com
andtest.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:
- Navigate to Dashboard -> Settings -> Checkout settings -> Branding
- 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:
- Navigate to Dashboard -> Settings -> Shipping -> Rates
- Click Add carrier
- 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:
- Navigate to Dashboard -> Settings -> Shipping -> Locations
- Click New zone
- Enter a zone name and select the countries you want to ship to.
- 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:
- Navigate to Dashboard -> Settings -> Shipping -> Catalog.
- For the country of origin, select the country where the majority of your products are manufactured in.
- 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.
Install the Zonos JS snippet
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.
Complete Zonos JS Integration 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", () => {
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.
Timestamp
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 Store ID and API Key
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
});
Set up Hello
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.
Hello Settings
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 JS Snippet
Zonos.init({
// ... other fields
helloSettings: {
// ... other hello settings
onInitSuccess: () => {
Zonos.openHelloDialog();
},
},
});
Set up Checkout
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.
Place order button selector
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.
Example server-side cart creation
// 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.
Pass cart ID to Checkout
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
},
},
});
Sync order tracking and status into Dashboard
To synchronize orders between your system and Zonos Dashboard, implement these API calls and webhooks:
Required Mutations
Mutation | Description |
---|---|
orderUpdateAccountOrderNumber | Syncs your native account number with Dashboard. Docs → |
orderAddTrackingNumber | Required only if you're not printing labels in Dashboard. Ensures tracking shows in Dashboard so Zonos can guarantee your landed cost calculations. Docs → |
Required Webhooks
Test your integration
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.
Common questions
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.
Custom integration
Build an end-to-end Checkout integration into your custom site.