When evaluating VTEX as a prospective Target Platform, the migration approach should match the required Next-Cart Migration Service, supported Add-ons where applicable, responsibility level, scope, and validation burden.
The right VTEX migration approach depends on how much of the merchant’s commerce operation must be interpreted, transformed, configured, or validated beyond ordinary record movement. VTEX can support sophisticated catalog structures, storefront implementations, marketplace operations, B2B scenarios, Master Data, integrations, and external services. That strength also means migration planning must separate supported record transfer from target-side implementation and custom business logic.
A small VTEX migration can require careful service-path selection if source data depends on custom fields, external identifiers, marketplace relationships, or headless storefront assumptions. A large migration can still fit a lighter path when the data is supported, the target structure is clear, and the merchant can validate the result confidently. The decision should be made from evidence, not from platform reputation or record count alone.
For VTEX, decide scope before execution: identify the supported records, eligible enhancements or tailored requirements, then choose who performs the agreed Migration Actions. The customer supplies business meaning, retains manual access and verifies the final result even when execution is expert-led.
What Migration Approach Means for VTEX
A VTEX migration approach is a decision about scope, responsibility, support level, configuration, and validation burden. It should explain which records are expected to migrate, which behaviors must be configured in VTEX, which supported records or fields require a data type condition, value expression, or different destination, which requirements need Custom Migration, and which launch tasks belong to the merchant’s implementation team.
A Product groups related selling choices; a SKU identifies a purchasable variation. Product specifications and SKU specifications have different roles, so moving a shared description does not establish a usable SKU selector. Stock belongs to a warehouse context, while trade policies distinguish channel catalog, pricing and logistics. A valid SKU can therefore exist without being ready for the intended channel. Qualify those relationships before assigning execution, and keep live seller, pricing and logistics setup separately owned.
The approach should separate four layers of work:
| Work layer | VTEX example | Service-path implication |
|---|---|---|
| Supported migrated records | Products, SKUs, categories, brands, customers, orders, images, CMS Pages, Blog Posts, and supported related fields. | May fit Standard Migration or Managed Migration depending on execution and validation needs. |
| Supported migration adjustments | data-type-specific record conditions, expression-based field-value changes, or compatible target destinations for supported source fields. | May require Data Filter, Data Transformation, or Advanced Data Mapping. |
| Custom or unsupported migration needs | Unsupported Master Data or app relationships, marketplace reconstruction, external IDs requiring non-standard handling, bespoke transformation or Custom Platform interpretation. | Requires Custom Migration review. |
| VTEX-side implementation | Storefront, apps, integrations, live checkout, payments, logistics, search, promotions, seller setup, and operational configuration. | Should be prepared and validated outside ordinary record migration. |
This separation protects the migration from two common mistakes: choosing too light an approach because the record types sound familiar, or choosing Custom Migration for work that is actually supported migration adjustment or VTEX-side implementation.
When Standard Migration May Be Enough
Standard Migration may be appropriate when the source data fits supported migration behavior, the VTEX target structure is predictable, and the merchant can manage setup, review, and approval responsibilities. It is strongest when products and SKUs are ordinary, categories and brands are clear, customer records are standard, order history needs readable reference value, and custom platform logic is limited.
Standard Migration should not be judged by volume alone. A large supported catalog can be feasible if the product/SKU relationship is clean and the merchant can validate representative samples. A smaller store may be unsuitable if key records depend on custom source fields, Master Data, marketplace ownership, or external system interpretation.
| Standard Migration readiness signal | VTEX-specific reason |
|---|---|
| Products and SKUs have clear source structures. | VTEX catalog mapping can be reviewed without bespoke transformation. |
| Specifications, categories, and brands are stable and supported. | Product discovery and merchandising values can be validated through ordinary samples. |
| Customers and orders are mostly standard records. | Historical context can remain useful without custom account reconstruction. |
| Pricing and promotions do not require special transformation. | Commercial setup can be handled through supported migration or VTEX configuration. |
| Marketplace, B2B, and Master Data expectations are limited or excluded. | The migration is less likely to depend on unsupported or custom data. |
| The merchant can validate the result. | Customer-led review remains practical. |
Standard Migration becomes risky when the merchant cannot describe what a passing VTEX sample should look like. If success criteria are unclear, the issue is not only execution; the scope itself needs refinement.
When Managed Migration May Be Safer
Managed Migration may be safer when VTEX scope is supported but expert execution of agreed Migration Actions is desired. Catalog interpretation, sample approval, integration review and launch timing still need customer-side owners. Expert execution does not automatically include sequencing the whole implementation project or coordinating every business team.
For VTEX, large Product/SKU volume and a busy launch can make execution capacity scarce. Managed Migration can reduce the burden of running agreed supported actions. Catalog, pricing, operations, storefront and integration teams still define requirements and verify results; unsupported Master Data or marketplace relationships remain separate scope questions.
| Managed Migration fit | VTEX scenario |
|---|---|
| Supported data with high review burden | Large catalog, many SKUs, many images, or broad historical order scope. |
| Multiple business owners must approve samples | Catalog, pricing, operations, support, SEO, storefront, and integration teams all need review. |
| Launch window is tight | Migration activity must be coordinated with target setup and source-store changes. |
| Merchant needs execution support | Included expert-led execution is useful while the merchant remains responsible for final verification. |
| Standard scope is clear but operational pressure is high | Expert execution is needed; customer-side coordination and approval are assigned separately. |
Select Managed Migration for expert execution of agreed supported actions. First qualify each required record, relationship and destination. Custom Migration applies when required extraction, Master Data interpretation, marketplace reconstruction or bespoke logic exceeds supported capability; compatible supported identifiers need not become custom.
When Add-ons Are the Right Tool
Add-ons help when the requirement is supported, bounded, and specific. Data Filter can apply separate conditions to eligible VTEX catalog or commerce entities. Data Transformation can produce a defined field value through an expression, and Advanced Data Mapping can send a supported source field to a different VTEX field. An unsupported or custom requirement still belongs in Custom Migration review.
A strong Add-on request is written as a concrete acceptance criterion. For example, the merchant may need to exclude Products that meet a defined source-field condition, transform a supported value through an expression, or remap a source field to a different VTEX field. A weak Add-on request uses vague language such as “make the VTEX structure match the source custom workflow,” which may actually require Custom Migration or target-side implementation.
VTEX does not support Advanced Database Mapping as Target. Master Data extensibility, an API or a database-capable Source does not change that gate. Advanced Data Mapping still requires an eligible compatible supported target field and preserves the source or already transformed value during routing.
When several Standard Add-ons are selected, processing follows Data Filter, Data Transformation, Advanced Data Mapping, then Advanced Database Mapping. Filtering selects records; transformation changes supported values; mapping routes the source value, or an already transformed value, without changing it during mapping. Combining supported Add-ons does not by itself require Custom Migration. Tax is excluded from both mapping Add-ons.
| Add-on need | VTEX example | Boundary check |
|---|---|---|
| Data Filter | Apply supported Product, Customer, Blog Post, or Order field conditions so only matching records migrate. | Filtering should not remove records needed for reporting, service, or SEO continuity. |
| Data Transformation | Apply expressions to transform supported VTEX-bound field values during migration. | The expression and outputs must remain within supported capability. |
| Advanced Data Mapping | Route supported source or already transformed values to eligible compatible VTEX Product, SKU, Customer, Order or content fields without changing the value during mapping. | Mapping cannot create unsupported VTEX behavior. |
| Tailored or Custom Add-on need | A Standard Add-on function needs project-specific modification, or bespoke Add-on functionality is required. | This work is reviewed and quoted through Custom Migration rather than treated as Standard Add-on scope. |
Add-ons are strongest when the source and target meaning is clear. They are weakest when the merchant is using them to avoid deciding whether a requirement is custom.
When Custom Migration Should Be Considered
Custom Migration should be considered when required VTEX data or relationships exceed supported migration and Standard Add-on capability. The trigger can be unsupported Master Data, app-owned records, marketplace reconstruction, Custom Platform extraction or bespoke transformation. Enterprise size, a native feature or an external identifier alone does not establish a custom requirement.
Custom Migration can be relevant even when the visible record count is small. A limited product set may require custom handling if each product depends on external PIM enrichment, nonstandard specifications, seller offers, custom pricing logic, or source-specific bundle behavior. A larger project may not need Custom Migration if the records are supported and target-side implementation handles the operational behavior.
| Custom Migration trigger | Why it changes the approach |
|---|---|
| Master Data entities must migrate | Custom entities may not behave like ordinary customer, product, or order fields. |
| External identifiers require handling beyond supported mapping | ERP, PIM, WMS, OMS, CRM or marketplace relationships may require tailored extraction or interpretation; a compatible supported reference field should be assessed first. |
| Marketplace or seller context must be reconstructed | Seller, offer, commission, fulfillment, or received-SKU meaning may require custom interpretation. |
| Product/SKU logic requires transformation | Bundles, kits, assemblies, personalization, attachments, or service logic may not map cleanly. |
| Storefront-sensitive data must be reshaped | URLs, CMS content, search/facet behavior, routing, or metadata may need bespoke handling. |
| Source platform is custom or heavily modified | The source structure itself may require custom extraction and interpretation. |
Custom Migration should be scoped from examples. The merchant should provide representative records, expected outcomes, and business reasons for preserving the custom value. Without examples, Custom Migration planning can become abstract and difficult to validate.
Custom Migration can use Self-Execute or Expert Handle for its agreed Migration Actions. Selecting CSV, XLS or XML as the Source Platform requires Custom Migration; the standard included file workflow covers Products only. Other required data types must be agreed explicitly. This differs from a supported platform’s File Upload connection method, and a Product export alone does not establish the complete VTEX scope.
Demo Migration as the Service-Path Evidence Gate
Demo Migration can examine a limited representative sample available in the active supported path and reveal gaps in the proposed VTEX approach. Add-ons and Customization are unavailable in Demo, and Reviews and Coupons are excluded. Use the contexts below to identify standard sample checks and requirements needing separate proof. Validate enhanced or tailored output through the agreed paid scope, and assign storefront, extension and live-operation checks to target implementation.
| Demo Migration sample | What it should decide |
|---|---|
| Simple product and SKU | Whether baseline catalog migration works cleanly. |
| Multi-SKU product | Whether source variants become usable VTEX SKUs. |
| Specification-heavy product | Whether discovery, search, filter, and merchandising values remain structured. |
| Commercial rule example | Distinguish supported historical values from live trade-policy pricing, promotion and logistics setup; enhanced or tailored output needs paid proof. |
| Customer with business context | Whether customer and account meaning remains usable. |
| Operational order | Whether historical order context remains readable for service and finance. |
| Master Data or integration-owned value | Diagnose the supported destination or scope gap from project evidence. Add-on or tailored Master Data/integration output requires agreed paid proof. |
| Storefront-sensitive record | Whether content, URLs, search, and SEO assumptions need separate implementation or custom handling. |
If limited standard samples preserve the required Product/SKU and historical meaning, that supports the standard part of the approach. Repeated structural gaps, missing references or marketplace ambiguity require scope review. Prove selected Add-ons and tailored output through agreed paid activity; storefront and live commercial behavior require separately owned implementation checks.
Entity Points and VTEX Scope Planning
Entity Points support eligible record capacity rather than VTEX complexity. Products, Customers, Orders and Blog Posts consume points when they first migrate successfully within the same purchased migration and fixed Source-to-Target path. New eligible records introduced later consume capacity on their first successful migration; previously counted records remain counted once.
Eligible records already counted within the purchased migration do not consume Entity Points again simply because the merchant continues migration activity or performs another migration action on the same migration path. That rule is important for VTEX projects where launch windows may include new products, customers, orders, or Blog Posts after the first migration run.
Entity Points do not measure VTEX complexity by themselves. A migration with modest record volume may still require Custom Migration if Master Data, external identifiers, seller context, or bespoke product/SKU transformation is required. A larger migration may fit Standard Migration or Managed Migration if the records are supported and reviewable.
Migration Actions for VTEX
VTEX launch planning often includes later migration activity because catalog, seller, offer, Master Data, Order, and integration work may continue while the target account is being prepared. These actions apply after a paid migration has produced an earlier result. The selected action depends on whether its recorded configuration remains valid, supported migration rules must change, or the target result needs a fresh basis. Demo findings should inform the first paid configuration rather than be treated as a paid result to continue.
| Migration Action | When it fits VTEX | What must be revalidated |
|---|---|---|
| Continue the Migration with Last Saved Configuration | The accepted filters, mappings, and supported data configuration remain correct, and the main need is to process newly eligible records or later source changes. | New Products and SKUs, changed specifications, Customers, Orders, Blog Posts, URLs, and a regression sample from earlier migrated records. |
| Continue the Migration with a New Configuration | Review of the earlier paid result or revised target requirements shows that filtering, mapping, content scope, specification handling, seller context, or supported data configuration must change. | Every affected Product/SKU family, category and specification relationship, seller or offer sample, Customer and Order record, content item, URL, and field influenced by the new configuration. |
| Perform a New Migration | The previous target result is no longer a suitable working basis, the VTEX environment has been reset, or the scope and assumptions have changed materially. | The complete accepted scope, replacement behavior, target cleanliness, catalog activation requirements, seller context, historical records, URLs, and integration-sensitive outputs. |
Eligible records already counted on the same migration path are not counted again, while genuinely new eligible Product, Customer, Order, or Blog Posts records may consume capacity when first migrated. VTEX seller, Trade Policy, logistics, Master Data, and marketplace complexity must be evaluated separately.
Revalidation should match the action. A continuation with the same configuration emphasizes new records plus regression samples. A continuation with a new configuration must prove that the changed rule improves the intended output without damaging unaffected records. A new migration requires broader proof because the target result is being rebuilt. VTEX-side pricing, logistics, checkout, seller onboarding, storefront implementation, apps, and integrations remain separate responsibilities unless explicitly included in the agreed scope.
The first paid run uses Perform a New Migration. Either continuation action requires an earlier paid migration; Demo alone does not establish a paid configuration. These actions keep the purchased Source-to-Target path and actual Store identities fixed. A different Source Platform, Target Platform, actual Source Store or actual Target Store requires a separate purchased Migration Service.
Choose the source-data window separately from the action. “Migrate only newly added entities” selects records added after the last successful run, not edits to existing records. “Continue the previous migration” applies to the appropriate previous migration state. Neither option is implied by an action name. When configuration changes, check the combined earlier and later output; a new action does not automatically erase protected target data.
VTEX Service-Path Decision Matrix
VTEX projects often combine ordinary commerce records with enterprise structures that are configured or owned elsewhere. The decision should be made per requirement rather than assigning one label to the entire project.
| VTEX requirement | Standard Migration | Managed Migration | Add-ons | Custom Migration |
|---|---|---|---|---|
| Clean Products, SKUs, Categories, brands, Customers, and Orders | Suitable when supported and customer-led review is realistic | Useful when expert execution of agreed supported actions is needed; approval stays with the customer | Used only for bounded filtering, mapping, or supported configuration | Not normally required |
| Category-linked specifications and Product/SKU meaning | Suitable when source relationships are explicit and compatible | Expert execution can be included; catalog owners still interpret and approve samples | Can refine supported field placement or scope | Required when bespoke transformation or unsupported structures control the result |
| Marketplace sellers, offers, or external seller context | Suitable only when excluded or fully supported in the agreed path | Covers agreed supported Migration Actions, with seller coordination and setup separately owned | Not a substitute for marketplace reconstruction | Appropriate when seller, offer, commission, or ownership context needs tailored handling |
| Master Data or app-owned entities | Usually outside ordinary handling unless explicitly supported | Does not change capability boundaries | Not sufficient for unsupported data types | Appropriate when the entities and relationships require tailored review |
| ERP, PIM, OMS, WMS, CRM, or marketplace identifiers | Suitable when supported fields are sufficient and used only for reference | Expert execution can reduce action workload; system owners still verify their references | May map supported identifiers | Required when extraction, relationships or transformation exceed supported mapping and expressions; live workflow implementation is separately agreed |
| Storefront, checkout, pricing, promotions, logistics, and search | Target-side implementation rather than ordinary record migration | Expert execution covers agreed migration actions; implementation ownership remains separate | Limited to supported migration output | Custom Migration does not automatically implement the VTEX environment unless agreed |
This matrix prevents two opposite errors: escalating every enterprise feature to Custom Migration, or assuming that enterprise structures become compatible because the underlying Product and Order records are supported. The correct path protects the expected business outcome while keeping VTEX implementation ownership visible.
Signals That the Chosen Approach Is Too Light
A VTEX migration approach is too light when it treats enterprise structure as ordinary record transfer. The warning signs often appear in sample review, not in the first scope estimate.
| Warning signal | Likely response |
|---|---|
| Product/SKU relationships are unclear. | Strengthen catalog scope or review Custom Migration. |
| Specifications required for search or filters are missing or flattened. | Review Advanced Data Mapping when supported source fields need different VTEX destinations; use Custom Migration when the source meaning requires bespoke interpretation. |
| Pricing, promotions, or channel values do not preserve business meaning. | Separate migrated data from VTEX configuration and custom logic. |
| Marketplace or seller context is expected but not represented. | Review marketplace scope, target setup, or Custom Migration. |
| Master Data or external IDs are business-critical. | Review Custom Migration unless a supported mapping path is clearly available. |
| Storefront-sensitive data is approved only by product count. | Add URL, content, search, navigation, and SEO validation. |
| The merchant cannot name review owners. | Managed Migration may help execution, but scope and acceptance criteria still need to be defined. |
These signals should be resolved before Full Migration. Continuing with a weak approach usually turns preparation gaps into launch defects.
Conclusion
The right VTEX migration approach starts with the supported Product/SKU, specification, warehouse and channel meaning required by the business. Standard Migration fits customer-led supported actions; Managed Migration includes expert execution of those agreed actions. Add-ons provide bounded filtering, value changes and compatible field routing. Custom Migration handles requirements beyond those capabilities, with Self-Execute or Expert Handle explicitly chosen. Seller, Master Data and external-reference needs are evaluated per requirement rather than assumed custom from their labels.
Limited standard Demo evidence can reveal structural gaps and clarify the service decision. Enhanced or tailored data needs agreed paid proof, while channel availability, live prices, logistics and storefront behavior need separate implementation checks. Resolve unclear ownership or unsupported relationships before approving broader execution.
Common Questions
Is Standard Migration enough for a VTEX migration?
Standard Migration may be enough when supported records are clean, products and SKUs are predictable, customer and order data are standard, and the merchant can validate the result responsibly. Marketplace, Master Data, external identifiers, or bespoke logic should be reviewed before assuming Standard Migration is enough.
When should Managed Migration be chosen for VTEX?
Choose Managed Migration when VTEX scope is supported but expert execution of agreed Migration Actions is needed. The customer retains manual access, interprets the business requirements and verifies the final result. Catalog approval, launch coordination, seller onboarding and implementation remain separately assigned.
How are Add-ons different from Custom Migration for VTEX?
Add-ons apply supported filtering, value expressions and compatible field routing. VTEX does not support Advanced Database Mapping as Target. Custom Migration handles required extraction, Master Data or app relationships, marketplace reconstruction and bespoke logic beyond those capabilities. An external reference can fit supported mapping when its eligible destination and meaning are compatible.
What should Demo Migration prove before the VTEX approach is approved?
Demo can inspect limited standard Product/SKU, specification, Customer, Order or other supported samples available in the active path. It can diagnose scope gaps but cannot prove Add-ons or Customization, and Reviews and Coupons are excluded. Use paid activity for enhanced or tailored output; channel pricing, warehouse operations, seller behavior and storefront implementation need separate checks.
How should the Custom Migration starting price be interpreted?
For a VTEX migration, the displayed Custom Migration amount is the Standard Migration price floor for the selected Entity Points Plan, not a fixed final project price. The final total depends on the agreed VTEX-specific customization work, purchased Add-ons where applicable, Expert Handle when included, and other accepted scope-specific costs.
Does a valid VTEX SKU prove that a product is ready for its sales channel?
No. SKU identity, Product/SKU specifications, warehouse stock and trade-policy catalog, pricing and logistics context are related but separate. Confirm supported data output, then assign live channel configuration and checks. Changing execution responsibility cannot make an unqualified channel relationship valid.
Does preserving a VTEX external identifier automatically require Custom Migration?
No. An eligible compatible supported field can be enough for a reference value. Custom Migration is needed when required extraction, relationship reconstruction or bespoke transformations exceed supported capability. Reconnecting ERP, PIM, warehouse, marketplace or other live systems remains implementation work unless expressly agreed.