Embeddable Storefront
API Reference

API Reference

Technical documentation for the TimberCloud Embeddable Storefront, including embed script options and URL parameters.

Embed Script (embed.js)

The embed script provides the simplest integration method, automatically creating and configuring the iframe.

Usage

<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>

Attributes

AttributeRequiredDefaultDescription
data-companyYes—Your TimberCloud company slug
data-themeNolightTheme: light or dark
data-widthNo100%Width of the embed (CSS value)
data-heightNo800pxHeight of the embed (CSS value)

What It Does

The embed.js script automatically:

  1. Creates the iframe inside the #timbercloud-embed container
  2. Sets the return URL to the current page (for password reset)
  3. Handles password reset routing when users click email links
  4. Listens for URL changes (popstate) for SPA support
  5. Handles resize messages from the embed
  6. Cleans URL parameters after password reset completion

Integration Script (timbercloud-integration.js)

For iframe-based integrations, the integration script provides automatic functionality.

Usage

<iframe
  id="timbercloud-embed"
  src="https://embed.timbercloud.com/your-company-slug"
  width="100%"
  height="800"
  style="border: none;"
  allow="payment"
></iframe>
 
<script src="https://embed.timbercloud.com/timbercloud-integration.js"></script>

What It Does

The integration script automatically:

  1. Detects TimberCloud iframes on the page
  2. Appends the return URL to iframe src if not present
  3. Handles password reset routing from email links
  4. Observes DOM changes for dynamically added iframes

Triggering Re-initialization (SPAs)

For single-page applications, trigger re-initialization after navigation:

window.dispatchEvent(new Event('timbercloud:reinit'));

The script also listens to popstate events automatically.

URL Parameters

The embed accepts the following URL parameters:

timbercloud_return_url

Specifies the URL to return to after actions like password reset.

<iframe
  src="https://embed.timbercloud.com/your-company-slug?timbercloud_return_url=https://yoursite.com/shop"
  ...
></iframe>

Manual usage:

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;

timbercloud_route

Navigates to a specific internal route within the embed.

<!-- Open directly to login page -->
<iframe
  src="https://embed.timbercloud.com/your-company-slug?timbercloud_route=/auth/login"
  ...
></iframe>

Available routes:

RouteDescription
/Product catalog (home)
/auth/loginLogin page
/auth/registerRegistration page
/auth/forgot-passwordPassword reset request
/auth/reset-passwordPassword reset form (requires code)
/checkoutCheckout page
/ordersOrder history
/orders/[id]Specific order details
/accountAccount settings
/product/[id]Product detail page

code

Used for password reset tokens. Automatically included in password reset email links.

Complete Examples

Example 1: Script Embed (Recommended)

<!DOCTYPE html>
<html>
<head>
  <title>Shop | Your Site</title>
  <link rel="preconnect" href="https://embed.timbercloud.com">
</head>
<body>
  <h1>Our Store</h1>
  
  <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>
</body>
</html>

Example 2: Iframe with Integration Script

<!DOCTYPE html>
<html>
<head>
  <title>Shop | Your Site</title>
  <link rel="preconnect" href="https://embed.timbercloud.com">
</head>
<body>
  <h1>Our Store</h1>
  
  <div style="
    position: relative;
    left: 50%;
    right: 50%;
    margin-left: -50vw;
    margin-right: -50vw;
    width: 100vw;
    max-width: 100vw;
    overflow: hidden;
    padding: 0 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>
</body>
</html>

Example 3: React Component

import { useEffect, useRef } from 'react';
 
export function TimberCloudEmbed({ 
  companySlug, 
  theme = 'light', 
  height = '800px' 
}) {
  const containerRef = useRef(null);
 
  useEffect(() => {
    const container = containerRef.current;
    if (!container) return;
 
    // Create placeholder div
    const embedDiv = document.createElement('div');
    embedDiv.id = 'timbercloud-embed';
    container.appendChild(embedDiv);
 
    // 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;
    container.appendChild(script);
 
    return () => {
      container.innerHTML = '';
    };
  }, [companySlug, theme, height]);
 
  return <div ref={containerRef} />;
}
 
// Usage
<TimberCloudEmbed 
  companySlug="your-company-slug" 
  theme="light" 
  height="900px" 
/>

Security Considerations

HTTPS Required

All communication occurs over HTTPS. The embed will not function properly on HTTP sites.

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;

Troubleshooting

Embed not loading

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

Password reset not working

  • Use Script Embed or Iframe + integration script
  • Ensure URL parameters aren't stripped by your server

Script Embed: Container not found

  • The <div id="timbercloud-embed"> must be the immediate previous sibling of the script
  • Ensure the div exists before the script runs (use defer attribute)
CustomizationCreate a Product