Migrating from Vendure to Swell - A Complete Guide

For merchants running Vendure's open-source TypeScript framework, the promise of complete code-level control often comes with hidden costs: infrastructure management, server scaling, and ongoing developer maintenance. Headless commerce platforms like Swell eliminate these operational burdens while preserving the API-first flexibility that drove the original Vendure decision. Swell provides managed infrastructure with extensive customization through custom fields and models—no external databases or CMS systems required.

The migration from self-hosted Vendure to Swell's managed platform requires systematic planning, but the payoff appears in reduced DevOps overhead, eliminated hosting costs, and infrastructure that auto-scales during traffic spikes without manual intervention. For businesses currently managing Vendure servers while trying to focus on growth, the shift to managed headless commerce represents a strategic reallocation of resources from infrastructure to business development.

Key Takeaways

• Vendure's self-hosted architecture requires ongoing infrastructure management, while Swell provides fully managed headless commerce with the same API-first flexibility and extensive customization capabilities
• Migration follows a specific data dependency sequence: products → customers → orders → shipments → subscriptions, with Swell's migration endpoint supporting batch processing up to 1,000 records at once
• Only bcrypt-encrypted passwords transfer between platforms—plan customer communication around password resets before migration launch
• Do NOT use the $migrate: true flag when importing subscriptions; they require event triggers to set up billing automation properly
• Phased migration over 6-8 weeks reduces risk compared to big-bang approaches, with parallel running recommended for 2-4 weeks before full cutover
• Swell's native subscription engine, B2B capabilities, and unlimited product modeling eliminate third-party extension dependencies common in Vendure implementations

Why Swell is the Future-Proof Choice for E-commerce Growth

Vendure offers powerful capabilities for teams with TypeScript and GraphQL expertise, but the total cost of ownership extends beyond the open-source license. Server hosting, security patching, performance optimization, and scaling infrastructure demand ongoing developer attention—resources that could drive business growth instead of maintaining systems.

Understanding Swell's Core Value Proposition

Swell's API-first architecture provides the same backend access developers expect from Vendure, but with managed infrastructure handling hosting, scaling, and security. The same API powering Swell's dashboard and checkout is available to developers, meaning anything possible in the admin interface can be replicated, customized, or extended through code.

Key differentiators from self-hosted solutions:

• Auto-scaling infrastructure with global CDN eliminates capacity planning
• Native subscription billing works with any payment gateway through an encrypted card vault
• Unlimited product modeling without custom entity development
• Built-in B2B and wholesale capabilities without plugin dependencies
• 99.9% uptime SLA with infrastructure reliability handled by the platform

Addressing Common E-commerce Limitations

Vendure's plugin architecture handles extended functionality, but each plugin requires maintenance, compatibility testing, and potential security updates. Swell builds commonly needed features—subscriptions, customer-group pricing, multi-level navigation, product bundling with individual inventory tracking—directly into the core platform.

For businesses processing significant transaction volume, Swell's competitive transaction fee structure provides cost predictability compared to managing payment gateway integrations directly through self-hosted infrastructure.

Seamless Product Data Transfer: From Vendure to Swell

Product migration forms the foundation of the transfer process since orders and subscriptions reference product records. Swell's migration endpoint with batch processing capabilities simplifies bulk data import.

Handling Unlimited Product Options and Variants

Vendure's custom entity system allows complex product modeling, but recreating that flexibility requires development work. Swell provides unlimited products and variants with custom attributes—both visible customer-facing options and hidden operational fields—without custom code.

Export from Vendure includes:

• Product titles, descriptions, and SKUs
• Variant options and pricing
• Inventory quantities and tracking status
• Product images and variant-specific media
• Custom fields mapped to Swell custom attributes

Use Swell's batch endpoint with the $migrate: true flag for products:

await swell.post('/:batch', {

1: {

url: '/products',

data: {

$migrate: true,

name: 'Product Name',

price: 99.99,

stock_tracking: true,

stock_level: 100

},

method: 'POST'

}

});

The $migrate flag bypasses standard validation rules, enabling stock_level import during initial data transfer that would otherwise require event triggers.

Leveraging Swell's Flexible Product Models

Swell supports multiple product types natively: physical goods, digital downloads, services, bundles, and gift cards. The model editor accessible through dashboard or API enables creating entirely custom data structures for business-specific needs.

CSV import/export handles bulk product management for simpler migrations, while the API provides granular control for complex product structures with custom relationships.

Migrating Subscription Models and Customer Data

Subscription migration demands the most careful planning. Active subscribers expect uninterrupted service, making billing schedule continuity critical.

Transitioning Advanced Subscription Features

Swell's native subscription engine handles flexible billing intervals, separate invoicing from fulfillment schedules, and mixed carts combining subscription and one-time products—features that often require custom development or third-party plugins in Vendure.

Migration checklist for subscriptions:

1. Export complete subscription data (billing frequency, next charge date, product SKUs, pricing)
2. Extract payment tokens from existing gateway (Stripe, Braintree)
3. Import customers and products first (subscriptions reference both)
4. Create subscription records in Swell with imported payment tokens
5. Verify billing schedules align with original next charge dates

Critical: Do not use the $migrate: true flag when importing subscriptions—they rely on subsequent events to set up properly. Skipping events triggers billing automation.

Securely Transferring Customer Profiles and Payment Methods

Customer data migration preserves account relationships and enables continued subscription billing:

• Contact information (email, phone, addresses)
• Account creation dates using ISO 8601 format in date_created field
• Customer groups and tags
• Custom fields for business-specific data
• Payment tokens for future charges

Password considerations: Only bcrypt-encrypted passwords transfer successfully. Plan a customer communication strategy explaining the password reset process since only bcrypt-encrypted passwords can be migrated.

Swell's encrypted card vault enables importing payment tokens from Stripe and Braintree using compatible formats, maintaining subscription billing continuity without requiring customers to re-enter payment information.

Building a Headless Storefront: Swell's API-First Approach

Developers familiar with Vendure's GraphQL API will find Swell's RESTful architecture equally flexible, with the added benefit of managed infrastructure eliminating deployment and scaling concerns.

Leveraging Swell's Comprehensive APIs for Customization

Swell provides three API layers for different use cases:

Backend API: Full CRUD access to all data models with secret key authentication. Use for server-side operations, data migrations, webhook handlers, and admin tools.

Frontend API: Partial CRUD for browser-based usage with public key authentication. Handles customer-facing operations—product catalogs, cart management, checkout flows, account management.

Checkout API: Enables custom payment flows and checkout experiences without PCI compliance burden.

The developer console built into the dashboard lets you test API calls, view request/response logs, and troubleshoot integration issues without leaving the browser.

Connecting Multiple Touchpoints with a Single Backend

Swell enables building storefronts in any JavaScript framework—React, Vue, Svelte—or programming language, connecting multiple customer touchpoints to a single commerce backend. Popular implementation frameworks include:

• Next.js for server-side rendering and static generation
• React for component-based UIs
• Vue for progressive framework implementations
• Svelte for compiled components with minimal runtime

For teams preferring managed storefronts, Swell's hosted solution with visual theme editor provides drag-and-drop customization without custom development—an option not available with self-hosted Vendure.

Custom Checkout, Payments, and Fulfillment Management

Swell provides two checkout paths at all pricing tiers: hosted Swell Checkout (PCI-compliant) or custom checkout via API—eliminating the PCI compliance burden that comes with self-hosted payment handling.

Replicating Advanced Checkout Logic

The Checkout API enables building custom payment flows while Swell handles PCI compliance, tokenization, and payment processing. Features available across all plans:

• Guest checkout option
• Abandoned cart recovery with automated sequences
• Saved payment methods in encrypted vault
• Split payments per order item or entire order
• Multi-part payment plans for installments

Payment gateway integration supports Stripe, PayPal, Authorize.Net, Braintree, and Amazon Pay through Swell's unified payment abstraction layer. Buy Now Pay Later services—Affirm, Klarna, Resolve for B2B net terms—integrate natively.

Optimizing Fulfillment Workflows

Swell's fulfillment capabilities handle complex shipping scenarios without custom development:

• Multi-warehouse management for distributed inventory
• Flexible shipping price rules by geographic zone, service type, or price point
• Split fulfillment shipping order items separately from different locations
• Product-specific shipping dimensions and weight tracking
• Order editing post-purchase without custom code

ShipStation integration connects Swell to carrier networks for label generation and tracking, while the shipping API enables custom carrier integrations when needed.

Internationalization and Localization: Expanding Your Reach with Swell

Global expansion with Vendure requires custom development for multi-currency pricing and localization. Swell provides these capabilities natively, supporting 230 currencies and content localization in 170 languages.

Setting Up Multi-Currency and Language Support

Two pricing approaches handle international commerce:

Explicit pricing: Set specific prices in each currency for psychological pricing strategies ($99 vs €89) or market-specific pricing. Configure product prices, shipping costs, and discount amounts per currency through dashboard or API.

Automatic conversion: Real-time exchange rates calculate prices dynamically, reducing management overhead for businesses without market-specific pricing requirements.

Multi-language support handles field-level translation for customer-facing content: product names, descriptions, checkout instructions, and email notifications. Each language version maintains separate content while sharing underlying product data and inventory.

Streamlining Global Tax Compliance

Tax automation eliminates manual compliance management:

• Avalara AvaTax: Real-time tax calculation worldwide with compliance reporting
• TaxJar: Automated sales tax calculation and filing for US businesses

For businesses with specific requirements, Swell supports creating custom tax rule groups by location and product type—functionality that would require custom development in Vendure.

Extending Store Functionality: Custom Models and Integrations

Vendure's custom entity system provides data modeling flexibility at the cost of development time. Swell's custom fields work across all standard models—products, orders, customers, carts—without code deployment.

Defining Custom Data Structures to Fit Your Business

The model editor enables creating entirely custom data structures for business-specific needs. A B2B wholesaler might add custom fields for net payment terms, a subscription box company could track dietary preferences, and a marketplace could manage vendor-specific metadata—all native to the platform.

Webhooks fire real-time notifications when events occur—order placed, subscription renewed, payment failed. Subscribe to specific events and Swell POSTs data to your endpoint immediately, enabling:

• Custom business logic triggers
• External system synchronization
• Custom notification workflows
• Third-party service updates

Connecting Your Tech Stack with Swell's Native Integrations

Swell's integration ecosystem includes native connections to common commerce tools:

• Klaviyo: Email marketing automation
• Contentful: Headless CMS integration
• ShipStation: Fulfillment and shipping
• Algolia: Product search
• Zapier: Workflow automation with 500+ apps

The unified payment abstraction layer processes transactions through all supported gateways consistently, enabling gateway switching without checkout integration rebuilds.

Strategic Planning for a Successful Migration to Swell

Most migration issues trace back to incomplete planning. A phased approach reduces risk compared to big-bang migrations that attempt everything simultaneously.

Key Phases of Your Migration Project

Phase 1 (Weeks 1-2): Pre-Migration Assessment

• Export Vendure data via CSV or API
• Audit current product catalog, customer database, and order history
• Map Vendure data structures to Swell models
• Create custom fields for data not covered by standard Swell fields

Phase 2 (Weeks 2-3): Products and Categories

• Batch import products using migration endpoint
• Configure product options and variants
• Validate inventory levels and pricing

Phase 3 (Weeks 3-4): Customers and Payment Methods

• Migrate customer accounts with payment tokens
• Send password reset communications
• Verify customer group assignments

Phase 4 (Weeks 4-5): Historical Orders and Subscriptions

• Import order history with original dates
• Create subscription records without migration flag
• Test billing automation in test environment

Phase 5 (Weeks 5-7): Storefront Development

• Build or configure storefront (hosted or custom headless)
• Integrate payment gateways and fulfillment
• Configure shipping zones and tax automation

Phase 6 (Week 8): Go-Live

• Run parallel systems for 2-4 weeks before full cutover
• Switch DNS and monitor traffic
• Disable old Vendure instance

Leveraging Swell's Support and Resources

Swell provides developer documentation, help center guides, and integration setup instructions. Higher-tier plans include priority support and dedicated developer support for complex migrations.

Test environments separate from live stores enable development and QA workflows during migration. The developer console logs API calls and webhook attempts for debugging integration issues.

For businesses requiring implementation assistance, Swell's agency partner program connects merchants with development shops experienced in platform migrations.

Frequently Asked Questions

What are the primary advantages of migrating from Vendure to Swell?

The core advantage is trading infrastructure management burden for managed platform benefits while maintaining API-first flexibility. Vendure requires ongoing server hosting, security patching, performance optimization, and scaling work—tasks that consume developer time without driving business growth. Swell handles infrastructure entirely, freeing technical resources for customer-facing improvements. Additionally, Swell's native subscription billing, B2B capabilities, and multi-currency support eliminate plugin dependencies that add complexity and maintenance overhead in Vendure implementations.

What level of technical expertise is required to perform a Vendure to Swell migration?

Migration requires advanced business user skills with technical support—specifically API knowledge and scripting capabilities for data migration. Teams familiar with Vendure's TypeScript environment will find Swell's REST API approachable. Small technical teams (1-2 developers plus project manager) typically handle migrations successfully. For businesses without internal API expertise, Swell's agency partner network includes development shops experienced in platform migrations who can manage the technical transfer while internal teams focus on business continuity.

How does Swell handle data volume during migration?

Swell's migration endpoint supports batch processing of up to 1,000 records per API call. For stores with fewer than 10,000 products, migration typically completes in 2-3 weeks. Stores with 10,000-50,000 products require 4-6 weeks, while larger catalogs exceeding 50,000 products may need 8+ weeks. Keep batch sizes under 1,000 records to avoid timeout issues, and split large datasets across multiple import operations.

What happens to Vendure's custom entities during migration?

Vendure custom entities map to Swell custom fields and custom models. Before starting data import, create all equivalent custom fields in Swell to ensure proper data structure preservation. The model editor accessible through dashboard or API enables defining custom data structures matching your existing Vendure schema. This preparation step prevents data loss during transfer and maintains business process continuity. Document all Vendure custom entities thoroughly during the pre-migration assessment phase to ensure complete field mapping.

Can I run Vendure and Swell in parallel during migration?

Yes, parallel running is recommended for 2-4 weeks before full cutover to validate functionality and catch issues before they impact customers. During parallel operation, continue processing orders through Vendure while testing the complete customer journey on Swell—product browsing, cart functionality, checkout completion, subscription management, and account operations. This approach reduces risk by enabling rollback if critical issues emerge, while providing time to train teams on the new platform before it becomes the primary system.