How to Integrate Ecwid with V0

Start by prompting V0 to build the page layout and UI components for your Ecwid store integration. The approach differs based on whether you are using the widget embed or the REST API approach. For the widget embed path: prompt V0 to generate the page layout with a specific placeholder container element. Give the container a clear ID (like 'ecwid-store' or 'my-store-widget') because the Ecwid widget script targets this element ID. Include a loading state in the placeholder since the widget takes 1-2 seconds to initialize. The surrounding layout — header, navigation, footer, and any marketing content above the store — should all be generated by V0. For the REST API path: prompt V0 to generate product card components, category navigation, filter panels, and the product grid layout. Tell V0 explicitly what data shape to expect from your API route so it generates the correct TypeScript interfaces and renders the data fields correctly. Ecwid's product objects have: id, name, price, thumbnailUrl, url, description, inStock, and category data. Providing this structure in your V0 prompt results in cleaner generated code. A common V0 limitation with e-commerce UIs is the 'Add to Cart' button behavior. V0 will generate the button and perhaps a cart icon in the header, but connecting the cart state across components requires either React context, a state management solution, or Ecwid's built-in cart handling. If you are using the Ecwid widget, the cart is managed entirely by Ecwid. If you are building a custom storefront with the REST API, cart management is a significant additional implementation task that V0 will scaffold but not fully wire together. Plan for this gap when estimating integration complexity.

Create the Next.js API route that fetches product data from Ecwid's REST API. Ecwid's REST API endpoint for products is https://app.ecwid.com/api/v3/{storeId}/products. Authentication uses the Secret Token as a Bearer token in the Authorization header. Ecwid's product listing endpoint supports a rich set of query parameters: offset and limit for pagination (default 100 products per page, maximum 100), sortBy for ordering (ADDED_TIME_DESC, PRICE_ASC, PRICE_DESC, etc.), keyword for search, and categoryId to filter by category. Pass these through from your API route's query parameters so the V0-generated frontend can control filtering and pagination. For a 'top integration for ecwid' query focus — the most valuable capability to expose is the category-aware product listing combined with pagination. Ecwid stores can have hundreds of products, and fetching all of them at once is both slow and expensive in terms of API quota. Implement offset-based pagination in your API route: accept offset and limit parameters from the client and pass them to Ecwid's API. Ecwid's product objects include an isShippingRequired field, a weight field, and variations (product options like sizes and colors) as nested arrays. For simple product listing pages, you only need the core fields. For product detail pages, fetch a single product by ID using GET https://app.ecwid.com/api/v3/{storeId}/products/{productId} which returns the full product object including description HTML, gallery images array, and all option combinations. Note that Ecwid's REST API returns product prices in the store's default currency. For international stores, the currency symbol and formatting are in the store profile endpoint (GET /api/v3/{storeId}/profile). Fetch this once on page load and cache it for the duration of the session.

1import { NextRequest, NextResponse } from 'next/server';
2
3const ECWID_STORE_ID = process.env.ECWID_STORE_ID!;
4const ECWID_SECRET_TOKEN = process.env.ECWID_SECRET_TOKEN!;
5const ECWID_BASE = `https://app.ecwid.com/api/v3/${ECWID_STORE_ID}`;
6
7export async function GET(request: NextRequest) {
8  try {
9    const { searchParams } = new URL(request.url);
10    const categoryId = searchParams.get('categoryId');
11    const offset = searchParams.get('offset') || '0';
12    const limit = searchParams.get('limit') || '20';
13    const sortBy = searchParams.get('sortBy') || 'ADDED_TIME_DESC';
14
15    const params = new URLSearchParams({
16      offset,
17      limit,
18      sortBy,
19      ...(categoryId && { categoryId }),
20    });
21
22    const response = await fetch(
23      `${ECWID_BASE}/products?${params}`,
24      {
25        headers: {
26          Authorization: `Bearer ${ECWID_SECRET_TOKEN}`,
27          'Content-Type': 'application/json',
28        },
29        next: { revalidate: 60 }, // Cache for 60 seconds
30      }
31    );
32
33    if (!response.ok) {
34      return NextResponse.json(
35        { error: `Ecwid API error: ${response.status}` },
36        { status: response.status }
37      );
38    }
39
40    const data = await response.json();
41
42    // Shape the response to only what the UI needs
43    const products = data.items?.map((p: Record<string, unknown>) => ({
44      id: p.id,
45      name: p.name,
46      price: p.price,
47      compareToPrice: p.compareToPrice,
48      thumbnailUrl: p.thumbnailUrl,
49      url: p.url,
50      inStock: p.inStock,
51      description: p.description,
52    })) || [];
53
54    return NextResponse.json({
55      products,
56      total: data.total,
57      offset: data.offset,
58      limit: data.limit,
59    });
60  } catch (error) {
61    console.error('Ecwid products error:', error);
62    return NextResponse.json(
63      { error: 'Failed to fetch products' },
64      { status: 500 }
65    );
66  }
67}

Your API route needs two Ecwid credentials: the Store ID and the Secret Token. Add these to Vercel's environment configuration. Go to Vercel Dashboard → your project → Settings → Environment Variables and add: ECWID_STORE_ID: Your numeric Ecwid store ID. Find it in Ecwid Control Panel → Settings → General → Store Profile. It is also visible in your browser's URL when viewing your control panel, and in the widget JavaScript snippet Ecwid provides. This is technically a public identifier (it appears in widget script URLs), but there is no benefit to exposing it client-side, so keep it server-side. ECWID_SECRET_TOKEN: The legacy API key / secret token from Ecwid Control Panel → Apps → Legacy API Keys → Generate Tokens. This provides full API access including write operations. Do NOT add NEXT_PUBLIC_ prefix. Store it as a server-only environment variable. For the widget embed approach, you will also want NEXT_PUBLIC_ECWID_STORE_ID with the same Store ID value. The Ecwid widget script URL includes the Store ID directly: https://app.ecwid.com/script.js?{storeId}. Since this is a public URL pattern and the Store ID appears in your page HTML anyway, NEXT_PUBLIC_ is appropriate here for the widget approach only. After saving all variables, trigger a new Vercel deployment. Check the Vercel function logs (Vercel Dashboard → Functions → View Function Logs) after making a request to /api/ecwid/products to confirm the API route is fetching data successfully.

1# .env.local — local development
2ECWID_STORE_ID=12345678
3ECWID_SECRET_TOKEN=your_secret_token_here
4# For widget embed (client-side use is safe for Store ID only)
5NEXT_PUBLIC_ECWID_STORE_ID=12345678

If you prefer the plug-and-play widget approach over building a custom storefront, embed Ecwid's JavaScript widget in your Next.js page. The widget loads Ecwid's full store interface including product listings, cart, and checkout directly in your page with no API routes needed. Create a client component that loads the Ecwid script and initializes the store widget on a specific container element. The Ecwid widget requires a global JavaScript snippet and a div with a specific ID that it will render into. In Next.js App Router, this must be a client component with 'use client' because it manipulates the DOM after mount. Ecwid's standard embed consists of two parts: a configuration object (window.ec.config) that sets the store ID and widget mode, and the JavaScript snippet that loads the Ecwid storefront assets. The configuration must be set before the script loads. For Next.js App Router, use a useEffect where you set the config and then append the script tag. The Ecwid widget renders the full Ecwid storefront at the container element, including navigation, category pages, product pages, cart, and checkout. It handles its own internal routing using hash-based navigation by default. This means users navigating within the store do not cause full Next.js route changes — the Next.js router is not involved in Ecwid's internal product and category pages. A V0-specific caveat: V0 may generate the Ecwid widget as a server component using next/script, which will not work correctly for the initialization pattern. Ensure the component is a client component with 'use client'. Also, if V0 generates the widget script loading in a way that conflicts with React's rendering lifecycle (for example, appending the script in the render function instead of useEffect), the store may initialize multiple times or fail to render.

1'use client';
2
3import { useEffect } from 'react';
4
5declare global {
6  interface Window {
7    ec?: {
8      config?: Record<string, unknown>;
9      storefront?: Record<string, unknown>;
10    };
11    ecwid_script_defer?: boolean;
12    ecwid_dynamic_widgets?: boolean;
13  }
14}
15
16export function EcwidStore() {
17  const storeId = process.env.NEXT_PUBLIC_ECWID_STORE_ID;
18
19  useEffect(() => {
20    if (!storeId) {
21      console.warn('EcwidStore: NEXT_PUBLIC_ECWID_STORE_ID is not set');
22      return;
23    }
24
25    const scriptId = `ecwid-script-${storeId}`;
26    if (document.getElementById(scriptId)) return;
27
28    // Configure Ecwid
29    window.ec = window.ec || {};
30    window.ec.config = window.ec.config || {};
31    window.ecwid_script_defer = true;
32    window.ecwid_dynamic_widgets = true;
33
34    const script = document.createElement('script');
35    script.id = scriptId;
36    script.src = `https://app.ecwid.com/script.js?${storeId}`;
37    script.async = true;
38    document.body.appendChild(script);
39  }, [storeId]);
40
41  return (
42    <div
43      id={`my-store-${storeId}`}
44      className="w-full min-h-[600px]"
45    />
46  );
47}