Get started with Storefront JS API

Ecwid storefront is a store working on a website where customers can browse for products. Ecwid storefront has many design and configuration settings out of the box that work on any website where it's displayed. Still, you can customize storefront design and functionality further with custom scripts and stylesheets.

Our JS API has many ready-to-use functions for managing store design settings, customers, and carts, and receiving different information without going server-side and making REST API requests.

Pre-requirements

To use Storefront JS API, you need a custom app and a JavaScript file hosted on your side.

1. Custom application. If you don't have a custom app yet, please refer to this instruction.
2. Access scopes. The app requires the following access scope: customize_storefront.
3. Endpoints. The app requires at least one of these endpoints:
   1. customJsUrl - link to your JavaScript file.
   2. customCssUrl - link to your stylesheet.

Set up JavaScript file for the storefront

Host your JavaScript file on a static link and email us this link alongside your store ID or application name/ID. We will add access scope and file URL to the app settings and write back to you.

After that, Ecwid will automatically load the customJsUrland customCssUrl files from your server and execute them every time the customer opens or switches storefront pages. You only need to set up the application once and install it in all stores where your script is required. Ecwid takes care of the rest.

Ecwid ensures that your files load and execute on any store website, even if the store works on multiple websites.

Enable JS API on the storefront

Ecwid has a collection of pre-built methods for triggering your code based on certain conditions and managing store data and configs safely from the storefront. We refer to it as Storefront JS API or simply JS API. By default, the JS API is not loaded on the page to improve loading times.

Make sure you always start your code with the Ecwid.OnAPILoaded() function to enable JS API on the page.

Code example:

Ecwid.OnAPILoaded.add(function() {
	Ecwid.OnPageLoaded.add(function(page) {
    if (page.type == "PRODUCT") {
       console.log(
        `
       Page loaded!
       Ecwid store ID is: ${Ecwid.getOwnerId()}
       Product ID is: ${page.productId}
        `
       )
    }
	})
})
// prints
//
//      Page loaded!
//      Ecwid store ID is: 1003
//      Product ID is: 560656065

Write scripts for the storefront

Now you can write JavaScript code and use JS API methods to expand existing and create new functionalities on the storefront. Our JS API has dozens of ready-to-use methods to dynamically adjust store design and behavior, receive store data without server-side calls, and manage customers.

If your code requires additional JavaScript files, you can load them from the customJsUrl file. We recommend using a standard createElement() function to create a new <script> element on the page. This code doesn't rely on JS API and therefore could be called before Ecwid.OnAPILoaded() function.

Code example:

var s = document.createElement("script");
s.type = "text/javascript";
s.src = "https://example.com/example.js";
document.head.appendChild(s);

Learn more about available JS API methods in the pages below and build unique UI/UX with Ecwid!