Integrate
Follow these steps to integrate Checkout with your BigCommerce store.
Get started
Please reach out to us for information on how to get started. Once we get an agreement, you can begin the installation process.
Create an account
- Register for a Zonos account.
- After registering, complete your Account setup.
Install apps
Both Checkout and Hello must be installed for Checkout to work properly, as Hello will inform when to redirect international customers to our Checkout.
- Install the Checkout app from BigCommerce Marketplace by clicking Get this app.
- Install the Hello app from BigCommerce Marketplace by clicking Get this app.
Configure Checkout
Once you have installed both apps, configure your settings:
- Within your BigCommerce backend, go to Apps → My apps → Zonos Checkout.
- Enter your integration credentials to link your Dashboard settings to your BigCommerce site.
- Enable the app in test mode or live:
- Under Zonos Checkout, select Enable.
- Under Test mode, select Enable. When this mode is enabled, you must append
?zonos=true
to the URL to enable Zonos functionality, allowing you to test Zonos while your shoppers still experience your native flow. Change this to Disable when you are ready to go live.
- Customize our app to work according to how your site needs:
- Under Create customer on order import, select your preference.
- Under Reserve product stock during checkout, select Enable if you would like Zonos to reserve product stock while it is in our Checkout. Learn how this works in the FAQs at the bottom of this page.
- Under Show payment provider as custom, select Enabled if you would like all of your Zonos orders to show Custom as the payment provider in BigCommerce.
- Click Update settings to save your selections.
Configure Hello
- Within your BigCommerce backend, go to Apps → My apps → Zonos Hello.
- Copy your Hello API key from Dashboard and input it as your Site Key.
- Enable the Hello app by switching Zonos Hello to enable. Hello can be enabled before Checkout and will not redirect to Zonos Checkout unless Checkout is also enabled.
- Switch Duty and tax quote to enable.
- If you would like Zonos to leverage BigCommerce currency conversion, switch Currency conversion to enable. Doing so will allow Hello to enable currencies for you in Settings → Currencies. Check your currency settings there to ensure that payments will be made in the currency you prefer.
- Click Update settings to save your selections.
Add missing product info
Versions of BigCommerce before V3 have limitations with the data they pass to Zonos for landed cost quotes. Learn what product information Zonos receives from each version of BigCommerce and when you must use Zonos Catalog to add product-specific information needed for our calculations.
Optional product info
Product-specific information is not required for Zonos to return a quote. Zonos can use your account defaults for HS codes and Country of origin, estimate weight with a custom factor, and quote without dimensions. However, the more product-specific information provided, the more accurate our calculations will be.
Product info sent from BigCommerce
- Weights
- Dimensions
- HS codes*
- Country of origin*
*Only imports if using the BigCommerce V3 product experience
If you are not using BigCommerce V3, add your products with their HS codes and Country of origin to Catalog. Learn how to use Catalog.
If you add weight, dimensions, HS code(s), or country of origin to Catalog, Catalog will always use those fields. If any information is present in both your ecommerce platform and Catalog, the information in Catalog will override the information sent from the ecommerce platform when running our calculations. For example, suppose a product's weight is present in Shopify and Catalog. In that case, Zonos will use the weight in Catalog to calculate shipping.
Test your integration
Now that you have set up your account and your app, you are ready to test your integration. You will need to enable Checkout and Hello in Magento while testing. To do so:
- Within your BigCommerce backend, go to Apps → My apps → Zonos Hello.
- Switch Zonos Hello to enable.
- Then go to Apps → My apps → Zonos Checkout.
- Under Zonos Checkout, select Enable.
- Under Test mode, select Enable.
When this mode is enabled, you must append ?zonos=true
to the URL to enable Zonos functionality, allowing you to test Zonos while your shoppers still experience your native flow.
After completing testing, enable Zonos by setting Test mode to Disable.
Some things to remember:
- De minimis—If the cart subtotal of your order is under the ship to country's De minimis, there may not be any duty or taxes due. This is reflected in our calculations.
- Refunds and cancellations—We are collecting the payment, so if you need to do any refunds or cancellations, please process these in Dashboard.
- Labels—Print labels for all international orders in Dashboard, unless you have been certified to print labels outside of Dashboard. This allows us to pay the duties and taxes on your behalf.
Note: If you need us to make adjustments, please reach out to Zonos support for assistance.
Advanced setup options
Stencil setup
To determine if you are using the Stencil theme, in the BigCommerce Admin Panel, if Storefront -> Footer Scripts is an option, your store is using a Stencil theme.
Hide domestic elements
If you have elements you need to hide for international users only, e.g. USA-only payment providers, shipping estimators, banners with USA-only messaging, etc., then use the next steps to hide them when the Zonos Hello country is international. To fix this, go to BigCommerce Admin Panel -> Storefront -> Script Manager -> Create Script.
To hide the domestic elements, follow the steps below:
-
Go to BigCommerce Admin Panel -> Storefront -> Script Manager -> Create Script.
-
Create a new custom script for Zonos by using the following:
- Name: Zonos Custom - [script relevant name]
- Description: [What this script does]
- Location in page: Footer
- Select pages where script will be added: All pages
- Script contents: Copy the following and paste it into the script contents.
-
In the script below, edit the selectors in
var domesticElements =
by doing the following:- Find the element selectors you want to hide for international users on your current BigCommerce site.
- Once you have those selectors, add them in where it says
.hide-me
. - Make sure to surround each selector by speech marks and broken by a commar see the following example:
[".hide-1", ".hide-2", ".hide-3", ".hide-4"]
- Once the script is ready and saved, test by going to the page where the elements were hidden on and toggle the Zonos Hello country from USA to international, and back to USA. Those elements should be hidden when an international country is selected.
Zonos integration script
<script>
var domesticElements = ['.hide-me'];
let cssElement = document.createElement('style'),
sheet;
document.head.appendChild(cssElement);
sheet = cssElement.sheet;
let count = 0;
for (let domesticHide of domesticElements) {
sheet.insertRule(`.z-intl ${domesticHide} { display:none; }`, count);
count++;
}
</script>
Blueprint setup
In BigCommerce, if Storefront -> Mobile Theme is an option, your store is using a Blueprint theme.
If you are set up on the Blueprint version of BigCommerce, you will need to add any additional scripts or code snippets to the bottom of: Advanced Settings > Web Analytics > Google Analytics > Tracking Code.
You can use the scripts included in the Stencil instructions as shown above, but make sure to copy and paste them to the Tracking Code section.
Troubleshooting
Checkout buttons not redirecting
If the Zonos Checkout is in test mode or set to live (and the checkout buttons are not redirecting to Zonos), it may be the checkout button selectors. Our Zonos Checkout app uses a set list of default checkout button selectors. If an international user is not being redirected, those selectors may need to be adjusted.
To fix this issue, follow the steps below:
-
Go to BigCommerce Admin Panel -> Storefront -> Script Manager -> Create Script.
-
Create a new custom script for Zonos by using the following:
- Name: Zonos Custom - [script relevant name]
- Description: [What this script does]
- Location in page: Footer
- Select pages where script will be added: All pages
- Script contents: Copy the following and paste into the script contents.
-
Once you have the code below in the script contents, you will need to either adjust one of the selectors to match your current checkout buttons or you can add a new selector to the list.
-
Make sure to save this new script and test the site.
Zonos integration script
<script>
window.onload = () => {
selectors = {
'.previewCartCheckout .button--primary': 'checkout',
'.cart-actions .button--primary': 'Check out',
'.previewCartAction-checkout': 'Check out now',
'.ProceedToCheckout .btn': 'Proceed To Checkout',
'.CheckoutLink': 'Checkout',
'.button--primary': 'Checkout',
'.button-checkout': 'Checkout',
'.btn': 'Proceed To Checkout',
'.CheckoutButton': 'Proceed To Checkout',
};
for (let key in selectors) {
let button = contains(key, selectors[key]);
for (i = 0; i < button.length; i++) {
button[i].addEventListener('click', function (e) {
zonosCheckout(e);
});
}
}
};
</script>
Checkout for BigCommerce
How to integrate the Checkout plugin for BigCommerce.Before integrating Checkout, ensure it will work as you expect. When you use Checkout: