Ecwid integration#

Use an Ecwid custom storefront app and the documented Storefront JS API lifecycle to add Room Visualizer controls to Ecwid product pages.

Verification status: Ecwid Storefront JS API documentation reviewed on September 7, 2026. No Ecwid app or merchant test store was available. Exact page payload fields must be confirmed against the current OnPageLoaded reference before deployment.

Before loading the SDK: Open Dashboard → Settings, add your storefront origin to Allowed Origins (CORS), and click Save. Include the published hostname and any preview or staging origins you use; separate multiple origins with commas. See configuration steps.

Prerequisites and supported path#

Ecwid requires a custom app with a self-hosted JavaScript file for durable storefront customization. Prepare an Ecwid development store/app, an HTTPS-hosted adapter file, Shop ID, Publishable Key, and imported product/variation SKUs.

If Ecwid is embedded in another CMS, the custom storefront app remains the reliable place for code because it runs with the Ecwid storefront. A parent-page script may not share the same lifecycle or document in every embed mode.

Minimal SDK contract#

html

<script
  src="https://sdk.ideal.house/sdk.js"
  data-shop-id="<SHOP_ID>"
  data-publishable-key="<PUBLISHABLE_KEY>"
  async
></script>

<div data-idealhouse-button-container data-product-code="CHAIR-OAK-01"></div>

Use the exact Ecwid SKU you imported as ideal.house sku.

Initialize your Ecwid storefront app#

Follow Ecwid's custom storefront quickstart to register the self-hosted file. Start it with the documented API-ready callback, then load the ideal.house SDK once:

Ecwid.OnAPILoaded.add(function () {
  if (document.querySelector('script[src="https://sdk.ideal.house/sdk.js"]')) return;

  const script = document.createElement('script');
  script.src = 'https://sdk.ideal.house/sdk.js';
  script.async = true;
  script.dataset.shopId = '<SHOP_ID>';
  script.dataset.publishableKey = '<PUBLISHABLE_KEY>';
  document.head.append(script);
});

For a multi-store app, obtain the two public ideal.house values from your app's safe public configuration. Never put an Ecwid app secret, access token, or ideal.house Client Secret into this file.

Render on product pages#

Ecwid documents Ecwid.OnPageLoaded.add() and supplies page information to its callback. Use the current API reference to confirm the product-page type and identifier, fetch or read the product data through Ecwid's supported client interface, then pass the resolved SKU to:

function mountIdealhouse(host, sku) {
  host.replaceChildren();
  const code = String(sku || '').trim();
  if (!code) return;

  const container = document.createElement('div');
  container.dataset.idealhouseButtonContainer = '';
  container.dataset.productCode = code;
  host.append(container);
}

Insert host into a stable product-details location after Ecwid finishes rendering the page. Remove the prior host when the page type changes. The DOM selector and page-payload-to-product lookup are customer adapter code because Ecwid storefront layouts and payload versions can change.

When a shopper chooses product options, wait until Ecwid resolves the purchasable variation and its SKU. Call mountIdealhouse() with that SKU, or clear the host if the selection is incomplete. Do not concatenate option labels to manufacture a code.

Ecwid is a single-page storefront. Use its documented page lifecycle (OnPageLoaded/page-switch callbacks) instead of listening only for browser DOMContentLoaded. Category/search navigation, browser Back/Forward, embedded widgets, and product popups must remove stale product hosts and mount a new container after rendering.

Import products#

Export the Ecwid product and variation SKU fields and map them to ideal.house sku. Use Product upload, including import products, job status, list products, update products, delete product, and errors and retries.

Any Ecwid REST API export, webhook, OAuth installation, or recurring sync is customer-owned and must be implemented server-side with the appropriate Ecwid authorization.

Verify and remove#

Test app installation, API initialization, product/category/search transitions, every variation, missing and unknown SKUs, browser Back/Forward, an Ecwid widget embedded on another site, mobile layout, consent, and logged-in/out customers. Confirm one SDK request in the document containing the host and exact SKU equality.

To remove, detach the self-hosted JavaScript file from the custom app or uninstall the app, remove injected hosts/listeners, and verify the SDK URL and all data-idealhouse-* nodes disappear after storefront navigation and a hard refresh.