VTEX Order History Migration to Shopify

Last updated August 2026

A technical guide to handling order history migration when migrating from VTEX to Shopify. This covers what transfers, what does not, the specific risks for VTEX stores, and the recommended approach.

VTEX-specific considerations

When migrating order history migration from VTEX, the following platform-specific aspects must be considered:

Data model implications

VTEX's data model stores this information differently than Shopify. In VTEX: OMS order with marketplace/seller split, fulfillment, returns, and invoicing.

Can Shopify's Store Migration app handle order history migration?

What transfers

• Order ID mapping can be created via API
• Order line items with product references
• Order totals and subtotals
• Payment status (limited)
• Fulfillment status (limited)
• Order timestamps

What does NOT transfer

• Historical orders are NOT migrated by Shopify's native tools for most platforms
• Order notes and internal comments usually lost
• Payment gateway transaction IDs
• Tax breakdowns at line-item level
• Discount codes and their exact application
• Order-level custom fields (most platforms)
• Gift messages and wrapping data
• Shipping carrier and tracking ID history

Specific risks for VTEX stores

• Customer order association requires customer records to exist in Shopify first
• Importing orders via API counts toward Shopify API rate limits
• Order IDs will change, breaking any external references
• Historical payment data (partial refunds, payment method details) may be incomplete
• Orders from deleted products create orphan records
• Multi-currency orders require Shopify Markets configuration

Recommended approach

For most stores, historical orders should NOT be migrated to Shopify unless required for customer service, reordering, or loyalty programs. Use a separate reporting system for historical order data. If migration is required, use the Shopify Admin API or a third-party app like Matrixify, importing customers first, then orders.

Exporting order history migration data from VTEX

• VTEX Admin CSV export (limited)
• VTEX Catalog API (REST)
• VTEX Master Data API
• VTEX OMS API
• Third-party connectors

Technical notes

• Shopify's Order API requires POST /admin/api/2026-07/graphql.json with complete order structure
• Orders must reference existing customer and product IDs in Shopify
• Shopify does not support importing order discount codes via API
• Transaction history (order payment events) should be imported separately via the Transaction API
• Order timeline events (fulfillment, refund) can be added via Order/fulfillment endpoints
• Shopify uses GraphQL cost-based rate limiting. Check current limits at shopify.dev/docs/api/usage/rate-limits
• Matrixify (Excelify) is the most commonly used app for bulk order import
• Consider archiving instead of importing: export orders to a database/reporting tool

Other VTEX migration issues

References

• Shopify Order API Reference — Shopify
• Migrating data with Matrixify — Matrixify