The SuiteCommerce Migration Checklist: Upgrading Without Downtime

Every hour of downtime costs money. For a mid-sized B2B store processing $50,000 daily, a four-hour migration window means $8,300 in lost revenue—plus the customer trust you can't quantify.

We've migrated dozens of SuiteCommerce stores, including complex B2B implementations with 50,000+ SKUs and custom integrations. Our track record: zero unplanned downtime. This guide shares the exact methodology we use.

Table of Contents

• Why SuiteCommerce Migrations Fail
• Phase 1: Pre-Migration Assessment
• Phase 2: Version Compatibility Analysis
• Phase 3: Customization Audit
• Phase 4: Data Backup and Recovery Planning
• Phase 5: Staging Environment Setup
• Phase 6: Zero-Downtime Deployment
• Phase 7: Post-Migration Validation
• The Complete Migration Checklist
• When to DIY vs. Hire Help
• FAQ

Why SuiteCommerce Migrations Fail

Before diving into the checklist, understand why migrations go wrong. In our experience, failures cluster around five root causes:

1. Untested Customizations Custom extensions that worked on version 2022.2 break silently on 2024.1. The store launches, everything looks fine, then orders start failing at checkout because a custom payment handler references deprecated APIs.

2. Data Sync Timing Migrations during business hours without proper data freeze protocols result in orders placed during the cutover window disappearing—or worse, duplicating.

3. DNS and CDN Propagation Teams flip DNS without accounting for TTL propagation. Half your customers hit the new store while the other half still see the old one, both writing to different databases.

4. Missing Rollback Plans The new deployment has a critical bug. There's no way back. You're debugging production at 2 AM while customers can't complete purchases.

5. Incomplete Testing "We tested the homepage and checkout" isn't a test plan. The edge case where a B2B customer with custom pricing and net terms places a partial shipment order—that's where things break.

This checklist exists to eliminate these failure modes systematically.

Phase 1: Pre-Migration Assessment

1.1 Define Migration Scope

Not all migrations are equal. Clarify exactly what you're doing:

1.2 Business Requirements Gathering

Document these before touching any code:

Downtime Tolerance

• What's the maximum acceptable downtime?
• Are there blackout periods (holiday season, monthly billing cycles)?
• Who approves the go-live decision?

Data Requirements

• Historical orders: How far back must they migrate?
• Customer accounts: Passwords, saved addresses, payment methods?
• Product data: Reviews, custom attributes, pricing tiers?

Feature Parity

• What functionality must work identically post-migration?
• What can change or improve?
• What legacy features can be deprecated?

1.3 Technical Inventory

Create a complete inventory of your current implementation:

CURRENT STATE DOCUMENTATION

Platform Version: SuiteCommerce Advanced 2022.2
Theme: Custom (based on Starter Theme v3)
Extensions: 
  - Custom Product Configurator (v2.1.0)
  - B2B Quick Order Pad (v1.4.2)
  - Advanced Shipping Calculator (v1.0.0)
  - Custom Payment Gateway Integration (v3.2.1)
  
Third-Party Integrations:
  - Avalara Tax Calculation
  - ShipStation Fulfillment
  - Klaviyo Email Marketing
  - Yotpo Reviews
  
Custom SuiteScripts:
  - ue_custom_checkout_validation.js
  - sl_shipping_rate_calculator.js
  - mr_inventory_sync.js
  
Custom Records:
  - customrecord_product_config
  - customrecord_shipping_rules

1.4 Performance Baseline

Capture current performance metrics. You'll compare these post-migration to validate success:

// Performance metrics to capture before migration
const baselineMetrics = {
  coreWebVitals: {
    LCP: 2.4,  // seconds (homepage, PDP, PLP)
    INP: 180,  // milliseconds
    CLS: 0.08
  },
  serverMetrics: {
    TTFB: 0.6,           // seconds
    avgPageLoad: 3.2,     // seconds
    checkoutCompletion: 4.1  // seconds
  },
  businessMetrics: {
    conversionRate: 2.8,  // percent
    cartAbandonmentRate: 68.5,
    avgOrderValue: 847    // dollars
  }
};

Phase 2: Version Compatibility Analysis

2.1 Review Release Notes

Oracle publishes detailed release notes for each SuiteCommerce version. Don't skim them—read them thoroughly. Look for:

• Deprecated APIs: Functions your extensions might use
• Breaking changes: Modified behaviors that affect existing functionality
• New dependencies: Updated Node.js versions, changed build tools
• Security patches: Required updates that may affect customizations

2.2 API Deprecation Audit

Run this analysis against your custom code:

// Example: Check for deprecated API usage
const deprecatedAPIs = {
  '2023.1': [
    'SC.Configuration.get()',  // Replaced with Configuration.get()
    'Application.getLayout()', // Replaced with Layout module
    'Backbone.View.afterAppend' // Replaced with lifecycle hooks
  ],
  '2024.1': [
    'jQuery.ajax()', // Should use Fetch API or Utils.ajax()
    'underscore.template()', // Use Handlebars
    'SC.Environment.published' // Replaced with Context module
  ]
};

// Grep your codebase for these patterns
// grep -r "SC.Configuration.get" ./Modules/

2.3 Dependency Version Matrix

Create a compatibility matrix for your tech stack:

2.4 Extension Compatibility Testing

For each custom extension, verify compatibility:

# Extension compatibility test procedure
1. Clone extension to isolated test environment
2. Update manifest.json to target new SC version
3. Run gulp deploy against new SC base theme
4. Catalog all compilation errors
5. Test all extension entry points manually
6. Document required code changes

Create a compatibility report:

## Extension: Custom Product Configurator v2.1.0

### Compilation Status: ⚠️ Errors

### Issues Found:
1. Line 47: SC.Configuration.get() deprecated
   - Fix: Replace with Configuration module import
   
2. Line 182: jQuery.Deferred() pattern
   - Fix: Migrate to native Promises
   
3. Line 256: Backbone.View lifecycle
   - Fix: Update to new afterViewRender hook

### Estimated Effort: 8-12 hours
### Risk Level: Medium

Phase 3: Customization Audit

3.1 Theme Customization Inventory

Document every theme modification:

THEME MODIFICATIONS

/Modules/Theme/
├── overrides/
│   ├── Header.View.js          # Custom mega menu
│   ├── ProductDetails.View.js  # Custom image gallery
│   └── Cart.View.js            # Custom upsell logic
├── sass/
│   ├── _custom-header.scss     # 450 lines
│   ├── _custom-pdp.scss        # 380 lines
│   └── _variables-override.scss # 120 lines
└── templates/
    ├── header.tpl              # Complete override
    ├── product_details.tpl     # Partial modifications
    └── facets_browse.tpl       # Minor tweaks

3.2 Classify Customizations by Risk

Categorize each customization:

3.3 Document Business Logic

For every custom business logic, document the "why" not just the "what":

// BEFORE: Undocumented customization
if (order.shipmethod === 'GROUND' && order.total > 500) {
  order.shipmethod = 'EXPRESS';
}

// AFTER: Documented customization
/**
 * Shipping Upgrade Rule (Implemented: 2023-06)
 * 
 * BUSINESS RULE: Orders over $500 with ground shipping selected
 * automatically upgrade to express at no additional cost.
 * 
 * STAKEHOLDER: VP Sales (approval email: 2023-06-15)
 * REASON: Customer retention initiative - high-value orders
 *         were experiencing delivery complaints
 * 
 * DEPENDENCIES: Requires EXPRESS shipping method in NetSuite
 * TESTING: Verify with orders $499, $500, $501
 */
if (order.shipmethod === 'GROUND' && order.total > 500) {
  order.shipmethod = 'EXPRESS';
}

3.4 SuiteScript Audit

Audit all custom SuiteScripts:

// SuiteScript compatibility checklist
const scriptAudit = {
  scriptId: 'customscript_checkout_validation',
  scriptType: 'UserEvent',
  deployedTo: ['Sales Order'],
  apiVersion: '2.0',  // ✅ Current
  
  // Check for version-specific issues
  usesNLAPI: false,   // ✅ Good - NLAPI is deprecated
  usesHttps: true,    // ✅ Using N/https module
  governanceUsage: {
    beforeSubmit: 15,  // units
    afterSubmit: 45    // units - watch this
  },
  
  // External dependencies
  callsExternalAPIs: ['avalara.com', 'shipstation.com'],
  handlesErrors: true,
  hasLogging: true,
  
  migrationRisk: 'Low'
};

Phase 4: Data Backup and Recovery Planning

4.1 Comprehensive Backup Strategy

Never migrate without backups. Create redundant copies:

NetSuite Data Backup

BACKUP CHECKLIST - NETSUITE

□ Export all saved searches to CSV
□ Export custom records (SuiteQL or saved search)
□ Screenshot all custom forms configurations
□ Export workflow definitions
□ Document all role permissions
□ Export all scripts and deployments
□ Backup File Cabinet custom folders

Storage: Minimum 2 locations (cloud + local)
Retention: 90 days post-migration

SuiteCommerce Code Backup

# Complete code backup procedure
cd /path/to/suitecommerce

# Tag current state in git
git tag -a "pre-migration-$(date +%Y%m%d)" -m "Backup before migration to v2024.1"
git push origin --tags

# Create archive
tar -czvf sc-backup-$(date +%Y%m%d).tar.gz \
  --exclude='node_modules' \
  --exclude='.git' \
  ./

# Upload to cloud storage
aws s3 cp sc-backup-*.tar.gz s3://company-backups/suitecommerce/

4.2 Rollback Procedures

Document exact rollback steps for every migration phase:

## ROLLBACK PROCEDURE - PHASE 6 (DEPLOYMENT)

### Trigger Conditions:
- Critical checkout errors affecting >1% of transactions
- Payment processing failures
- Order sync failures to NetSuite
- Homepage/PDP/PLP returning errors

### Rollback Steps:
1. **Immediate** (< 5 minutes)
   - Revert SSP application to previous bundle
   - NetSuite: Setup > SuiteCommerce > SSP Applications
   - Select previous version from dropdown
   - Save

2. **DNS Rollback** (if applicable)
   - Revert CNAME to previous deployment
   - TTL: Ensure pre-migration TTL was lowered to 300s

3. **Database Sync**
   - Pause all scheduled scripts
   - Run order reconciliation report
   - Manually process any orders stuck in queue

### Communication:
- Slack: #ecommerce-oncall
- Email: [email protected]
- Status page update: status.company.com

### Post-Rollback:
- Incident report within 24 hours
- Root cause analysis within 72 hours

4.3 Data Freeze Protocol

For migrations requiring data consistency:

DATA FREEZE TIMELINE

T-24 hours:
□ Notify customer service team
□ Add banner to site: "Scheduled maintenance Saturday 2-4 AM"
□ Disable promotional campaign triggers

T-4 hours:
□ Stop scheduled inventory syncs
□ Disable automated email campaigns
□ Export current order queue status

T-1 hour:
□ Disable new customer registration
□ Disable wishlist/saved cart updates
□ Set cart expiration to 30 minutes

T-0 (Migration Start):
□ Enable maintenance mode
□ Final order queue export
□ Begin migration

T+X (Migration Complete):
□ Validate order queue restored
□ Re-enable all systems
□ Monitor for 2 hours

Phase 5: Staging Environment Setup

5.1 Production-Mirror Staging

Your staging environment must mirror production exactly:

STAGING ENVIRONMENT REQUIREMENTS

NetSuite:
□ Sandbox account with recent production refresh
□ All custom records synced
□ All SuiteScripts deployed
□ Test payment processor credentials

SuiteCommerce:
□ Separate SSP application
□ Isolated domain (staging.company.com)
□ SSL certificate configured
□ CDN configured (or bypassed for testing)

Data:
□ Product catalog (full or representative subset)
□ Customer accounts (anonymized production data)
□ Pricing rules and promotions
□ Inventory levels

5.2 Automated Testing Infrastructure

Set up automated testing before migration:

// Example: Cypress E2E test suite for SuiteCommerce
describe('Critical Path Tests', () => {
  
  describe('Guest Checkout', () => {
    it('should complete checkout with credit card', () => {
      cy.visit('/product/sample-product');
      cy.get('[data-action="add-to-cart"]').click();
      cy.get('[data-action="proceed-to-checkout"]').click();
      
      // Fill shipping
      cy.get('#shipping-address-form').within(() => {
        cy.get('[name="firstname"]').type('Test');
        cy.get('[name="lastname"]').type('User');
        cy.get('[name="addr1"]').type('123 Test St');
        cy.get('[name="city"]').type('Austin');
        cy.get('[name="state"]').select('TX');
        cy.get('[name="zip"]').type('78701');
      });
      
      // Select shipping method
      cy.get('[data-shipmethod="standard"]').click();
      
      // Payment
      cy.get('#cc-number').type('4111111111111111');
      cy.get('#cc-expiry').type('12/28');
      cy.get('#cc-cvv').type('123');
      
      // Submit
      cy.get('[data-action="submit-order"]').click();
      
      // Verify confirmation
      cy.url().should('include', '/confirmation');
      cy.contains('Thank you for your order');
    });
  });
  
  describe('B2B Customer Flow', () => {
    it('should apply customer-specific pricing', () => {
      cy.login('[email protected]', 'password');
      cy.visit('/product/sample-product');
      cy.get('[data-price]').should('contain', '$89.99'); // Custom price
    });
    
    it('should allow purchase on terms', () => {
      cy.login('[email protected]', 'password');
      cy.addToCart('sample-product');
      cy.checkout();
      cy.get('[data-payment="terms"]').should('be.visible');
      cy.get('[data-payment="terms"]').click();
      cy.submitOrder();
      cy.url().should('include', '/confirmation');
    });
  });
});

5.3 Performance Testing

Load test your staging environment:

# Example: k6 load testing script
import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  stages: [
    { duration: '2m', target: 50 },   // Ramp up
    { duration: '5m', target: 100 },  // Sustained load
    { duration: '2m', target: 200 },  // Peak load
    { duration: '2m', target: 0 },    // Ramp down
  ],
  thresholds: {
    http_req_duration: ['p(95)<2000'], // 95% of requests < 2s
    http_req_failed: ['rate<0.01'],    // <1% failure rate
  },
};

export default function() {
  // Homepage
  let res = http.get('https://staging.company.com/');
  check(res, { 'homepage status 200': (r) => r.status === 200 });
  sleep(1);
  
  // Product listing
  res = http.get('https://staging.company.com/category/widgets');
  check(res, { 'PLP status 200': (r) => r.status === 200 });
  sleep(2);
  
  // Product detail
  res = http.get('https://staging.company.com/product/widget-pro');
  check(res, { 'PDP status 200': (r) => r.status === 200 });
  sleep(1);
  
  // Add to cart
  res = http.post('https://staging.company.com/api/cart', {
    item_id: '12345',
    quantity: 1
  });
  check(res, { 'add to cart': (r) => r.status === 200 });
}

Phase 6: Zero-Downtime Deployment

6.1 Blue-Green Deployment Strategy

The key to zero-downtime migrations is running old and new versions simultaneously:

BLUE-GREEN DEPLOYMENT ARCHITECTURE

                    ┌─────────────────┐
                    │   Load Balancer │
                    └────────┬────────┘
                             │
              ┌──────────────┴──────────────┐
              │                             │
    ┌─────────▼─────────┐        ┌─────────▼─────────┐
    │   BLUE (Current)  │        │   GREEN (New)     │
    │   SC 2022.2       │        │   SC 2024.1       │
    │   100% traffic    │        │   0% traffic      │
    └───────────────────┘        └───────────────────┘
              │                             │
              └──────────────┬──────────────┘
                             │
                    ┌────────▼────────┐
                    │    NetSuite     │
                    │   (Shared)      │
                    └─────────────────┘

CUTOVER PROCESS:
1. Deploy GREEN with 0% traffic
2. Internal testing on GREEN
3. Shift 5% traffic to GREEN (canary)
4. Monitor for 30 minutes
5. Shift 25% → 50% → 100% to GREEN
6. Decommission BLUE after 24 hours

6.2 Database Considerations

SuiteCommerce uses NetSuite as its database, simplifying some concerns but creating others:

// Handling concurrent sessions during migration

// PROBLEM: Customer on BLUE adds item to cart
//          Traffic shifts to GREEN
//          Cart appears empty

// SOLUTION: Session-aware routing
const routingStrategy = {
  existingSession: 'STICKY',    // Keep on current environment
  newSession: 'WEIGHTED',       // Route per traffic split
  cartInProgress: 'BLUE',       // Don't migrate active carts
  checkoutInProgress: 'CURRENT' // Never switch mid-checkout
};

6.3 CDN and Cache Management

Manage caches carefully during cutover:

# Pre-cutover cache warming
# Warm GREEN environment caches before traffic shift

PAGES=(
  "/"
  "/category/most-popular"
  "/category/new-arrivals"
  "/product/best-seller-1"
  "/product/best-seller-2"
  "/cart"
  "/checkout"
)

for page in "${PAGES[@]}"; do
  curl -s -o /dev/null "https://green.company.com${page}"
  echo "Warmed: ${page}"
done

# Post-cutover cache invalidation
# Clear old BLUE content from CDN

curl -X POST "https://api.cdn.com/purge" \
  -H "Authorization: Bearer $CDN_TOKEN" \
  -d '{"files": ["/*"]}'

6.4 Real-Time Monitoring During Cutover

Set up dashboards for the deployment window:

DEPLOYMENT MONITORING CHECKLIST

Real-Time Dashboards:
□ Error rate (target: <0.1%)
□ Response time P50/P95/P99
□ Checkout completion rate
□ Payment success rate
□ Order creation rate vs. baseline

Alerts (Immediate Response):
□ Error rate >1% for 2 minutes
□ P95 response time >5s
□ Checkout failures >5 in 5 minutes
□ Payment errors (any)
□ NetSuite sync queue >100 items

Team Communication:
□ War room Slack channel
□ All stakeholders on standby
□ Customer service briefed
□ Executive sponsor reachable

Phase 7: Post-Migration Validation

7.1 Functional Validation Checklist

After cutover, systematically validate every critical function:

POST-MIGRATION FUNCTIONAL TESTING

CORE SHOPPING FLOW
□ Homepage loads correctly
□ Navigation menus work
□ Search returns results
□ Faceted filtering works
□ Product pages display correctly
□ Add to cart functions
□ Cart updates (quantity, remove)
□ Checkout completes (guest)
□ Checkout completes (registered)
□ Order confirmation displays
□ Confirmation email received

CUSTOMER ACCOUNTS
□ Login works
□ Registration works
□ Password reset works
□ Order history displays
□ Address book editable
□ Payment methods manageable
□ Wishlist functions

B2B FEATURES (if applicable)
□ Customer-specific pricing shows
□ Terms payment available
□ Quick order pad works
□ Quote request submits
□ Account hierarchy displays
□ Sub-user permissions work

INTEGRATIONS
□ Tax calculation correct
□ Shipping rates calculate
□ Inventory levels sync
□ Orders appear in NetSuite
□ Fulfillment triggers work
□ Email marketing events fire
□ Analytics tracking correct

7.2 Performance Validation

Compare against your pre-migration baseline:

// Post-migration performance check
const postMigrationMetrics = {
  coreWebVitals: {
    LCP: 2.1,   // ✅ Improved from 2.4
    INP: 165,   // ✅ Improved from 180
    CLS: 0.06   // ✅ Improved from 0.08
  },
  serverMetrics: {
    TTFB: 0.5,            // ✅ Improved
    avgPageLoad: 2.9,      // ✅ Improved
    checkoutCompletion: 3.8 // ✅ Improved
  }
};

// Regression thresholds
const regressionAlerts = {
  LCP: baseline * 1.1,    // Alert if >10% worse
  conversionRate: baseline * 0.95 // Alert if >5% drop
};

7.3 48-Hour Monitoring Protocol

Maintain heightened monitoring for 48 hours post-migration:

48-HOUR POST-MIGRATION PROTOCOL

Hours 0-4:
□ All hands monitoring
□ Check orders every 15 minutes
□ Compare conversion rate vs. same day last week
□ Review all error logs

Hours 4-12:
□ Reduced team, senior engineer on call
□ Check orders every 30 minutes
□ Review customer service tickets
□ First daily comparison report

Hours 12-24:
□ On-call engineer only
□ Automated monitoring active
□ Escalation procedures documented
□ Morning stand-up scheduled

Hours 24-48:
□ Normal operations resume
□ Continue enhanced monitoring
□ Compile migration success report
□ Schedule retrospective meeting

The Complete Migration Checklist

Here's the consolidated checklist for your migration:

# SUITECOMMERCE MIGRATION CHECKLIST

## PHASE 1: PRE-MIGRATION ASSESSMENT
□ Define migration scope and type
□ Document business requirements
□ Identify downtime tolerance
□ Create technical inventory
□ Capture performance baseline
□ Identify stakeholders and approvers

## PHASE 2: VERSION COMPATIBILITY
□ Review target version release notes
□ Audit code for deprecated APIs
□ Create dependency version matrix
□ Test each extension for compatibility
□ Estimate total development effort

## PHASE 3: CUSTOMIZATION AUDIT
□ Inventory all theme modifications
□ Classify customizations by risk level
□ Document business logic and reasons
□ Audit all SuiteScripts
□ Map all third-party integrations

## PHASE 4: BACKUP AND RECOVERY
□ Complete NetSuite data backup
□ Tag code in version control
□ Create code archive in cloud storage
□ Document rollback procedures
□ Define data freeze protocol
□ Schedule maintenance window

## PHASE 5: STAGING SETUP
□ Configure sandbox environment
□ Deploy new version to staging
□ Migrate all customizations
□ Set up automated test suite
□ Execute load testing
□ Complete UAT sign-off

## PHASE 6: DEPLOYMENT
□ Lower DNS TTL (if applicable)
□ Deploy to production (GREEN)
□ Warm CDN caches
□ Execute canary deployment (5%)
□ Monitor for 30 minutes
□ Gradual traffic shift to 100%
□ Update monitoring thresholds

## PHASE 7: POST-MIGRATION
□ Complete functional validation
□ Verify performance metrics
□ Confirm order flow to NetSuite
□ Check all integrations
□ Review error logs
□ 48-hour enhanced monitoring
□ Decommission old environment
□ Conduct retrospective

When to DIY vs. Hire Help

Be honest about your team's capabilities:

Handle In-House If:

• Minor version upgrade (2024.1 → 2024.2)
• Minimal customizations (<5 extensions)
• Standard theme with CSS-only changes
• You have SuiteCommerce development experience
• You can tolerate a maintenance window

Hire Help If:

• Major version jump (2022.x → 2024.x)
• Heavy customizations (>10 extensions or core overrides)
• Custom SuiteScript integrations
• Zero-downtime requirement
• No in-house SuiteCommerce expertise
• B2B functionality with complex pricing
• High transaction volume (>$1M/month)

At Stenbase, we specialize in complex migrations. Our SuiteCommerce implementation services include migration planning, execution, and post-migration optimization.

FAQ

How long does a typical SuiteCommerce migration take?

Timeline depends on complexity:

• Simple upgrades (theme refresh, minor version): 2-4 weeks
• Standard migrations (major version, moderate customizations): 6-8 weeks
• Complex migrations (heavy customizations, zero-downtime requirement): 10-16 weeks

Can I migrate during business hours?

With proper blue-green deployment, yes. We've executed migrations during peak business hours without customers noticing. The key is gradual traffic shifting and instant rollback capability.

What's the biggest migration risk?

Untested customizations. Every custom extension, theme modification, and SuiteScript must be tested against the new version in staging before production deployment. "It worked before" is not a test plan.

Should I migrate or rebuild?

If your customizations are more than 3 versions old and weren't built following SuiteCommerce best practices, rebuilding is often faster than migrating. We assess this during our free site audit.

How do I handle orders placed during migration?

With zero-downtime deployment, orders continue processing normally. For traditional maintenance-window migrations, implement a data freeze protocol 1-4 hours before cutover and reconcile all pending orders immediately after.

Planning a SuiteCommerce migration? Contact Stenbase for a free migration assessment. We'll review your current implementation and provide a realistic timeline and risk analysis—no obligation.