LogoLogo
Build appsContact API support
Build apps
  • Build apps
  • Site Templates
  • API Reference
  • Changelog
Build apps
  • Build with Ecwid apps
  • Ecwid API features
  • Get started
    • Set up your dev environment in Ecwid
    • Make your first API request
    • Add more features to your custom app
    • API glossary
  • Develop apps
    • What is an Ecwid app
    • Private and public Ecwid apps
    • App settings
    • Community libraries
  • Launch apps
    • Public apps overview
    • Monetize public apps
    • Steps to go live with a public app
    • Native and external apps
      • Access store data from the app
      • Build user settings page for Ecwid admin
        • Use Native app JS SDK
        • Deep linking
        • Manage personal user settings storage
  • Contact Ecwid API support team

Lightspeed® 2025

On this page
  • EcwidApp.init()
  • EcwidApp.openPage(page)
  • EcwidApp.ready()
  • EcwidApp.setSize(height)
  • EcwidApp.sendUserToUpgrade(features)

Was this helpful?

  1. Launch apps
  2. Native and external apps
  3. Build user settings page for Ecwid admin

Use Native app JS SDK

Native app JS SDK offers useful JavaScript methods for interacting with Ecwid stores from within your app. Use our HTML template or manually add the required JS file into your iframeUrl to use the SDK: https://djqizrxa6f10j.cloudfront.net/ecwid-sdk/js/1.3.0/ecwid-app.js

<head>
<!-- Include Ecwid JS SDK -->
<script src="https://djqizrxa6f10j.cloudfront.net/ecwid-sdk/js/1.3.0/ecwid-app.js"></script>
</head>

Find the list of available methods below:

EcwidApp.init()

This method initializes your app inside Ecwid admin. Call it once at the beginning of executable code in your app. This method is required to make the app work inside the Control Panel.

Code example:

// Initialize the application
EcwidApp.init({
  app_id: "client_id", // use client_id of your application
  autoloadedflag: true, 
  autoheight: true
});

Available fields:

Name
Type
Description

app_id

string

autoloadedflag

boolean

Set true if you want Ecwid to detect when the app is loaded, stop the "Loading" animation, and display the settings page to users.

Set falseif you want to control this moment with the EcwidApp.ready() method.

autoheight

boolean

Set true if you want Ecwid to adjust the iframe height dynamically depending on the settings page content.

Set falseif you want to control iframe size with the EcwidApp.setSize() method.

EcwidApp.openPage(page)

Use this method to redirect users to another Ecwid admin page. Specify the page with the hash (#) part in the URL. For example, billing will open the Billing page, products will open the Catalog - Products page:

Page URL: https://my.ecwid.com/store/1003#products Call: EcwidApp.openPage('products');

This method supports everything users can see after the hash (#), including order IDs, product IDs, etc:

Page URL: https://my.ecwid.com/store/5035009#order:id=938&return=orders Call: EcwidApp.openPage('order:id=938&return=orders');

EcwidApp.ready()

Use this method to "manually" inform Ecwid when your application is ready to be shown to users.

For example, your app needs some API calls or additional heavy assets before it is ready for display. Pass false in the autoloadedflag parameter in the EcwidApp.init() method and call the EcwidApp.ready() function when you are ready.

Code example:

// Initialize the application
EcwidApp.init({
  app_id: "my-super-app", // use your application client_id
  autoloadedflag: false, // disable automatic detection of ready state
  autoheight: true
});

// Show app UI
EcwidApp.ready();

EcwidApp.setSize(height)

Use this method to set the application iframe height in pixels manually.

We recommend using the autoheight: true in EcwidApp.init() method to let Ecwid dynamically adjust your app iframe size depending on your application content. But if you want to control the iframe size yourself, set that flag as false and use this EcwidApp.setSize() method.

Code example:

// Initialize the application
EcwidApp.init({
  app_id: "my-super-app", // use your application client_id
  autoloadedflag: true, 
  autoheight: false // disable automatic detection of app size
});

// Set app height to 800 pixels. 
EcwidApp.setSize(800);

EcwidApp.sendUserToUpgrade(features)

Use this method to initiate the plan upgrade process for users right from your app interface. The features argument supports multiple values separated by a comma.

Code example:

// Send user to upgrade to get Product Variations feature
EcwidApp.sendUserToUpgrade(["COMBINATIONS"]);

// Send user to upgrade to the minimal plan where Order Editor and Marketplaces features are available
EcwidApp.sendUserToUpgrade(["ORDER_EDITOR", "MARKETPLACES"]);

Ecwid determines the minimum required plan for the store owner to use features you pass and then initiates the upgrade process.

Last updated 5 days ago

Was this helpful?

Must be client_id of your application. If you don't know it, go to the application Details page from and find it there. Required

Only the app_id field is required, but we recommend leaving all three fields and if you notice any issues with your app loading or height.

Find a list of features in availableFeatures field in the endpoint.

emailing us
#develop-apps
Get store profile