Shopify Import/Migration

Paid pluginsize Lplanned, not built

Indicative price, not an offer: €249 one-time + €59/mo (6 month support); support commitment: we handle your Shopify export, data cleaning, testing

Generated from docs/plan/paid/shopify-import-migration/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Merchants exporting from Shopify can import their product catalog, customer list, order history, and inventory into AstroBaaS in one operation. The paid pack provides data validation, deduplication, and post-migration support; core owns the import interface and ETL orchestration.

The problem

Migrating from Shopify to AstroBaaS is manual and error-prone: products must be re-entered, inventory is lost, customer emails are not imported, order history is orphaned. Merchants fear data loss and downtime.

What it does

• Shopify data export: merchants provide Shopify API key or download CSV export file
• Product import: SKU, name, description, images, price, inventory, tags, collections
• Customer import: email, name, address, order history, lifetime value (informational)
• Order history import: order ID, date, items, total, payment status, shipping address (read-only archive)
• Inventory sync: import stock levels per location (warehouse, store)
• Deduplication: if product SKU exists in AstroBaaS, merge or skip (admin chooses per product)
• Validation report: pre-import check for data quality (missing fields, invalid prices, image URLs)
• Rollback: admin can undo import if errors are discovered (up to 24 hours post-import)

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Discount codes: Shopify discount rules are complex; merchants must recreate them in AstroBaaS (not part of migration).
• Abandoned carts: Shopify carts don’t migrate; customers lose carts (expected loss in migration).
• Theme/design: Shopify theme HTML is not portable; merchants redesign storefront in AstroBaaS (scope is data, not design).
• Apps and integrations: Shopify apps (Recharge, Klaviyo, etc.) don’t migrate; merchants reconnect to AstroBaaS (per app, not AstroBaaS responsibility).

Data model

Migration records: import_job { jobId, shopifyStoreId, status (pending, running, completed, failed), productsImported, customersImported, ordersImported, startedAt, completedAt, errors }. Import mappings stored per product for deduplication tracking.

API

• POST /api/import/shopify/start { shopifyApiKey OR csvFile } -> { jobId, estimatedDuration }
• GET /api/import/shopify/{jobId}/status -> { status, progress, imported_counts, errors }
• POST /api/import/shopify/{jobId}/validate -> { validation_report, issues, ready_to_import }
• POST /api/import/shopify/{jobId}/confirm -> { started }
• POST /api/import/shopify/{jobId}/rollback (within 24 hours) -> { rolled_back }
• GET /api/import/shopify/{jobId}/report (admin only)

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Admin sees: import wizard (upload CSV or enter Shopify API key), pre-import validation report (row-by-row errors), import progress bar with item counts, deduplication handler (merge/skip per product), rollback button (24-hour window), import history.

The seam — why this is paid

Core owns the import interface and ETL orchestration. Paid pack owns: Shopify API integration, data cleaning/deduplication logic, validation rules, post-migration support.

Support commitment: Shopify API access, data validation, post-migration support

Dependencies

• product subsystem (existing; stores products)
• customer subsystem (existing; stores customers)
• order subsystem (existing; stores order archive)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• A Shopify export CSV with 500 products, 1000 customers, 5000 orders completes import in under 5 minutes
• Pre-import validation detects 50 products with missing descriptions; admin can choose to import anyway
• A product with SKU ‘ABC123’ exists in AstroBaaS; import finds duplicate and prompts admin to merge or skip
• Imported orders are visible in order history (read-only); they cannot be edited
• Imported customer email, name, address are correct; lifetime value is shown informational
• Inventory for ‘Main Warehouse’ and ‘Brooklyn Store’ are both imported and tracked per location
• Within 24 hours of import, admin clicks ‘Rollback’; all imported data is removed and removed SKUs are deleted
• After 24 hours, rollback button is disabled

Risks

If deduplication is not careful, duplicate products are created (SKU ABC123 appears twice with different prices). If customer email is not deduplicated, duplicate customer records create checkout issues. If order history import runs before products are imported, order line items reference non-existent SKUs. If rollback recreates deleted products, merchants lose new data entered after import. If validation is not strict enough, garbage data (invalid prices, malformed emails) propagates to production.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.