Ecwid

Ecwid (Lightspeed eCom) App Development

Overview

Ecwid (now part of Lightspeed eCom) is an embeddable e-commerce widget that merchants add to any existing website -- WordPress, Wix, Squarespace, static HTML, or a fully custom site. Unlike self-hosted platforms, Ecwid runs as a JavaScript widget injected into a host page, rendering its entire storefront (product catalog, cart, checkout) inside a <div> container. This architecture means the storefront is a single-page application (SPA) where all product browsing, cart interactions, and checkout happen without full page reloads.

Ecwid provides an app ecosystem through the Ecwid App Market. Third-party developers build apps that extend storefront behavior, add admin panel functionality, integrate payment and shipping providers, or connect external services. Apps interact with Ecwid through two primary channels: the JavaScript SDK for client-side storefront customization and the REST API for server-side data access and manipulation.

Ecwid stores are identified by a numeric store ID. Each store operates independently with its own products, orders, customers, and settings. Apps authenticate via OAuth 2.0 and receive access tokens scoped to individual stores.

App Types

Ecwid supports several app categories, each targeting a different integration surface:

Storefront Apps (JavaScript-Based)

Storefront apps run directly in the merchant's storefront widget. They use the Ecwid JavaScript SDK to listen for page events, modify product pages, inject custom UI elements, manipulate the cart, and alter checkout behavior. Storefront apps load as external JavaScript files that Ecwid injects into the storefront when the merchant installs the app. No iframe isolation exists for storefront apps -- they share the DOM with the Ecwid widget.

Native Apps (Iframe-Based)

Native apps appear as pages inside the Ecwid Control Panel (admin dashboard). They load in an iframe and communicate with the Control Panel through the Ecwid App SDK. Native apps provide configuration interfaces, dashboards, reporting tools, or content management features. The iframe receives store credentials and access tokens through initialization parameters.

Payment Integrations

Payment apps add custom payment methods to the Ecwid checkout. They implement a server-side payment flow where Ecwid sends order details to the app's payment endpoint, the app redirects the customer to the payment gateway, and the app notifies Ecwid of the payment result. Payment apps register through the Ecwid API and appear as checkout options.

Shipping Integrations

Shipping apps provide real-time shipping rate calculations during checkout. Ecwid sends the cart contents and shipping address to the app's endpoint, and the app returns available shipping methods with rates. Shipping apps support dimensional weight, zone-based pricing, and carrier API lookups.

For full JavaScript SDK event handling, cart manipulation, and storefront customization patterns, see references/javascript-sdk.md.

JavaScript SDK

The Ecwid JavaScript SDK is the primary tool for storefront customization. It exposes a global Ecwid object on the host page with methods for page event handling, cart operations, and storefront configuration.

Page Events

The storefront is an SPA, so standard DOM events like DOMContentLoaded do not fire on page transitions. Use Ecwid's page event system instead:

• Ecwid.OnPageLoaded.add(callback) -- Fire after a storefront page fully renders. The callback receives a page object with the page type (CATEGORY, PRODUCT, CART, CHECKOUT, etc.) and contextual IDs.
• Ecwid.OnPageSwitch.add(callback) -- Fire when navigation begins, before the new page renders. Use for cleanup or transition animations.

Cart Manipulation

The Ecwid.Cart namespace provides methods for reading and modifying the shopping cart:

• Ecwid.Cart.addProduct(product) -- Add an item to the cart programmatically. The product object requires id and quantity; options can specify product variations.
• Ecwid.Cart.get(callback) -- Retrieve the full cart contents asynchronously. The callback receives a cart object with items, subtotal, and item count.
• Ecwid.Cart.clear() -- Remove all items from the cart.

Storefront Customization

Inject custom CSS through the Ecwid Control Panel or dynamically through JavaScript. Modify product page layouts by listening for PRODUCT page loads and manipulating the DOM after render. Add custom fields to checkout by registering additional input elements through the Ecwid API.

For the complete JavaScript SDK reference including all events, cart methods, and DOM manipulation patterns, see references/javascript-sdk.md.

REST API

The Ecwid REST API provides server-side access to store data. All endpoints use https://app.ecwid.com/api/v3/{storeId}/ as the base URL, authenticated with an access token in the Authorization: Bearer {token} header.

Key Resources

• Products -- Full CRUD operations on products, variations, images, and inventory. Filter by keyword, category, creation date, price range, or custom attributes. Supports batch updates for bulk operations.
• Orders -- Retrieve, create, update, and delete orders. Filter by status, date range, customer, payment method, or fulfillment status. Access order items, shipping details, and payment information.
• Customers -- Manage customer accounts, addresses, and order history. Search by name, email, or customer group.
• Categories -- Organize products into hierarchical categories. CRUD operations on category names, descriptions, images, and product assignments.
• Discount Coupons -- Create and manage discount codes with percentage, absolute, or free shipping discount types. Set usage limits, expiration dates, and minimum order amounts.

Authentication

Apps authenticate using OAuth 2.0. The flow starts when a merchant installs the app from the App Market. Ecwid redirects to the app's redirect URL with an authorization code. The app exchanges this code for a permanent access token scoped to that store. Access tokens do not expire but can be revoked by the merchant.

Webhooks

Register webhook URLs to receive real-time notifications when orders are placed, products are updated, inventory changes, or other store events occur. Webhooks send a POST request with event type and entity ID -- the app then calls the REST API to fetch full details.

For comprehensive REST API endpoint documentation, authentication flow, rate limiting, and webhook setup, see references/rest-api.md.

Development Setup

Developer Account

1. Create an Ecwid developer account at the Ecwid Partner Portal.
2. Register a new application to receive a client ID and client secret.
3. Configure the app's OAuth redirect URL, iframe URL (for native apps), and storefront JavaScript URL (for storefront apps).
4. Request necessary API access scopes (read/write products, orders, customers, etc.).

Sandbox Store

Create a free Ecwid Venture plan store for testing. This provides a fully functional store with product catalog, checkout, and order processing without payment charges. Use the sandbox store to install and test the app during development.

Local Development

For storefront apps, serve the JavaScript file from a local HTTPS server (Ecwid requires HTTPS). Use tools like ngrok or localtunnel to expose the local server. Point the app's storefront JavaScript URL to the tunnel URL during development.

For native apps, serve the iframe page locally and point the app's iframe URL to the tunnel URL. The Ecwid Control Panel loads the iframe with authentication parameters that the app can use to initialize.

Anti-Patterns

• Polling the REST API for changes -- Use webhooks to receive real-time notifications instead of repeatedly querying the API. Polling wastes rate limit budget and creates unnecessary latency.
• Modifying the DOM before Ecwid renders -- Always wait for Ecwid.OnPageLoaded before manipulating storefront DOM elements. The SPA architecture means DOM elements may not exist until after asynchronous rendering completes.
• Ignoring the SPA lifecycle -- Standard page-load events do not fire on internal navigation. Bind to Ecwid page events rather than window.onload or DOMContentLoaded.
• Storing access tokens client-side -- OAuth access tokens grant full API access. Store them server-side only. Never expose tokens in storefront JavaScript.
• Hardcoding store IDs -- Build apps to work with any store by extracting the store ID from the OAuth flow or initialization parameters.

Reference Files

• JavaScript SDK -- Page events, cart manipulation, storefront customization, public config, widget embedding
• REST API -- Endpoints, OAuth authentication, webhooks, rate limiting, batch operations, filtering, pagination
• App Market -- App Market submission, iframe integration, native app panel, review process, developer partner program