NAV

Subscribe to Events

Find various useful events and execute your functions with them.

Ecwid.OnAPILoaded

OnAPILoaded usage example

Ecwid.OnAPILoaded.add(function() {
    console.log("API is loaded")
});

This event contains callback functions that are called exactly when the Ecwid Javascript API loads and becomes available under the window.Ecwid top-level object. Functions attached to this event do not accept any parameters and do not require to return any value.

Ecwid.OnPageLoad/Ecwid.OnPageLoaded

If user visits cart page, do domething

Ecwid.OnPageLoaded.add(function(page) {
    if (page.type == "CART") {
      // do something ...
  }
});

These events contain callbacks that get called on each page change inside the product browser. The difference between OnPageLoad and OnPageLoaded is that the former is called when the page is changed (e.g. a link is clicked), while the latter is called later when the corresponding page is loaded inside the product browser.

The callback functions accept one parameter of type Page specifying which page is to be loaded (or has already been loaded). See Page Object details for more info.

Page Object

Describes the page displaying inside the product browser.

Get page type after new page is loaded

Ecwid.OnPageLoaded.add(function(page){
  console.log("Current page is of type: " + page.type);
})

// prints
// Current page is of type: CATEGORY

Fields:

NameTypeDescription
typestring, one of the following: ‘ACCOUNT_SETTINGS’, ‘ADDRESS_BOOK’, ‘ORDERS’, ‘CATEGORY’, ‘CART’, ‘CHECKOUT_ADDRESS_BOOK’, ‘CHECKOUT_PAYMENT_DETAILS’, ‘CHECKOUT_PLACE_ORDER’, ‘CHECKOUT_SHIPPING_ADDRESS’, ‘ORDER_CONFIRMATION’, ‘ORDER_FAILURE’, ‘CHECKOUT_RESULT’, ‘DOWNLOAD_ERROR’, ‘PRODUCT’, ‘SEARCH’, 'FAVORITES’The type of the page. Some pages may have parameters like for example product id of the viewing product. Those parameters are described below.
keywordsstring, optionalfor type==’ORDERS’: the keywords that are used to find orders in the customer account page. for type==’SEARCH’: the keywords that are used to find products on the product search page.
frominteger timestamp, optionalfor type==’ORDERS’: The timestamp of the start of the orders date range.
tointeger timestamp, optionalfor type==’ORDERS’: The timestamp of the end of the orders date range.
offsetfor type==’ORDERS’: the position of the current order list page (starting from 0). for type==’CATEGORY’ and SEARCH’: the position of the current product list page (starting from 0).
categoryIdintegerfor type==’CATEGORY’: the id of the showing product category or 0 if this is the starting page of the catalog and no categories are selected yet. for type==’PRODUCT’: the category internal id the current product has been navigated from. Zero (0) is the root category, −1 meaning that the category is unknown (e.g. a product opened from a search result).
mainCategoryIdintegerfor type==’PRODUCT’ in the OnPageLoaded event: the internal id of category that is considered the default category of this product (in case if the product is assigned to a few different categories). If a product is assigned to a single category, mainCategoryId will be equeal to categoryId; if a product is not assigned to any category, its mainCategoryId is 0 (zero). for type==’PRODUCT’ in the OnPageLoad event: always 0 (zero);
sortstring, one of: ‘normal’, ‘addedTimeDesc’, ‘priceAsc’, ‘priceDesc’, ‘nameAsc’, ‘nameDesc’for type==’CATEGORY’ and ’SEARCH’: the order of the product list, as selected by the user in the ‘sort by’ drop-down. ‘Desc’ suffix stands for the descending order, ‘Asc’ suffix stands for the ascending order.
orderIdintegerfor type==’CHECKOUT_RESULT’ and type==’ORDER_CONFIRMATION’: the internal id of the order (not to be confused with the store order number)
ticketintegerfor type==’CHECKOUT_RESULT’: the security random code that allows to retrieve information about the order
errorTypeone of the following: ‘expired’, ‘invalid’, ‘limit’for type==’DOWNLOAD_ERROR’: the type of the error while downloading an e-good file.
keyinteger, optionalfor type==’DOWNLOAD_ERROR’: the downloading file internal id
productIdintegerfor type==’PRODUCT’: the internal id of the displaying product (not to be confused with SKU).
orderNumberintegerfor type==’ORDER_CONFIRMATION’ the number of the order placed by customer(without prefix and suffix).
vendorOrderNumberstringfor type==’CHECKOUT_RESULT’ and type==’ORDER_CONFIRMATION’ the number of the order placed by customer(with prefix and suffix).

Ecwid.OnSetProfile

Ecwid.OnSetProfile code example

<script src="//app.ecwid.com/script.js?1003" type="text/javascript" charset="UTF-8"></script>
<script>
function dump(arr,level) {
  var dumped_text = "";
    if (!level) level = 0;
    // The padding given at the beginning of the line.
      var level_padding = "";
      for (var j=0;j<level+1;j++) level_padding += " ";
        if (typeof(arr) == 'object') { // Array/Hashes/Objects
          for (var item in arr) {
          var value = arr[item];
            if (typeof(value) == 'object') { // If it is an array,
            dumped_text += level_padding + "'" + item + "' ...\n";
            dumped_text += dump(value,level+1);
            } else {
            dumped_text += level_padding + "'" + item + "' => \"" + value + "\"\n";
            } 
          }
        } else { // Stings/Chars/Numbers etc.
        dumped_text = "===>"+arr+"<===("+typeof(arr)+")";
      }
      return dumped_text;
  }

Ecwid.OnSetProfile.add(function(customer) {
  if (customer == null) document.getElementById('CUSTOMER').innerHTML = 'not logged in';
    else document.getElementById('CUSTOMER').innerHTML = dump(customer);
});
</script>
<div><pre id='CUSTOMER'/></div>
<script>
xProductBrowser();
</script>

This event contains callback functions that receive the changes in the current customer profile.

If no customer is logged in, these functions receive null. Whenever a customer logs in/out, the callback functions are called with either the corresponding parameter of type Customer or null. Example code can be seen on the right.

Ecwid.OnCartChanged

Specify a callback function when cart is changed in storefront

Ecwid.OnCartChanged.add(function(cart){
    // your code here
}) 

This event contains callback functions that get called each time when a shopping cart is changed — either by the customer or due to system events.

The callback function receives cart object as an argument, that has the new shopping cart state after the change is applied.

The callbacks added to Ecwid.OnCartChanged will be called when the shopping cart is initialized and on every occasion when either of the properties of the passed cart object is changed. These occasions include:

  • Cart initialization
  • Adding a product to cart
  • Removing a product from cart
  • Changing the product’s options
  • Clearing the cart
  • Applying a discount coupon
  • Selecting and changing the selection of the shipping method
  • Changing shipping address
  • Syncing the cart contents, if there are a few browser tabs with the store are opened
  • Clearing the cart upon user’s logout — in this occasion the callback receives null as an argument.

The passed cart object represents only the basic properties of the shopping cart. It contains the data coming from the customer’s actions (like products, coupons, shipping methods) and might not contain the calculated aggregates (like order totals, shipping costs, the discounted amounts or taxes). For the calculated aggregates, it is rather recommended to use the Ecwid.Cart.calculateTotal() method.

Ecwid.OnProductOptionsChanged

Show an alert if product options were changed

Ecwid.OnProductOptionsChanged.add(function(productid) {
   window.alert("Options changed, product id:" + productid);    
})

This event executes callback function each time when product option was changed. The callback functions accept one parameter: productid, specifying ID of the product changed.

OnProductOptionsChanged works for following options type: dropdown list, radio button and checkbox. Input, textarea and upload files types are not supported yet.

Ecwid.OnOrderPlaced

Get order number of a placed order

Ecwid.OnOrderPlaced.add(function(order){
  console.log(order.orderNumber);
})

// 781

Ecwid.OnOrderPlaced() event allows you to get details of an order placed by a customer in storefront right after an order is placed. This event provides the order object in callback function so that you can get order details right after the event occurs.

Order object

Describes the details of a placed order by customer.

Fields

NameTypeDescription
itemsArray<OrderItems>Items purchased in order
productsQuantityintegerTotal quantity of purchased items in order
couponNamestringApplied coupon name. undefined if no coupon was used
weightnumberTotal order weight
paymentMethodstringSelected payment method name. undefined if no method selected
shippingCarrierNamestringSelected shipping carrier name. undefined if no method selected
shippingMethodstringSelected shipping method name. undefined if no method selected
totalnumberOrder total
subtotalnumberOrder subtotal
taxnumberOrder total tax
couponDiscountnumberCoupon discount applied to order
volumeDiscountnumberSum of discounts based on subtotal
customerGroupDiscountnumberSum of discounts based on customer group
discountnumberTotal discount amount for order
shippingnumberTotal shipping cost for order
handlingFeenumberHandling fee applied to order
shippingAndHandlingnumberSum of shipping and handlingFee fields
billingPerson<PersonInfo>Customer billing information
shippingPerson<PersonInfo>Customer shipping information
affiliateIdstringAffiliate ID value for order
orderNumbernumberOrder number in a store
vendorNumberstringOrder number with custom prefixes and suffixes of that store
datestring (UNIX Timestamp)Date when order was placed as a UNIX Timestamp, e.g. "1484638550"
paymentStatusstringPayment status of an order. One of: AWAITING_PAYMENT, PAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, INCOMPLETE
fulfillmentStatusstringFulfillment status of an order. One of: AWAITING_PROCESSING, PROCESSING, SHIPPED, DELIVERED, WILL_NOT_DELIVER, RETURNED, READY_FOR_PICKUP
customer<CustomerInfo>Basic customer info
OrderItems
NameTypeDescription
quantityintegerQuantity of an item in order
product<ProductInfo>Product details
optionsMap<OptionsInfo>Selected product options

ProductInfo

NameTypeDescription
idIntegerInternal unique product ID
nameStringProduct name
priceIntegerProduct price
shortDescriptionStringProduct description truncated to 120 characters
skuStringProduct SKU
urlStringURL to this product details page in store front (store front URL is generated from a field in Ecwid Control panel > Settings > General > Store profile)
weightIntegerWeight of a product

OptionsInfo

NameTypeDescription
selectedOptionstringSelected option name as a key, its value as a value of that key. For dropdown, radio, textarea, textfield options value is a string; for checkbox option the value is a comma-separated list of selected values in a single string; for date option the value is a selected date according to the store format; for files option the value is a string in a format: "4 files"

PersonInfo

NameTypeDescription
namestringCustomer’s name
companyNamestringCustomer’s company name
streetstringCustomer’s street address
citystringCustomer’s city
countryNamestringCustomer’s country name. countryCode can be used instead
countryCodestringCustomer’s country code. countryName can be used instead
postalCodestringCustomer’s zip code
stateOrProvinceCodestringCustomer’s state or province code
stateOrProvinceNamestringCustomer’s state or province name
phonestringCustomer’s phone number

CustomerInfo

NameTypeDescription
namestringCustomer’s name
emailstringCustomer’s email