Wix Ecommerce

Wix eCommerce App and Extension Development

Overview

Wix provides a cloud-based website building platform with integrated eCommerce capabilities. Unlike traditional open-source platforms (WooCommerce, Magento), Wix is a fully managed SaaS environment. Developers extend Wix through three primary channels: Velo by Wix (site-level JavaScript customization), Wix CLI apps (standalone applications distributed through the Wix App Market), and Wix Blocks (reusable widget components). All development happens within Wix's sandboxed runtime -- there is no direct server access, no SSH, and no arbitrary backend deployment.

The Wix eCommerce ecosystem exposes APIs for products, orders, carts, checkout, payments, and catalog management. These APIs are available both as Velo backend modules (for site-level code) and as REST/SDK endpoints (for external CLI apps). The extension model differs fundamentally from plugin-based platforms: instead of hooking into server-side lifecycle events, developers register event handlers, build dashboard pages, and inject widgets into predefined extension points.

App Types

Velo Site Extensions

Velo by Wix (formerly Corvid) enables JavaScript development directly within a Wix site. Developers write frontend and backend code in the Wix Editor or IDE, with access to Wix APIs, HTTP functions, and scheduled jobs. Velo code runs within the Wix runtime and is scoped to a single site. It is not distributable through the App Market.

Use Velo for site-specific customizations: custom checkout flows, dynamic pages driven by database collections, backend HTTP endpoints, scheduled data syncs, and custom business logic triggered by eCommerce events.

Wix CLI Apps

Wix CLI apps are standalone applications built outside the Wix Editor using the @wix/cli toolchain. These apps can be published to the Wix App Market for distribution to all Wix users. CLI apps consist of dashboard pages (React components rendered inside the Wix site dashboard), site widgets (embedded in the live site), and backend extensions (event handlers, webhooks).

CLI apps authenticate via OAuth 2.0 and interact with Wix APIs through the @wix/sdk package. They run on the developer's infrastructure or as serverless functions, communicating with Wix through REST APIs.

Wix Blocks

Wix Blocks is a visual development environment for building reusable widgets and components that can be installed on any Wix site. Blocks combine a visual design canvas with Velo-powered logic, producing distributable components. Blocks are suitable for building embeddable UI elements (price calculators, product configurators, review widgets) without requiring a full CLI app.

Development

Wix CLI Setup

Initialize a new Wix app project using the CLI:

1. Install the CLI: npm install -g @wix/cli
2. Create a new app: wix create
3. Select the app template (dashboard, widget, or full app)
4. Start local development: wix dev

The wix dev command starts a local development server with hot reload, creates a tunnel to the Wix platform, and installs a development version of the app on the target site.

Dashboard Pages

Dashboard pages are React components that render inside the Wix site owner's dashboard. Define dashboard pages in the app manifest and implement them using React with the @wix/dashboard-sdk for context (site ID, user info, instance data). Dashboard pages have full access to Wix APIs through the SDK and can display data tables, forms, charts, and configuration panels.

Site Widgets

Site widgets are React components embedded in the live storefront. Declare widget extension points in the app manifest and implement them as React components. Widgets receive configuration from the Wix Editor's settings panel and render within the site's layout. Use the @wix/widget-sdk for widget lifecycle hooks and editor integration.

Backend Extensions

Register backend event handlers for eCommerce lifecycle events (order placed, payment received, cart updated). Backend extensions run as serverless functions triggered by Wix platform events. Define event handlers in the app's service plugin configuration and implement the handler logic in TypeScript/JavaScript.

Wix eCommerce APIs

Wix exposes a comprehensive set of eCommerce APIs accessible through Velo backend modules (wix-ecom-backend) and the REST SDK (@wix/ecom).

Products and Catalog

Query, create, update, and delete products and collections. Manage product variants, options, media, pricing, and inventory. Support for physical and digital product types. The Catalog API supports filtering, sorting, and pagination for product queries.

Orders

Create, query, and update orders. Access order line items, shipping details, payment information, and fulfillment status. Listen for order events (created, paid, fulfilled, canceled) through backend event handlers.

Cart and Checkout

Manipulate the shopping cart programmatically -- add items, remove items, apply coupons, set custom fields. Control the checkout flow by adding custom validation, modifying totals, and injecting additional steps. The Checkout API supports redirect-based and embedded checkout experiences.

Payments

Integrate custom payment providers through the Wix Payments SPI (Service Provider Interface). Implement the payment provider contract to support charge, refund, and transaction status queries. Wix handles PCI compliance for hosted payment fields.

For complete API documentation, backend module reference, and code examples, see references/velo-and-apis.md.

Limitations

Wix's managed environment imposes constraints that differ significantly from self-hosted platforms:

• No direct database access. Data storage is limited to Wix Data collections (NoSQL-like) with query limitations. No SQL, no joins, no raw database access.
• Sandboxed JavaScript runtime. Velo backend code runs in a restricted Node.js-like environment. Many npm packages are unavailable or unsupported. No filesystem access, no child processes, no native modules.
• API rate limits. Wix APIs enforce per-site and per-app rate limits. Heavy operations (bulk imports, catalog syncs) must implement throttling and pagination.
• No server-side rendering control. Site rendering is managed by the Wix platform. Developers cannot control SSR behavior, caching headers, or CDN configuration.
• App Market review process. Public apps undergo a review process that evaluates functionality, security, UX quality, and compliance with Wix guidelines.

For a detailed breakdown of runtime restrictions, storage limits, and API quotas, see references/limitations.md.

Anti-Patterns

• Using Velo for distributable apps -- Velo code is site-scoped and cannot be packaged for distribution. Use the CLI app framework for apps intended for the App Market.
• Ignoring rate limits on bulk operations -- Batch product imports or order syncs without throttling will hit rate limits and cause partial failures. Implement paging and delays.
• Storing sensitive data in Wix Data collections -- Wix Data collections are not encrypted at the field level. Store API keys and secrets in the Wix Secrets Manager, not in database collections.
• Building complex UIs without Blocks -- Attempting to build reusable UI components purely through Velo custom elements leads to fragile, non-portable code. Use Wix Blocks for distributable widgets.
• Polling instead of using event handlers -- Wix provides backend event handlers for eCommerce events. Polling APIs for state changes wastes rate limit budget and increases latency.

Reference Files

• Velo and APIs -- Velo runtime, eCommerce backend APIs, Wix Data collections, HTTP functions, webhooks, dashboard widgets, custom app pages
• App Market -- Wix App Market submission, Wix Developers Center, app types, review process, pricing models, OAuth integration
• Limitations -- Velo sandbox restrictions, API rate limits, data storage limits, rendering constraints, restricted npm packages