Installation & Setup

Get your TimberCloud Embeddable Storefront up and running in minutes with this step-by-step guide.

Tip: Embedding the storefront isn't the only way to get online. If you don't already have a website, you can instead launch a fully hosted, white-label site on your own custom domain with the Site Builder — no embed code required.

Prerequisites

Before you begin, ensure you have:

A TimberCloud account (a paid plan is required for checkout and payments; on the Free plan the storefront is inquiry/quote-only)
Products configured in your catalog
Your company slug (found in Settings → Company)
Access to edit your website's HTML
HTTPS enabled on your website (required for payments)

Integration Methods Overview

Method	Description	Best For
Script Embed	Auto-creates iframe with data attributes	Most websites, SPAs
Iframe Embed	Direct iframe with optional integration script	Custom styling needs

Method 1: Script Embed (Recommended)

The easiest way to integrate — add a container and the script:

<div id="timbercloud-embed"></div>
<script
  src="https://embed.timbercloud.com/embed.js"
  data-company="your-company-slug"
  data-theme="light"
  data-width="100%"
  data-height="800px"
  defer
></script>

Replace your-company-slug with your actual company slug.

Script Attributes

Attribute	Required	Default	Description
`data-company`	✅ Yes	—	Your TimberCloud company slug
`data-theme`	No	`light`	Passed through to the iframe element. See the note below — this does not set the storefront's light/dark theme.
`data-width`	No	`100%`	Width of the embed
`data-height`	No	`800px`	Height of the embed

Important: data-theme does not control the storefront's appearance. The script only copies it onto the iframe tag; the storefront app ignores it. Your storefront's light/dark theme comes from the theme mode setting in your TimberCloud account (Settings → Website / company settings), so it stays consistent no matter what you put in the embed code. To change light vs. dark, update your theme setting — see Customization.

What the Script Does

The embed.js script automatically:

✅ Creates and configures the iframe
✅ Handles password reset email links
✅ Manages SPA URL changes
✅ Supports dynamic resize messages from the embed
✅ Cleans URL parameters after password reset

Full-Width Example

<div 
  id="timbercloud-embed"
  style="
    position: relative;
    left: 50%;
    right: 50%;
    margin-left: -50vw;
    margin-right: -50vw;
    width: 100vw;
    max-width: 100vw;
    overflow: hidden;
    padding: 0 16px;
  "
></div>
<script
  src="https://embed.timbercloud.com/embed.js"
  data-company="your-company-slug"
  data-theme="light"
  data-width="100%"
  data-height="1280px"
  defer
></script>

Method 2: Iframe Embed

For complete control over the container and iframe styling:

Basic Iframe

<iframe
  id="timbercloud-embed"
  src="https://embed.timbercloud.com/your-company-slug"
  width="100%"
  height="800"
  style="border: none; border-radius: 8px;"
  title="Product Catalog"
  allow="payment"
></iframe>

Iframe with Integration Script (Recommended)

Add the integration script for password reset and SPA support:

<iframe
  id="timbercloud-embed"
  src="https://embed.timbercloud.com/your-company-slug"
  width="100%"
  height="800"
  style="border: none; border-radius: 8px;"
  title="Product Catalog"
  allow="payment"
></iframe>
 
<!-- Add this script AFTER the iframe -->
<script src="https://embed.timbercloud.com/timbercloud-integration.js"></script>

Note: The integration script only acts on TimberCloud iframes — it recognizes iframes whose src points at embed.timbercloud.com (or localhost during development) and ignores all other iframes on your page. It's safe to include alongside other embeds.

Full-Width Iframe Container

<div style="
  position: relative;
  left: 50%;
  right: 50%;
  margin-left: -50vw;
  margin-right: -50vw;
  width: 100vw;
  max-width: 100vw;
  overflow: hidden;
  padding-left: 16px;
  padding-right: 16px;
">
  <iframe
    id="timbercloud-embed"
    src="https://embed.timbercloud.com/your-company-slug"
    width="100%"
    height="1280"
    style="border: none; border-radius: 8px; display: block;"
    title="Product Catalog"
    allow="payment"
  ></iframe>
</div>
 
<script src="https://embed.timbercloud.com/timbercloud-integration.js"></script>

Iframe with Manual Return URL

For complete manual control:

<iframe
  id="timbercloud-embed"
  width="100%"
  height="800"
  style="border: none;"
  allow="payment"
></iframe>
 
<script>
  const currentPageUrl = window.location.href;
  const embedUrl = `https://embed.timbercloud.com/your-company-slug?timbercloud_return_url=${encodeURIComponent(currentPageUrl)}`;
  document.getElementById('timbercloud-embed').src = embedUrl;
</script>

Platform-Specific Instructions

WordPress

Option A: Script Embed (Recommended)

Edit your page in WordPress
Add a "Custom HTML" block
Paste the script embed code:

<div id="timbercloud-embed"></div>
<script
  src="https://embed.timbercloud.com/embed.js"
  data-company="your-company-slug"
  data-theme="light"
  data-width="100%"
  data-height="900px"
  defer
></script>

Update/Publish the page

Option B: Iframe Embed

Edit your page in WordPress
Add a "Custom HTML" block
Paste the iframe code with integration script
Update/Publish

Shopify

Go to Admin → Online Store → Pages
Create or edit a page
Click the HTML button (<>)
Paste your preferred embed code
Save the page

Wix

Add an "Embed HTML" element to your page
Click "Enter Code"
Paste the script embed code (recommended)
Resize as needed
Publish

Squarespace

Edit your page
Add a "Code" block
Paste the embed code
Click Apply
Save the page

React / Next.js

Script Embed in React:

import { useEffect } from 'react';
 
export function TimberCloudEmbed({ companySlug, theme = 'light', height = '800px' }) {
  useEffect(() => {
    // Load embed script
    const script = document.createElement('script');
    script.src = 'https://embed.timbercloud.com/embed.js';
    script.setAttribute('data-company', companySlug);
    script.setAttribute('data-theme', theme);
    script.setAttribute('data-width', '100%');
    script.setAttribute('data-height', height);
    script.defer = true;
    
    const container = document.getElementById('timbercloud-embed');
    if (container) {
      container.parentNode.insertBefore(script, container.nextSibling);
    }
    
    return () => {
      if (script.parentNode) {
        script.parentNode.removeChild(script);
      }
    };
  }, [companySlug, theme, height]);
 
  return <div id="timbercloud-embed" />;
}

Iframe Embed in React:

import { useEffect } from 'react';
 
export function TimberCloudEmbed({ companySlug }) {
  useEffect(() => {
    const script = document.createElement('script');
    script.src = 'https://embed.timbercloud.com/timbercloud-integration.js';
    script.async = true;
    document.body.appendChild(script);
    
    return () => {
      if (document.body.contains(script)) {
        document.body.removeChild(script);
      }
    };
  }, []);
 
  return (
    <iframe
      id="timbercloud-embed"
      src={`https://embed.timbercloud.com/${companySlug}`}
      width="100%"
      height="800"
      style={{ border: 'none', borderRadius: '8px' }}
      title="Product Catalog"
      allow="payment"
    />
  );
}

Container Styling Examples

Card Container

<div style="
  max-width: 1400px;
  margin: 0 auto;
  padding: 20px;
  background: white;
  border-radius: 16px;
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
">
  <div id="timbercloud-embed"></div>
</div>
 
<script
  src="https://embed.timbercloud.com/embed.js"
  data-company="your-company-slug"
  data-height="900px"
  defer
></script>

Responsive Height (CSS)

<style>
  #timbercloud-embed iframe,
  #timbercloud-iframe {
    height: 600px;
  }
  
  @media (min-width: 768px) {
    #timbercloud-embed iframe,
    #timbercloud-iframe {
      height: 800px;
    }
  }
  
  @media (min-width: 1024px) {
    #timbercloud-embed iframe,
    #timbercloud-iframe {
      height: 1000px;
    }
  }
</style>
 
<div id="timbercloud-embed"></div>
<script
  src="https://embed.timbercloud.com/embed.js"
  data-company="your-company-slug"
  defer
></script>

Full-Page Layout

<!DOCTYPE html>
<html>
<head>
  <title>Shop | Your Company</title>
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }
    body { font-family: system-ui, sans-serif; }
    header {
      background: #1a1a1a;
      color: white;
      padding: 16px 24px;
      display: flex;
      justify-content: space-between;
      align-items: center;
    }
    main {
      height: calc(100vh - 60px);
    }
    #timbercloud-embed {
      height: 100%;
    }
  </style>
</head>
<body>
  <header>
    <div>Your Company</div>
    <nav>
      <a href="/" style="color: white; margin-left: 24px;">Home</a>
      <a href="/about" style="color: white; margin-left: 24px;">About</a>
    </nav>
  </header>
  
  <main>
    <div id="timbercloud-embed"></div>
  </main>
 
  <script
    src="https://embed.timbercloud.com/embed.js"
    data-company="your-company-slug"
    data-height="100%"
    defer
  ></script>
</body>
</html>

URL Parameters

The embed supports these URL parameters:

Parameter	Description	Example
`timbercloud_return_url`	URL to return to after password reset	`?timbercloud_return_url=https://yoursite.com/shop`
`timbercloud_route`	Internal route to navigate to	`?timbercloud_route=/auth/login`
`code`	Token for password reset	Used automatically by password reset emails

For a deeper technical reference on these parameters and the iframe messaging, see the API Reference.

Security Requirements

HTTPS

Your website must use HTTPS for:

Payment processing (Stripe requires HTTPS)
Secure cookie handling
Browser security policies

Content Security Policy

If your site uses CSP headers, add these directives:

Content-Security-Policy: 
  frame-src https://embed.timbercloud.com https://js.stripe.com;
  script-src https://embed.timbercloud.com;

Cookie Settings

The embed uses cookies for:

User authentication (JWT tokens)
Cart persistence
Session management

Testing Checklist

✅ Embed loads and displays products
✅ Can add products to cart
✅ Can view cart sidebar
✅ Can navigate to product detail pages
✅ Can proceed to checkout
✅ Payment form loads (Stripe — paid plan required)
✅ Can create an account / log in
✅ Password reset emails work correctly

Troubleshooting

Embed not loading

Verify company slug is correct
Check browser console for errors
Ensure HTTPS is used
For Script Embed: ensure <div id="timbercloud-embed"> comes before the script

Payment form not appearing

Verify Stripe is configured in TimberCloud settings (and that you're on a paid plan — Free is inquiry-only)
Check that allow="payment" is on the iframe
Ensure HTTPS is active

Products not showing

Confirm products are published in your catalog
Check that products are assigned to the correct company

Storefront theme looks wrong (light vs. dark)

The storefront theme is not set by data-theme. Update your theme mode in your TimberCloud settings instead (see Customization).

Password reset not working

Use Script Embed or Iframe + integration script
Ensure URL parameters aren't stripped by your server
Check console for TimberCloud log messages

Performance Tips

Preconnect

Add to your <head> for faster loading:

<link rel="preconnect" href="https://embed.timbercloud.com">
<link rel="dns-prefetch" href="https://embed.timbercloud.com">

Lazy Loading (Iframe Only)

const observer = new IntersectionObserver((entries) => {
  if (entries[0].isIntersecting) {
    loadEmbed();
    observer.disconnect();
  }
});
 
observer.observe(document.querySelector('#embed-container'));
 
function loadEmbed() {
  const container = document.getElementById('embed-container');
  container.innerHTML = '<div id="timbercloud-embed"></div>';
  
  const script = document.createElement('script');
  script.src = 'https://embed.timbercloud.com/embed.js';
  script.setAttribute('data-company', 'your-company-slug');
  script.defer = true;
  container.appendChild(script);
}

Method Comparison

Feature	Script Embed	Iframe Only	Iframe + Integration Script
Setup complexity	⭐ Easiest	⭐⭐ Easy	⭐⭐ Easy
Auto iframe creation	✅	❌	❌
Password reset handling	✅	❌	✅
SPA support	✅	❌	✅
Dynamic resizing	✅	❌	❌
URL cleanup after reset	✅	❌	❌
Custom container styling	✅	✅ Full	✅ Full

Recommendation: Use Script Embed for most use cases.

Next Steps

Customization — Styling, theme, and brand color options
Storefront Features — Pagination, live carrier rates, order tracking, add-ons
API Reference — PostMessage communication
Your Website — Prefer a fully hosted site on your own domain instead of embedding? Use the Site Builder.

Embed Overview Customization