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 a pre-defined price range. Pass parameters as a second argument in the function.

product

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

  • 'id'- Product ID. This is a required parameter for opening product pages.
  • name - Product name as it would look in the URL: lowercase, spaces replaced with dashes. For example, "Pizza 33cm" product name would transform into pizza-33cm.
  • slug_value - Custom page slug for the product. Use it instead of the name parameter if a product has a custom slug.
  • 'variation' - Accepts Product variation ID as a value to open a specific product variation.
  • 'options' - Accepts an array of product option choices (dropdown and radio button option types). Option choices are assigned to product options depending on the option index (starts at 1). For example, 'options': [3,1] selects the third value for the first option, and the first value for the second option.

📘

If you pass both id and name or id and slug_value parameters, Ecwid JS API will create a product URL and open it without making additional backend requests to confirm the category exists. The choice between the name or slug_value parameters depends on whether a product has a custom slug.

Code examples:

Ecwid.openPage('product', {'id': 72585497, 'slug_value': 'best-toys'});

Ecwid.openPage('product', {'id': 45523512, 'name': 'Pizza Roll'});

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

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

There is an alternative way to open a page with pre-selected options or a variation without JS API. You can add option choices or the variation ID (?options=1,2,3 or ?variation=123456) as a query parameter to product page URLs and open it. 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 will ignore any other params and open the root category page ('id': 0).
  • name - Category name as it would look in the URL: lowercase, spaces replaced with dashes. For example, "Rental Spaces" category name would transform into rental-spaces.
  • slug_value - Custom page slug for the category. Use it instead of the name parameter if a category has a custom slug.
  • 'page' - Page number for categories where products don't fit on one page. If you pass a value bigger than the number of pages in the category, Ecwid will open the last page.

📘

If you pass both id and name or id and slug_value parameters, Ecwid JS API will create a category URL and open it without making additional backend requests to confirm the category exists. The choice between the name or slug_value parameters depends on whether a category has a custom slug.

Code example:

Ecwid.openPage('category', {'id': 20671017, slug_value: 'rental', 'page': 2});

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});

Ecwid.showProductFilters()

This method is used to open the side menu with product filters on category pages.

Code example:

Ecwid.showProductFilters();

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