Migration Guide

This guide walks through the complete migration process from start to finish. Follow each step in order — the dependency chain between entity types matters.

Migration Steps

curl -X GET "https://yoursite.com/wp-json/cartshift/v1/preflight" \
  -H "X-WP-Nonce: YOUR_NONCE"

curl -X GET "https://yoursite.com/wp-json/cartshift/v1/counts" \
  -H "X-WP-Nonce: YOUR_NONCE"

{
  "products": 142,
  "categories": 12,
  "customers": 856,
  "orders": 3241,
  "subscriptions": 94,
  "coupons": 27
}

curl -X POST "https://yoursite.com/wp-json/cartshift/v1/migrate" \
  -H "X-WP-Nonce: YOUR_NONCE" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_types": ["products", "customers", "coupons", "orders", "subscriptions"],
    "dry_run": true
  }'

curl -X GET "https://yoursite.com/wp-json/cartshift/v1/log?per_page=100" \
  -H "X-WP-Nonce: YOUR_NONCE"

curl -X POST "https://yoursite.com/wp-json/cartshift/v1/migrate" \
  -H "X-WP-Nonce: YOUR_NONCE" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_types": ["products", "customers", "coupons", "orders", "subscriptions"]
  }'

{ "entity_types": ["products", "customers"] }

curl -X GET "https://yoursite.com/wp-json/cartshift/v1/progress" \
  -H "X-WP-Nonce: YOUR_NONCE"

{
  "migration_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "running",
  "dry_run": false,
  "started_at": "2025-03-15 10:30:00",
  "completed_at": null,
  "entities": {
    "products": {
      "status": "completed",
      "total": 142,
      "processed": 138,
      "skipped": 4,
      "errors": 0
    },
    "customers": {
      "status": "running",
      "total": 856,
      "processed": 312,
      "skipped": 5,
      "errors": 0
    },
    "coupons": {
      "status": "pending",
      "total": 0,
      "processed": 0,
      "skipped": 0,
      "errors": 0
    },
    "orders": {
      "status": "pending",
      "total": 0,
      "processed": 0,
      "skipped": 0,
      "errors": 0
    },
    "subscriptions": {
      "status": "pending",
      "total": 0,
      "processed": 0,
      "skipped": 0,
      "errors": 0
    }
  }
}

curl -X POST "https://yoursite.com/wp-json/cartshift/v1/cancel" \
  -H "X-WP-Nonce: YOUR_NONCE"

curl -X GET "https://yoursite.com/wp-json/cartshift/v1/log?per_page=100" \
  -H "X-WP-Nonce: YOUR_NONCE"

Entity Migration Details

Each entity type has specific mapping behavior. Understanding these details helps you verify your migrated data and troubleshoot any issues.

Products

Supported types: Simple and variable products. Grouped and external products are skipped.

What gets mapped:

Product details (fct_product_details table):

• Fulfillment type: physical, digital, or service based on WC product properties
• Variation type: simple or advanced_variations
• Stock availability and management settings
• Min/max price range calculated from variations

Variations (fct_product_variations table):

• Simple products get one "Default" variation
• Variable products get one variation per WC variation
• Prices converted to cents (integer) — $29.99 becomes 2999
• Sale price becomes compare_price (original regular price)
• SKU uniqueness enforced — duplicates get a -wc{id} suffix
• Stock quantities, backorder settings, and downloadable flags preserved
• WC Subscription metadata (billing period, trial, signup fee) mapped to other_info

Category migration runs before products. Categories are sorted so parents are created before children. The "Uncategorized" default category is skipped. Categories already existing in FluentCart (matched by slug) are reused, not duplicated.

Customers

Registered customers:

WordPress users with the customer role. Each user becomes a FluentCart customer record with billing/shipping addresses.

Guest customers:

Extracted from orders that have no customer_id (or customer_id = 0). Each unique billing email becomes a FluentCart customer. The migrator supports both HPOS (wc_orders table) and legacy post-based order storage.

Addresses:

Both billing and shipping addresses are created as CustomerAddresses records in FluentCart. Phone numbers and company names are stored in the address meta field.

Deduplication: If a customer with the same email already exists in FluentCart, the migrator stores the ID mapping and skips creation.

Orders

Orders are the most complex entity to migrate. Each WooCommerce order maps to multiple FluentCart tables.

Order record (fct_orders):

Status mapping:

Order items (fct_order_items):

Each line item references the FluentCart product and variation via the ID map. Unit prices and line totals are converted to cents. Subscription product metadata is preserved.

Order addresses (fct_order_addresses):

Billing and shipping addresses stored per-order. Company names and phone numbers in the meta field.

Transactions (fct_order_transactions):

The primary payment creates a charge transaction. Refunds create separate refund transactions linked to the same order. WooCommerce transaction IDs are preserved in the meta field.

Order types:

• Regular orders become onetime
• Orders containing subscription products become subscription
• Renewal orders (child orders from WC Subscriptions) become renewal

HPOS support: The migrator works with both HPOS (High-Performance Order Storage) and legacy post-based orders. Customer counting and guest extraction auto-detect which storage is active.

Subscriptions

Requires WC Subscriptions to be active. If WC Subscriptions is not detected, the subscription migrator returns null and is skipped entirely.

What gets mapped:

Subscription status mapping:

Coupons

What gets mapped:

Coupon type mapping:

Conditions stored in the conditions JSON field:

• Minimum order amount
• Maximum order amount
• Usage limit (max uses)
• Per-customer usage limit
• Exclude sale items flag
• Free shipping flag

Deduplication: If a coupon with the same code already exists in FluentCart, it is skipped and the mapping is stored.

Batch Processing

All entity types are processed in batches of 50 records. This is controlled by the $batchSize property in AbstractMigrator.

The batch loop works as follows:

1. Count total records for the entity type
2. Fetch a batch of records (page 1, 2, 3...)
3. Process each record in the batch (map, validate, write)
4. Update progress after each record
5. Check for cancellation between records
6. Move to the next batch until all records are processed or the batch returns fewer than 50 records

This approach keeps memory usage predictable regardless of store size. A store with 10,000 orders processes them in 200 batches of 50.

ID Mapping

The cartshift_id_map table is central to the migration. Every time a WooCommerce record is successfully migrated, its WC ID and FC ID are stored along with the entity type.

Entity types in the ID map:

The ID map is used for:

• Cross-referencing — Orders look up customer and product IDs from the map
• Skip detection — Already-migrated records are skipped by checking the map
• Rollback — The rollback process uses the map to find and delete FluentCart records

Migration Log

Every processed record generates a log entry in the cartshift_migration_log table:

Retrieve the log via the REST endpoint:

curl -X GET "https://yoursite.com/wp-json/cartshift/v1/log?page=1&per_page=50" \
  -H "X-WP-Nonce: YOUR_NONCE"

The response includes pagination information:

{
  "entries": [ ... ],
  "total": 4360,
  "page": 1,
  "per_page": 50,
  "pages": 88
}