How to Integrate Bolt.new with Ecwid (Lightspeed E-Series)

Log in to your Ecwid account at ecwid.com and open your merchant dashboard. Your Store ID is the most important identifier — it is a numeric string visible in the browser URL bar when you're in the dashboard (e.g., app.ecwid.com/cp/#/overview/12345678, where 12345678 is your store ID) and in your embed code. For the REST API, you need a secret key. Go to your Ecwid dashboard → Apps (left sidebar) → All Applications → scroll down to 'Legacy API keys' or find it under the developer section. Click 'Legacy API keys' to see your store's public and secret keys. The secret key is used for server-side API calls; the public key is not needed for most operations. Note your Store ID and Secret Key. Add them to your .env file: NEXT_PUBLIC_ECWID_STORE_ID (safe to expose client-side — it's in the public embed script URL anyway) and ECWID_SECRET_KEY (server-side only — grants full read/write access to your store's orders, customers, and products). Ecwid's API base URL follows this pattern: https://app.ecwid.com/api/v3/{storeId}/. All API calls append your store ID to this base URL and require a Bearer token with your Secret Key in the Authorization header. The REST API uses HTTPS exclusively — compatible with Bolt's WebContainer.

1// src/lib/ecwid.ts
2const STORE_ID = process.env.NEXT_PUBLIC_ECWID_STORE_ID;
3const BASE_URL = `https://app.ecwid.com/api/v3/${STORE_ID}`;
4
5export async function ecwidFetch<T>(
6  path: string,
7  options: RequestInit = {}
8): Promise<T> {
9  const secretKey = process.env.ECWID_SECRET_KEY;
10  if (!secretKey) throw new Error('ECWID_SECRET_KEY is not set');
11
12  const response = await fetch(`${BASE_URL}/${path}`, {
13    ...options,
14    headers: {
15      Authorization: `Bearer ${secretKey}`,
16      'Content-Type': 'application/json',
17      ...options.headers,
18    },
19  });
20
21  if (!response.ok) {
22    throw new Error(`Ecwid API error ${response.status}: ${await response.text()}`);
23  }
24
25  return response.json();
26}
27
28export const ECWID_STORE_ID = STORE_ID;

The embed approach adds a fully working store to your Bolt.new app with minimal code. Ecwid's script tag loads their storefront JavaScript, which mounts a complete shopping experience inside the target div. In React, you cannot add script tags directly to JSX — use useEffect to inject the script programmatically after the component mounts. The embed code consists of two elements: a script tag that loads Ecwid's storefront script from app.ecwid.com/script.js with your store ID as a query parameter, and a div with id='my-store-{storeId}' that Ecwid targets for rendering. The script tag must be added to the DOM (not the Next.js script component) and must load after the target div exists in the DOM. Customize the storefront appearance using the window.ec.config object, which you can set before the script loads. Options include defaultCategoryId (which category to show first), scrollToCurrentPage (prevent page scrolls), and view (list or grid). CSS customization is limited to overriding Ecwid's class names — the widget renders its own HTML with stable class names that you can target. The Ecwid widget works in Bolt's WebContainer preview immediately after you add the code — no deployment needed to see the live store. Customers can browse products and add to cart in the preview. Checkout will redirect to Ecwid's hosted payment page.

1// app/shop/page.tsx
2'use client';
3import { useEffect } from 'react';
4
5export default function ShopPage() {
6  const storeId = process.env.NEXT_PUBLIC_ECWID_STORE_ID;
7
8  useEffect(() => {
9    if (!storeId) return;
10
11    // Configure Ecwid before loading script
12    (window as any).ec = (window as any).ec || {};
13    (window as any).ec.config = {
14      baseUrl: '/shop',
15      storefrontUrls: { cleanUrls: true },
16    };
17
18    const script = document.createElement('script');
19    script.src = `https://app.ecwid.com/script.js?${storeId}&data_platform=code`;
20    script.defer = true;
21    script.id = 'ecwid-script';
22    document.body.appendChild(script);
23
24    return () => {
25      // Clean up on unmount
26      const existingScript = document.getElementById('ecwid-script');
27      if (existingScript) document.body.removeChild(existingScript);
28      delete (window as any).ecwid_onBodyDone;
29    };
30  }, [storeId]);
31
32  return (
33    <div className="max-w-6xl mx-auto px-4 py-8">
34      <h1 className="text-3xl font-bold mb-8">Our Store</h1>
35      <div id={`my-store-${storeId}`} className="min-h-96" />
36    </div>
37  );
38}

For more design control, use Ecwid's REST API to fetch product data and render products using your own React components. This approach lets you design the product grid, product cards, and filtering UI exactly as you want, while Ecwid handles inventory, pricing, and checkout. The Ecwid products endpoint is /products and returns a paginated list of products with id, name, price, description, thumbnailUrl, imageUrl, quantity (inventory), and url (the direct Ecwid product page URL for checkout). Filter by category with ?category={id}, search with ?keyword={term}, and paginate with ?limit=20&offset=0. For checkout, you have two options: link to Ecwid's product page URL (simplest — uses Ecwid's full checkout) or use the Ecwid JS API (window.Ecwid.openPage()) to open specific products in the embedded widget. For a custom storefront with Ecwid as the backend, linking to Ecwid's product URL is the most reliable checkout path. Cache product data in your app — Ecwid's free plan has API rate limits (API calls are limited, though the specific numbers are not publicly documented). Fetching on every page load is inefficient; cache for 5-15 minutes using Next.js's built-in fetch cache or a simple in-memory map.

1// app/api/ecwid/products/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { ecwidFetch } from '@/lib/ecwid';
4
5interface EcwidProduct {
6  id: number;
7  name: string;
8  price: number;
9  compareToPrice?: number;
10  thumbnailUrl: string;
11  quantity: number;
12  unlimited: boolean;
13  url: string;
14  shortDescription: string;
15  enabled: boolean;
16}
17
18interface EcwidProductsResponse {
19  items: EcwidProduct[];
20  total: number;
21  count: number;
22  offset: number;
23  limit: number;
24}
25
26export async function GET(request: NextRequest) {
27  const params = request.nextUrl.searchParams;
28  const query = new URLSearchParams({
29    limit: params.get('limit') ?? '20',
30    offset: params.get('offset') ?? '0',
31    enabled: 'true',
32    ...(params.get('category') && { category: params.get('category')! }),
33    ...(params.get('keyword') && { keyword: params.get('keyword')! }),
34  });
35
36  try {
37    const data = await ecwidFetch<EcwidProductsResponse>(
38      `products?${query}`,
39      { next: { revalidate: 300 } } as any // 5 minute cache
40    );
41
42    const products = data.items
43      .filter(p => p.enabled)
44      .map(p => ({
45        id: p.id,
46        name: p.name,
47        price: p.price,
48        compareToPrice: p.compareToPrice ?? null,
49        thumbnail: p.thumbnailUrl,
50        inStock: p.unlimited || p.quantity > 0,
51        url: p.url,
52        description: p.shortDescription?.slice(0, 100) ?? '',
53      }));
54
55    return NextResponse.json({ products, total: data.total });
56  } catch (err: any) {
57    return NextResponse.json({ error: err.message }, { status: 500 });
58  }
59}

Customize the Ecwid embed appearance and behavior before deploying. Ecwid's JavaScript API exposes configuration options via window.ec.config before the script loads, and event hooks via window.Ecwid.OnAPILoaded for post-load customization. For CSS customization, Ecwid's widget elements have stable class names prefixed with ec- that you can override in your global CSS. Common customizations include matching the store font to your app's typography, adjusting button colors to match your brand, and hiding Ecwid's default breadcrumbs if you have your own navigation. Keep CSS overrides minimal — Ecwid updates their widget CSS periodically and overrides can break. For the Ecwid widget specifically, no webhook setup is required for read-only storefront functionality. You do not need a deployed URL to test product browsing and add-to-cart in the Bolt preview. However, if you want to receive order notifications in your app (via Ecwid webhooks that POST to your server when orders are placed), you will need a deployed URL — Bolt's WebContainer cannot receive incoming HTTP connections. Configure order webhooks in your Ecwid dashboard under Settings → Notifications → Webhooks after deploying. To deploy: publish to Netlify or Bolt Cloud, set NEXT_PUBLIC_ECWID_STORE_ID and ECWID_SECRET_KEY as environment variables in your hosting dashboard, and trigger a new deployment. The Ecwid widget loads from Ecwid's CDN and requires no Ecwid-specific deployment configuration.

1/* app/globals.css — Ecwid widget customization */
2
3/* Match app typography */
4.ecwid,
5.ec-storefront {
6  font-family: inherit !important;
7}
8
9/* Brand primary button color */
10.ec-cart__checkout-button,
11.ec-storefront .form-control__button--primary {
12  background-color: #2563eb !important;
13  border-color: #2563eb !important;
14}
15
16.ec-cart__checkout-button:hover,
17.ec-storefront .form-control__button--primary:hover {
18  background-color: #1d4ed8 !important;
19}
20
21/* Hide Ecwid footer on free plan */
22.ec-footer {
23  display: none !important;
24}
25
26/* Responsive grid on mobile */
27@media (max-width: 640px) {
28  .grid-list .grid-list__list-inner {
29    grid-template-columns: 1fr !important;
30  }
31}