Customize behaviour

Ecwid storefront is an embeddable widget and you can control many aspects of embedding process: add custom JS file, delay widget initialization, change page contents and more.

Table of contents

Add Ecwid to the site

Add Ecwid storefront to your website

<div id="my-store-1003"></div><div> <script type="text/javascript" src="" charset="utf-8"></script><script type="text/javascript"> xProductBrowser("id=my-store-1003");</script></div>

This is the most important Ecwid widget. It shows and includes a full-featured shopping cart with products, categories, catalog, checkout pages, etc.

To add an Ecwid store to the website, use the code example on the right. The 1003 is the ID of an Ecwid store. Make sure to specify your desired store ID in order to show your store!

Set main storefront URL for widgets

You can add different store widgets, like search, minicart to a page separately from the storefront widget.

When you interact with them, the storefront area will open in a pop-up. This pop-up contains the whole store and works as usual.

But in some cases it is more convenient to open the storefront on another website page instead of the pop-up.

You can do this with the help of the option.

'Tell’ Ecwid widgets that storefront is located at “”

<script> = || Object(); = || Object(); = "";

How Ecwid works by default

  • if a visitor uses the “minicart/vertical categories/search box” widget and a storefront is added on this page, all actions (go to cart, to category, etc.) will be made in that storefront widget
  • but if a storefront widget doesn’t exist on the same page page, a pop-up window with the storefront will be created on this page to complete the action

How Ecwid works with this option

When a merchant uses a storefront widget placed on another page of a website, you should use the option. If it’s set up, Ecwid works in such way:

  • if a visitor uses the “minicart/vertical categories/search box” widget and the storefront widget isn’t added on this page, they will be redirected to the URL speicified in the code and then the necessary actions will be performed there

For example, if a customer searches for a product on the page without a storefront, they will be redirected to a URL specified in variable and then Ecwid will show the search results on that page.

How to set up this option

In order to use it, you need to add the JavaScript code on the right to all pages, where Ecwid widgets are installed.

Disable force scrolling to storefront

Disable force scrolling to storefront = || Object(); = || Object(); = "DISABLED";

Use custom scrolling to any position on the page = || Object(); = || Object(); = "CUSTOM"; = function() {
  window.scrollTo(500, 0);

When Ecwid storefront widget is added to a website, the page will be scrolled to the beginning of storefront by default.

If you want to disable this behaviour, use the config variable. Possible values:

  • "CUSTOM"

Default value: "IMMEDIATELY"

If you need to scroll to a custom position when navigating the Ecwid store, use the "CUSTOM" value and set your custom scrolling function in the configuration.

Adapt storefront layout to container width

Adapt storefront layout to changed container width


By default, Ecwid is a responsive widget which adapts to the changing screen width. That’s usually when the container for storefront changes its width also.

However, if the screen width stays the same but the container for storefront changes its width, you will need to call the Ecwid.resizeProductBrowser() function to adapt Ecwid’s layout to this change.

Open specific product variation

When opening a product that has options or variations, it can be useful to open them with preset values right away. This will save customer’s time and improve the buying process.

How to open a product variation

1) Determine the product you want to open: get a direct URL to product details page you would need to use.

For example:

2) Use Ecwid.openPage() method to open that product page with specific variation ID. See example on the right.

Open variation with ID 16351010 of a product with ID 72585497

Ecwid.OnAPILoaded.add(function() {
  Ecwid.openPage('product', {'id': 72585497, 'name': "Rip Curl Channel Island", 'variation': 16351010});

Alternative way

Add a query parameter variation to the URL with a value of desired variation ID. You can retrieve the variation ID via the Ecwid REST API

Resulting URL:

It will open a product “Rip Curl Channel Island” with options: Size - Any, Color - Dark grey.

How to open a custom product variation

If your product doesn’t have product variations but has product options, you can still open details page with preset values (selections). Use options query parameter instead.

1) Determine the product you want to open: get a direct URL to product details page you would need to use.

For example:

2) Use Ecwid.openPage() method to open that product page with specific options selected. See example on the right.

Open a product “Rip Curl Channel Island” with options: Size - Medium, Color - Dark grey

Ecwid.OnAPILoaded.add(function() {
  Ecwid.openPage('product', {'id': 72585497, 'name': "Rip Curl Channel Island", 'options': [2,2]});

Alternative way

Add a query parameter options to the URL with values of product options separated by comma: ?options=A,B,C

Each value will be assigned to product options depending on its index in the list of available selections. The index starts at 1. This method supports drop down and radio button product options only

Any incorrect and out of range values will be ignored.

Example: ?options=4,5,6

These values mean that:

  • for product option 1 the value will be: 4th selection
  • for product option 2 the value will be: 5th selection
  • for product option 3 the value will be: 6th selection

And so on.

Resulting URL:,2

It will open a product “Rip Curl Channel Island” with options: Size - Medium, Color - Dark grey.

Offset default storefront scroll position

Move storefront widget scroll position up by 150px

<script> = || {}; = || {}; = 150; 

Some websites have sticky headers which stay in the same place as user scrolls the page down.

When navigating to a new page in Ecwid storefronts, it will scroll to the top of the store page area automatically.

By default, Ecwid can detect the sticky headers and offset the scroll position so that both website header is visible as well as the top area of a store page.

However, you can override this value with a custom one. See the example on the right.

Important: if store page title is clearly visible or there is little space between the page top and store area – the scroll indent will be disabled.

Embed or remove storefront on demand

Dynamic embedding of Ecwid storefront widget

<div id="my-store-1003"></div>
window.ecwid_script_defer = true;
window.ecwid_dynamic_widgets = true;

   if (typeof Ecwid != 'undefined') Ecwid.destroy(); 
   window._xnext_initialization_scripts = [{
        widgetType: 'ProductBrowser',
        id: 'my-store-1003',
        arg: ["id=productBrowser"]

  if (!document.getElementById('ecwid-script')) {
      var script = document.createElement('script');
      script.charset = 'utf-8';
      script.type = 'text/javascript';
      script.src = ''; = 'ecwid-script'
    } else {

In some cases it is necessary to dynamically create and destroy Ecwid widget within the HTML page. This is useful for dynamic sitebuilders that switch to online store page without actually reloading page (e.g. making it visible).

You should use window.ecwid_dynamic_widgets variable to enable dynamic widget creating in Ecwid. See the example on the right that shows how to create and destroy Ecwid widget through the JavaScript functions.

Please note that this method allows to embed the storefront widget only. If you need to embed other widgets dynamically, please, use the code for deferred widget initialization

Delayed widget initialization

Delayed widget initialization

<div id="my-store-1003"></div>
<div id="my-categories-1003"></div>
<div id="my-search-1003"></div>
<div class="ec-cart-widget"></div>

  window.ecwid_script_defer = true;

  var script = document.createElement('script');
  script.charset = 'utf-8';
  script.type = 'text/javascript';
  script.src = '';


  window._xnext_initialization_scripts = [
      // Storefront widget
        widgetType: 'ProductBrowser', id: 'my-store-1003', arg: [
      // Horizontal categories widget
        widgetType: 'CategoriesV2', id: 'id=my-categories-1003', arg: [
      // Search widget
        widgetType: 'SearchWidget', id: 'my-search-1003', arg: [
      // 'Buy now' button for product
        widgetType: 'Product', id: 'Product-1'

// Initialize Minicart Widget. A div with class '.ec-cart-widget' must be present on a page  



Sometimes it is necessary to delay widget initialization while the website page finishes the initialization procedures. This is useful when the website is built dynamically using libraries such as ReactJs.

See the example of delayed initialization of different Ecwid widgets on the right.

Increase widget loading speed

DNS Prefetching of Ecwid’s resources

<link rel="dns-prefetch" href="//">
<link rel="dns-prefetch" href="//">
<link rel="dns-prefetch" href="//">

To increase the loading speed of an Ecwid store, you can start loading Ecwid resources even before a customer opens the store page by the means of so-called prefetching (prerendering) browser feature. Not all browsers support this at this moment though.

Prefetching and prerendering of storefront page

<link rel="prefetch" href=""/>
<link rel="prerender" href=""/>

You can also add your storefront page to preload and prerender in the background for further increase in loading speed for browsers that have this feature.

Feel free to learn more about these techniques in

Add custom JavaScript code

Example of custom JavaScript to modify storefront

 * Show a promo 'Free shipping' message on the cart page. 
 * In the example below, users will see a message on the cart page 
 * informing them that they will qualify for free shipping if their 
 * order is more than $99

var promoMessage = "Orders $99 and up ship free!";
var minSubtotal = 99;
var widgets;

// Calculating subtotal and displaying the message
var checkSubtotal = function(order) {
  if (order) {
    var subtotal = - order.shipping;
    if (subtotal > minSubtotal) {

// Detecting whether we're on the cart page and get the cart info
Ecwid.OnPageLoaded.add(function(page) {
  widgets = Ecwid.getInitializedWidgets();

  // if storefront widget is present on this page
  for (i = 0; i < widgets.length ; i++) {
    if (widgets[i] == "ProductBrowser") {
      if ('CART' == page.type) {
        Ecwid.Cart.calculateTotal(function(order) {

// Get color value for the message and store it in color variable
var color = Ecwid.getAppPublicConfig(appId);

// your code here
// ...

You can access the Ecwid storefront DOM and do pretty much everything you want by means of native JavaScript or whatever framework you want.

If you use a JS framework, please make sure it’s already loaded on the page by the moment you start using it.

In addition, Ecwid provides a JavaScript API that you can use to retrieve store information and track Ecwid events on the page.

Table of contents

How to load custom JavaScript anytime storefront is loaded

Ecwid can load and execute a JS file from your server when store loads on page automatically.


  • A registered app with customize_storefront access scope
  • Ready or dummy JS file uploaded to your server
  • Ecwid store on a paid plan

Required actions:

  1. After your app is registered, contact us and provide HTTPS URL of .js and/or .css file you’d like to load in the user storefront.
  2. Install your app into the target Ecwid store using instructions provided in registration email.
  3. The next time storefront is loaded in any browser or website, your JS/CSS files will be automatically appended, loaded, and executed on that page.

Q: How to know what Ecwid widgets are on a page?

If your applcation customizes storefront, your script will be loaded at all times when{store_id} is on a page. It means that if a simple search widget is present on a page, your script will be executed.

Ecwid widgets can be also embedded in many ways:

  • as a part of a website page
  • in an iframe
  • certain widgets are displayed only (like search and minicart, no storefront)

So, it is important to know where exactly your application is loaded: if there is a storefront present on a page or if it’s just a search widget. To check that, use Ecwid.getInitializedWidgets() function of Ecwid Javascript API. Using it, you can determine whether your app functionality needs to be initialized or not.

Q: What is the best way to add new scripts from my code?

Add external script to the page example

var s = document.createElement("script");
s.type = "text/javascript";
s.src = "";

In case if you need more than one JavaScript code executed on a page, you can load additional scripts from within your base app JavaScript code.

We recommend that you load external JS files using a standard function createElement(). See example code on the right. It allows you to create a new <script> element on a page with the parameters you need and then append it to the DOM tree to get loaded and executed.

More details about this approach: W3CSchools

Access merchant in-app preferences

Applications can work and look differently in various stores, so you can provide tailored user experience to the store owner and a website they have in your application.

App public config allows apps to access user specific data in storefront as soon as it starts to load, so no calls to external servers are required and result is available right away. It’s recommended that you use app storage to access public user data in storefront area of your application.

How it works:

  1. App saves public data in public storage in backend
  2. App gets public data from public storage in storefront
  3. App tailors user experience to merchant settings

For example, using this method you can pass store ID to a storefront, category or product ID where the changes need to apply or whether your widget needs to be shown in storefront.

To find out more about this process, please check Public App Config section.

Store-specific custom JavaScript

Example of the script that dynamically loads store-specific code

// Load external script with store
function loadConfig(ecwidStoreId, callback) {
  var script = document.createElement("script");
  script.setAttribute("src", '//' + ecwidStoreId + '.js');
  script.charset = "utf-8";
  script.setAttribute("type", "text/javascript");
  script.onreadystatechange = script.onload = callback;

// Application functionality
function doCoolStuff() {

// Get color value for the message and store it in color variable
var color = Ecwid.getAppPublicConfig(appId);

// Get Ecwid store ID and start working
loadConfig(Ecwid.getOwnerId(), doCoolStuff);

In most cases, your application behavior will vary depending on the store it is opened in. Although Ecwid API allows you to specify only one JS file per application, your application can detect the current Ecwid store ID and act correspondingly. Use the Ecwid.getOwnerId() method to detect the user store ID in your script.

For example, let’s say you need to dynamically add a store-specific configuration to your script when it’s executed in some particular storefront. You can detect the store ID in your script and call a script on your server containing the store-specific code.

To get information for that specific store you can use Ecwid.getAppPublicConfig function in Ecwid Javascript API. See more details on how to access that data in Application data section of documentation.

Caching JavaScript file contents

When your external JS file is loaded on a page, it is loaded like any other resource via a GET request by a web browser. If you’d like to use caching to increase the loading speeds of your script, we can suggest several options:

  • invalidate cache for your JS file link when deploying a new version
  • in your JS file, place a code that will get the latest JS assets file from your server dynamically and append it to a page (instead of the using an actual code of your app on that URL)
  • don’t use caching, so that your files for storefront are always up-to-date for any user

Using jQuery on store pages

Checking for jQuery on a page example

// function to load jQuery

function loadjQuery(){
  var jq = document.createElement('script'); jq.type = 'text/javascript';
  jq.src = '';

if (typeof jQuery == 'undefined') {  
} else {}

// your app code
// ...

jQuery is a very popular JavaScript library that is used in many websites. The developers of themes for Wordpress CMS, for example, include this library right into the theme to have access to its functions and to operate various HTML elements on the page easily.

Ecwid storefronts can be customized in many ways, for example: you can set specific behaviour for each page or each user that visits those pages. Some developers prefer using native JavaScript functions to change the position or the display of certain elements. But many use different versions of popular jQuery library.

To ensure that your jQuery version code doesn’t conflict with other applications that change Ecwid storefront, please see our guidelines:

For simple modifications

When your modifications don’t require specific versions of jQuery loaded on a page and are fairly simple, we suggest you follow this algorithm:

First, check for jQuery object on current page. If no object is defined, load any jQuery version you prefer using the example code on the right. If there is already jQuery object available - skip the loading and use the curreny jQuery on this page.

For complex modifications

When you are using advanced jQuery’s features such as jQuery UI, version specific functions, etc. it will be hard to work with, if a website already has varuous jQuery versions on a page. To avoid any version conflicts with current page jQuery version, we suggest you use jQuery noconflict feature. Check out how it works:

Custom URL redirect after an online purchase

Setting custom URL redirect after online purchase

<script> = || Object(); = || Object(); = 'YOUR CUSTOM URL HERE';
<script> = || Object(); = || Object(); = '';

Some merchants may want to send their customers after a successful online purchase to a custom URL. Using the configuration on the right you can set the URL where the customer should be redirected.

Important: the redirect will work only for online payment methods. For offline payment methods, consider using the Custom URL for 'Thank you’ page application.

Generate cart with products

Ecwid JavaScript API allows you to add items to customer’s cart automatically. This can be useful when you are using custom storefront to provide any type of button to add products to cart.

Using the following steps you will be able to create links to your storefront with products in cart for your customers. So all they have to do is just clikc that promo link to go to your store and have products added to cart automatically.

Let’s check out how this can be achieved:

Step 1: Add external files to your website

Script and CSS to load on your storefront page

<link rel="stylesheet" type="text/css" href="">
<script src=""></script>

Add the JS and CSS files below to the source code of the page, where your Ecwid storefront is displayed. Make sure to add the script below the Ecwid integration code.


Step 2: Generate your cart

Generate example

var cartItems = [{
    "id": 66821181, // ID of the product in Ecwid
    "quantity": 3, // Quantity of products to add
    "options": { // Specify product options
        "Color": "White",
}, {
    "id": 66722581,
    "quantity": 5

var cart = {
     "gotoCheckout": true, // go to next checkout step right away (after 'Cart' page)
     "products": cartItems, // products to add to cart
     "profile": {
         "address": { // Shipping address details
             "name": "john smith",
             "companyName": "general motors",
             "street": "5th Ave",
             "city": "New York",
             "countryCode": "US",
             "postalCode": "10002",
             "stateOrProvinceCode": "NY",
             "phone": "+1 234 235 22 12"
         "billingAddress": { // Billing address details
             "countryCode": "US",
             "stateOrProvinceCode": "AL",
         "email": "", // Customer email
         "orderComments": "Comments!" // Order comments

cart = JSON.stringify(cart);
cart = encodeURIComponent(cart);


// prints the resulting string you need to use in step 3
// %7B%22gotoCheckout%22%3Atrue%2C%22products%22%3A%5B%7B%22id%22%3A66821181%2C%22quantity%22%3A3%2C%22options%22%3A%7B%22Color%22%3A%22White%22%2C%22Size%22%3A%2211oz%22%7D%7D%2C%7B%22id%22%3A66722581%2C%22quantity%22%3A5%7D%5D%2C%22profile%22%3A%7B%22address%22%3A%7B%22name%22%3A%22john%20smith%22%2C%22companyName%22%3A%22general%20motors%22%2C%22street%22%3A%225th%20Ave%22%2C%22city%22%3A%22New%20York%22%2C%22countryCode%22%3A%22US%!%22%7D%7D

In order for the script to add items to cart, we need to 'tell’ it what items to add. Check the example on the right on how to do this. The cart variable will have the generated cart content in it.

The syntax is very similar to adding products to cart via Ecwid JavaScript API.

Step 3: Create a link for customers

Final link structure!/~/cart/create={generatedCartCode}

Final link to generated cart example!/~/cart/create=%7B%22gotoCheckout%22%3Atrue%2C%22products%22%3A%5B%7B%22id%22%3A66821181%2C%22quantity%22%3A3%2C%22options%22%3A%7B%22Color%22%3A%22White%22%2C%22Size%22%3A%2211oz%22%7D%7D%2C%7B%22id%22%3A66722581%2C%22quantity%22%3A5%7D%5D%2C%22profile%22%3A%7B%22address%22%3A%7B%22name%22%3A%22john%20smith%22%2C%22companyName%22%3A%22general%20motors%22%2C%22street%22%3A%225th%20Ave%22%2C%22city%22%3A%22New%20York%22%2C%22countryCode%22%3A%22US%!%22%7D%7D

Now we need to fill in customer’s cart when your custom link is opened.

First things first, let’s determine where your Ecwid store is displayed and get a direct link to that page.

For example, our demo store is located in: And to fill in customer’s cart with items that you seleted earlier, we need to create a link to your storefront with the generated cart part.

Example link

Generated link with products added automatically to cart for Ecwid demo store will be:!/~/cart/create=%7B%22gotoCheckout%22%3Atrue%2C%22products%22%3A%5B%7B%22id%22%3A66821181%2C%22quantity%22%3A3%2C%22options%22%3A%7B%22Color%22%3A%22White%22%2C%22Size%22%3A%2211oz%22%7D%7D%2C%7B%22id%22%3A66722581%2C%22quantity%22%3A5%7D%5D%2C%22profile%22%3A%7B%22address%22%3A%7B%22name%22%3A%22john%20smith%22%2C%22companyName%22%3A%22general%20motors%22%2C%22street%22%3A%225th%20Ave%22%2C%22city%22%3A%22New%20York%22%2C%22countryCode%22%3A%22US%!%22%7D%7D

Storefront JavaScript API

Any Ecwid storefront has a JavaScript API available at all times to help users create various customizations for their storefronts.

Its features include:

  • detect currently opened page details
  • set shipping and billing address for customer
  • get customer’s cart details
  • manage customer’s cart and others.

To find our more about it, plesae see the Storefront JavsScript API Documentation.

We use cookies and similar technologies to remember your preferences, measure effectiveness of our campaigns, and analyze depersonalized data to improve performance of our site. By choosing «Accept», you consent to the use of cookies.