API Reference

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

Note: This page covers the technical reference for embedding. If you just want to get the storefront on your site, start with Embed Setup. For brand colors, theme, and layout, see Customization. For the customer-facing shopping experience, see Storefront Features. If you don't already have a website, a hosted white-label website (on your own custom domain) is an alternative to embedding.

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

Important: data-theme is not consumed by the storefront UI. The script sets it as an attribute on the iframe element, but the storefront's light/dark appearance is controlled by your TimberCloud theme setting (site_theme_mode), and brand colors by your primary/secondary color settings — not by embed code. See Customization for how to set the storefront theme and colors.

What It Does

The embed.js script automatically:

1. Creates the iframe inside the #timbercloud-embed container (the <div> must be the immediate previous sibling of the script).
2. Sets the return URL to the current page (used so customers land back on your page after actions like password reset).
3. Handles password-reset routing when a customer clicks a link from a TimberCloud email (via the timbercloud_route and code parameters — see URL Parameters).
4. Listens for popstate so the embed stays in sync during browser back/forward navigation (helpful for single-page apps).
5. Auto-resizes the iframe when the storefront sends a timbercloud:resize message.
6. Cleans URL parameters (timbercloud_route, code) from your page's address bar after a password reset completes.

Integration Script (timbercloud-integration.js)

For iframe-based integrations, the integration script adds the same automatic routing behavior without using the script-tag embed.

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. It only acts on iframes whose src points at embed.timbercloud.com (or localhost:3002 in local development). Iframes for any other host are ignored.
2. Appends a return URL to the iframe src if one isn't already present, so customers return to your page after actions like password reset.
3. Sanitizes sensitive query parameters out of that return URL before setting it. Parameters such as code, token, reset_code, auth, auth_token, access_token, refresh_token, otp, and verification_code are stripped first, so secrets from your page's URL are never forwarded into the embed.
4. Handles password-reset routing from email links (forwarding timbercloud_route and code to the iframe).
5. Observes DOM changes so dynamically added iframes (or iframes whose src is updated) are picked up automatically.

Note: Use either embed.js or the iframe + timbercloud-integration.js approach — not both. The script-tag embed already includes its own routing logic.

Triggering Re-initialization (SPAs)

For single-page applications, trigger re-initialization after a client-side navigation so newly mounted iframes are processed:

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

The script also listens to popstate events automatically.

URL Parameters

The embed accepts the following URL parameters on the storefront URL (https://embed.timbercloud.com/your-company-slug):

timbercloud_return_url

Specifies the URL to return to after actions like password reset. The integration script sets this for you (with sensitive parameters removed); you can also set it manually.

<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 the login page -->
<iframe
  src="https://embed.timbercloud.com/your-company-slug?timbercloud_route=/auth/login"
  ...
></iframe>

Available routes:

Note: Routes ending in [id] are dynamic — substitute a real product or order ID. Most customers reach these screens by navigating inside the storefront; timbercloud_route is mainly used for deep-linking and email-driven flows.

code

Used for password-reset tokens. Automatically included in password-reset email links and forwarded to the embed alongside timbercloud_route.

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.

Sensitive parameters are stripped

The integration script removes sensitive query parameters (code, token, reset_code, auth, auth_token, access_token, refresh_token, otp, verification_code) from the return URL before passing it to the embed, so secrets in your page's address bar aren't forwarded.

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

Storefront theme isn't changing

• data-theme does not control the storefront's appearance. Set the storefront theme and brand colors in your TimberCloud settings instead — see Customization.

Password reset not working

• Use the Script Embed, or the iframe + integration script.
• Ensure URL parameters aren't stripped by your server or proxy.

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 the defer attribute).

Integration script isn't acting on my iframe

• The integration script only processes iframes whose src points at embed.timbercloud.com (or localhost:3002 in development). Confirm your iframe src uses the embed.timbercloud.com host.