Apply for App Market
API Reference
Join Slack CommunityEmail us

Methods for storefront management

Storefront JS API has methods for receiving and managing different storefront details. For example, you can:

  • Receive and manage store settings and design configuration
  • Receive information about store pages and redirect users to different pages
  • Manage Ecwid widgets on custom websites and load them dynamically

Enable JS API on the storefront

The methods listed below require JS API to be loaded on the page. Read more on how to enable JS API.

Ecwid.getOwnerId()

This method responds with Ecwid store ID.

Code example:

var storeId = Ecwid.getOwnerId()
console.log(storeId);

// prints
// 1003

Ecwid.getStorefrontLang()

This method responds with the current storefront language.

Code example:

var lang = Ecwid.getStorefrontLang();
console.log(lang);

//prints
// "en"

Ecwid.getAppPublicToken()

This method accepts app client_id as an argument and responds with a public access token for the app. Such token is safe to use on the storefront, it won't reveal any private store data.

Code example:

var publicToken = Ecwid.getAppPublicToken('my-cool-app');
console.log(publicToken);

// prints
// public_qKDUqKkNXzcj9DejkMUqEkYLq2E6BXM9

Ecwid.getAppPublicConfig()

This method accepts app client_id as an argument and responds with a public config for the app. Read more about setting up a public config for applications.

Code example:

var publicConfig = Ecwid.getAppPublicConfig("client_id");
console.log(publicConfig);

// prints
// {"key": "public","value": "{'color':'red','text':'Email button','border-radius':'3px'}"}

Ecwid.getInitializedWidgets()

This method responds with a list of currently enabled widgets.

Code example:

var widgets = Ecwid.getInitializedWidgets();
console.log(widgets);

// prints 
// ["Minicart", "SearchPanel", "ProductBrowser"]

Full list of widgets:

  • Minicart - Minicart widget
  • SearchPanel - Search widget
  • ProductBrowser - Main storefront widget, contains full Ecwid store
  • Categories - Horizontal categories menu widget
  • Product - Widget with an embedded product page

Ecwid.isStorefrontV3()

This method is mostly for public applications developed before 2024. Use it to define if you should adapt your application for an old storefront design in this store.

Code example:

var v3Migration = Ecwid.isStorefrontV3();
console.log(v3Migration);

// prints if enabled
// true

Ecwid.formatCurrency()

This method is used to check a currency format on the storefront. It accepts a numeric price value as an argument and responds with a price format with a currency symbol according to the store settings.

Code example:

var currencyFormat = Ecwid.formatCurrency(12.99);
console.log(currencyFormat);

// prints
// "$12.99"

Ecwid.setStorefrontBaseUrl()

This method allows redirecting storefront widgets loaded on the current page to another page on the website. The most common use case is when you have several Ecwid widgets on different pages of your custom website and want them all to work with the same cart and checkout on one of the pages.

Example:

example.com/store - main store page

example.com/sale - page with products currently on sale

example.com/gift-cards - page with a gift card product widget

In this case, you can make all three pages to work through the checkout on the /store by executing the following line of code on pages example.com/sale and example.com/gift-cards:

Ecwid.setStorefrontBaseUrl('example.com/store');

Ecwid.openPage()

This method allows opening a specific page on the storefront. It accepts page slug and some additional parameters in its arguments.

Code example:

Ecwid.openPage('product')

Pages list:

  • 'cart' - Checkout step 1. Customers enter their email and apply discount coupons.
  • 'checkout/address' - Checkout step 2. Customers enter their address.
  • 'checkout/shipping' - Checkout step 3. Customers choose shipping/pickup method.
  • 'checkout/payment' - Checkout step 4. Customers choose a payment method and go to the payment page.
  • 'checkout/order-confirmation'- "Thank you for purchase" page customers see after placing an order.
  • 'account' - Customer's account page.
  • 'account/address-book'- Customer's account page (saved shipping addresses).
  • 'account/favorites'- Customer's account page (products added to favorites).
  • 'pages/about' - Legal page (about the store).
  • 'pages/shipping-payment' - Legal page (shipping/payment policies).
  • 'pages/returns' - Legal page (return policy).
  • 'pages/terms' - Legal page (Terms of use).
  • 'pages/privacy-policy' - Legal page (Cookie/Privacy policies).

Open page with parameters

Parameters allow you to open a specific page, for example, product variation or a search with pre-defined price range. Pass parameters as a second argument in function.

product

For product pages, additional parameters include: 'id', 'variation', and 'options':

  • 'id'- Product ID. This is a required parameter for opening product pages.
  • 'variation' - Product variation ID. Use it to open a specific variation on a product page.
  • 'options' - Selection of product options that support dropdown and radio button options, e.g. [3,2]. Each value will be assigned to product options depending on its index in the list of available selections. The index starts at 1.
    'options': [3,2] means that for the first option the third value will be pre-selected and for the second option it will be the second value.

Code examples:

Ecwid.openPage('product', {'id': 72585497, 'variation': 16351010});

Ecwid.openPage('product', {'id': 72585497, 'options': [2,2]});

Alternatively, you can add ?options=1,2,3 or ?variation=123456 query params to product page URLs to open a product page with pre-selected options or a specific variation. Resulting URL examples:
https://example.com/store/example-product?variation=163510
https://example.com/store/example-product?options=4,3

category

For category pages, additional parameters include: 'id' and 'page':

  • 'id' - Category ID. If not specified, Ecwid opens root category page with 'id': 0.
  • 'page' - Page number for categories where products don't fit on one page. If the page value is bigger than the number of pages in a category, the last page will be opened.

Code example:

Ecwid.openPage('category', {'id': 20671017, 'page': 3});

search

For the search page, Ecwid has several additional parameters passed inside the 'search' argument:

  • 'keyword': Search string for product title, description, and SKU.
  • 'inventory': Supports only one value: if instock, only products "In stock" are returned.
  • 'onsale': Supports only one value: if onsale, only products with "Compare to" prices are returned.
  • 'priceFrom': Minimum product price for search, for example, 500.00.
  • 'priceTo': Maximum product price for search, for example, 899.99.
  • 'offset': Offset from the beginning of the returned items list. Default is 0.
  • 'categories': Category IDs for search, for example: 0,123456,8236623
  • 'includeProductsFromSubcategories': Supports two values: if true, the search includes products from subcategories of selected categories, false otherwise. Default is true.
  • 'attribute_[name]=[values]': Search by product attributes. Accepts several values separated by a comma. To search for an exact match to attribute value, enclose it in quotation marks.
  • 'option_[name]=[values]': Search by product options. Accepts several values separated by a comma. To search for an exact match to option value, enclose it in quotation marks.
  • 'createdFrom': Product creation datetime (lower bound) matching REST API date format, for example, createdFrom=2020-01-30 10:00:00 +0000.
  • 'createdTo': Product creation datetime (upper bound) matching REST API date format, for example, createdFrom=2020-01-30 10:00:00 +0000.

Code examples:

Ecwid.openPage('search', {'keyword': 'surfboard', 'page': 2});

Ecwid.openPage('search', {'priceTo': '50'});

Ecwid.openPage(
    'search', 
    {
      'keyword': 'shoes', 
      'attribute_Brand': 'Nike',
      'inventory': 'instock',
      'offset': 50
    }
  );

account

For the account sign in page, there is only one additional parameter:

  • 'returnurl' - Optional parameter for redirecting users to a specific URL after successful login.

Code example:

Ecwid.openPage('account', {'returnurl': 'https://www.ecwid.com/demo/Surfboards-c20671017'});

account/subscription

For the account subscriptions page, there is only one additional parameter:

  • 'id' - Subscription ID used to redirect customers to a specific subscription page. Required parameter.

Code example:

Ecwid.openPage('account/subscription', {'id': 1006502});

Methods for Instant Site home page

Instant Site home page is designed to load as fast as possible. As a result, it doesn't have the product browser and works with a limited number of JS API methods.

The collection of methods for home page includes two automatic event triggers and 3 data-receiving methods.

Read more about event triggers for Instant Site home page.

window.instantsite.getSiteId() 

This method responds with Ecwid store ID.

Code example:

window.instantsite.getSiteId()

window.instantsite.getAppPublicConfig("client_id")

This method accepts app client_id as an argument and responds with a public config for the app. Read more about setting up a public config for applications.

Code example:

var publicConfig = window.instantsite.getAppPublicConfig("client_id");
console.log(publicConfig);

// prints
// {"key": "public","value": "{'color':'red','text':'Email button','border-radius':'3px'}"}

window.instantsite.getAppPublicToken("client_id") 

This method accepts app client_id as an argument and responds with a public access token for the app. Such token is safe to use on the storefront, it won't reveal any private store data.

Code example:

var publicToken = Ecwid.getAppPublicToken('my-cool-app');
console.log(publicToken);

// prints
// public_qKDUqKkNXzcj9DejkMUqEkYLq2E6BXM9