OpenCart integration#

Add Room Visualizer through an OpenCart 4 extension or custom theme and map a stable storefront product code to the ideal.house catalog.

Verification status: OpenCart 4 extension documentation reviewed on September 7, 2026. No test store was available. OpenCart 3 and third-party themes use different paths and event conventions; adapt this guide to the installed major version.

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 code choice#

Prepare a staging shop, extension/theme development access, Shop ID, Publishable Key, and imported test records. OpenCart core commonly exposes model in product templates, while SKU may require controller/extension work depending on version and theme. Pick one value and use it consistently as ideal.house sku.

Do not edit core catalog files directly. Package changes as an OpenCart 4 extension or keep them in a version-controlled custom theme.

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>

The Product Code must equal the imported ideal.house sku character for character.

Render the product container#

Extend the active product template through your extension. If you deliberately map the OpenCart model field to ideal.house sku, place this near the product actions:

twig

{% if model %}
  <div class="idealhouse-host">
    <div
      data-idealhouse-button-container
      data-product-code="{{ model }}">
    </div>
  </div>
{% endif %}

Twig autoescaping depends on environment configuration; ensure the chosen value is HTML-attribute escaped. If you choose the real SKU field, add that sanitized value to the controller's template data in your extension and render it instead of model.

Load the SDK once#

Add a storefront JavaScript asset through the extension/theme mechanism. It should create one script with required attributes:

if (!document.querySelector('script[src="https://sdk.ideal.house/sdk.js"]')) {
  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);
}

Store the two public values in extension configuration and render them safely. Never place an ideal.house Client Secret in JavaScript, Twig, extension logs, or cached HTML.

Options, variants, and dynamic rendering#

OpenCart options do not universally map one-to-one to SKU-bearing variants. If your store uses an option/variant extension, integrate with that extension's documented resolved-variant callback and data model. Replace the host only when it provides the exact selected code:

function renderIdealhouseCode(host, productCode) {
  host.replaceChildren();
  const code = String(productCode || '').trim();
  if (!code) return;
  const container = document.createElement('div');
  container.dataset.idealhouseButtonContainer = '';
  container.dataset.productCode = code;
  host.append(container);
}

This is customer adapter code; there is no universal OpenCart variant event in this guide. For AJAX search, category filters, popups, and quick view, render clean containers in the extension's templates or call the bridge from its documented completion callback. Never copy children produced by the SDK.

Import products#

Export the chosen OpenCart model/SKU for every visualizable item and map it to ideal.house sku. Use Product upload, then follow import products, job status, list products, update products, delete product, and errors and retries.

OpenCart Admin API calls, scheduled exports, event listeners, and webhooks are customer-owned integration work.

Verify and remove#

Test simple products, every supported option combination, missing and duplicate codes, unknown ideal.house SKUs, category/search pages, quick view, browser Back/Forward, mobile layout, multiple stores, languages/currencies, consent, and production cache/minification. Confirm exactly one SDK request and an exact code match.

To remove, disable/uninstall the extension or remove the custom-theme override and asset, refresh OpenCart modifications/events, clear theme/CDN caches, and verify the SDK request and containers are absent.