Custom integration

To get started, please contact our sales team to create an account and sign an agreement. Once an 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.

4. Pass the corresponding IDs through your Checkout customHTML so the relay knows which property/pixel to fire against:

For step-by-step iframe instructions, the full event reference (including the purchase / Purchase payload mapping), and debugging tips, see:

• Google Analytics 4 for iframe Checkout
• Facebook Pixel for iframe Checkout

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? 

Configure the post-purchase experience in Dashboard -> Settings -> Checkout settings under Success page type. Three options are available:

• Show Zonos success page (default, recommended) — Zonos displays a built-in thank you page after the order is placed. The page is always shown, even if the order fails to import into your system, so the shopper always gets a confirmation.
• Redirect to a success page — Zonos waits on a brief "Order complete" screen until the order is created, then redirects to your configured success URL with zOrderNumber (and orderId for legacy carts) appended as query params.
• Close the checkout modal — Zonos closes its modal once payment is captured. If you also configure a success URL, Zonos redirects to that URL immediately after Stripe collects payment — without waiting for the order to be created — and appends zonosCheckoutSessionId as a query param. Use this option when you want the fastest hand-off back to your own success page.

Looking up the order from zonosCheckoutSessionId 

When you use Close the checkout modal with a redirect URL, the order may take a few seconds to attach to the checkout session after the redirect. Read zonosCheckoutSessionId from the URL and poll the checkoutSession GraphQL query from your server using your secret credential token until the order is ready. Never call this from the browser — the secret credential token must stay server-side.

Send the query to https://api.zonos.com/graphql with your secret credential token from Dashboard -> Settings -> Integrations passed as the credentialToken request header.

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.