VTEX data-model planning should start with a translation question: which source records will become usable VTEX commerce structures, and which records belong to another VTEX domain, storefront implementation, integration, or external system? VTEX is a modular commerce environment, so data meaning is distributed across catalog, SKUs, specifications, pricing, promotions, checkout, orders, logistics, sellers, marketplace context, Master Data, search, storefront implementation, and external systems.
That makes VTEX different from platforms where product, customer, order, page, and URL data can be reviewed mostly as isolated records. A source product option may become a SKU, a specification, a storefront selection, a custom field, or a rebuild requirement. A source customer field may be ordinary profile context, Master Data, B2B-related information, CRM-owned identity, or integration metadata. A source order may preserve support value, but it does not automatically configure VTEX checkout, payment, fulfillment, marketplace, or logistics behavior.
The strongest VTEX migration scope is not the largest transfer. It is the scope that preserves useful data meaning while separating migrated records from VTEX setup, front-end implementation, integration ownership, structured mapping or dedicated target handling, and purpose-built mapping or restructuring requirements.
VTEX Data Meaning Is Distributed Across Commerce Services
VTEX data should be interpreted through the platform domain that owns it after migration. Catalog data may affect product display, search, pricing, promotions, SKU availability, logistics, and marketplace behavior. Order history may matter for service and reporting, but live order processing depends on checkout, payment, fulfillment, logistics, and operational configuration. Customer data may appear simple at first, while Master Data, segmentation, B2B context, CRM identifiers, or custom forms create separate decisions.
This distributed model changes migration review. A field that looked like an ordinary product attribute in the source store may be a specification in VTEX. A source variant may need SKU-level structure. A channel price may belong to pricing rules or price tables rather than the product record itself. A marketplace seller reference may not be ordinary catalog data. A content page may need storefront implementation or redirect planning rather than direct one-to-one migration.
| Source record or behavior | VTEX interpretation question | Migration implication |
|---|---|---|
| Product option or variant | Does it define a sellable SKU, a Product specification, or storefront choice behavior? | The Product–SKU–specification relationship must be explicit in scope. |
| Attribute or custom field | Is it used for filtering, product detail, operations, integration, or customer workflow? | Mapping depends on business use, not only field name similarity. |
| Channel price or promotion | Is it a base price, price table, sales-channel condition, coupon, or active promotion rule? | Commercial behavior should be separated from historical price data. |
| Customer extra field | Is it profile data, Master Data, B2B context, CRM metadata, or integration-owned information? | Some values may need bounded mapping or filtering, purpose-built mapping or restructuring, or external-system handling. |
| Order status or fulfillment note | Is it historical support context or live OMS/logistics behavior? | Order migration should not be treated as target workflow configuration. |
VTEX therefore requires meaning-first mapping. Each data area needs a declared future owner and purpose; that ownership determines whether a field belongs in migrated records, VTEX configuration, storefront implementation, integration data, a restructured target model, or deliberate exclusion.
Catalog Translation Starts With Category, Brand, Product, SKU, and Specification Relationships
VTEX Catalog is not a flat Product table. Its core structure links Categories, Brands, Products, SKUs, and specifications. A Product is the generic commercial definition, while each SKU represents the variation or physical unit that can be stocked and purchased. Category-linked specification groups define which Product and SKU properties apply, and those groups can inherit through Category levels.
| Source structure | VTEX interpretation | Relationship consequence |
|---|---|---|
| Parent Product with child variants | Product with one or more SKUs | The sellable identity, images, inventory, and Order lines belong at SKU level where appropriate. |
| Product attribute | Product specification | Preserve category-linked field and value meaning rather than copying free text. |
| Variant attribute such as size or voltage | SKU specification | Keep it attached to the SKU that represents the physical variation. |
| Brand or manufacturer | Brand relationship | Do not flatten the value when navigation or discovery depends on the Brand entity. |
| Category tree | Catalog classification | Category placement determines specification inheritance and Product organization. |
| Product image set | SKU media relationship | VTEX associates sellable availability and imagery with active SKUs. |
| Bundle, kit, or configurable assembly | Kit, attachment, assembly option, service, or external logic | Determine which VTEX structure actually owns the component and pricing relationship. |
A migration can preserve every source Product name and still produce a weak VTEX catalog if SKUs, specifications, images, Categories, and Brands no longer describe the same sellable item.
Specifications, Attachments, and Assembly Options Preserve Different Meanings
VTEX specifications are structured properties associated with Categories and applied to Products or SKUs. They can support navigation, comparison, selection, integration, or display. Their purpose is therefore as important as the value itself. A “color” field used for filtering is not automatically equivalent to a free-text color note; a size that distinguishes SKUs is not the same as a dimensional specification on the Product.
VTEX also separates specifications from optional Product customization structures. Attachments can collect information related to an SKU. Assembly options can represent more complex combinations, quantities, additional items, costs, and inventory relationships. Kits group SKUs sold together, while paid extras may be represented through SKU service structures. These concepts should not be collapsed into one generic “option” column.
| Source meaning | VTEX destination concept | Key distinction |
|---|---|---|
| Descriptive characteristic | Product specification | Describes the generic Product. |
| Variation-defining characteristic | SKU specification | Distinguishes the sellable unit. |
| Buyer-provided information | Attachment | Adds information to an SKU without necessarily creating another SKU. |
| Component or configurable combination | Assembly option | Represents additional items, quantities, costs, or inventory relationships. |
| Group of sellable units | Kit | Preserves a composition of SKUs sold together. |
| Paid extra associated with an item | SKU service relationship | Keeps the extra separate from the base SKU identity. |
The target model should preserve the structure that drives Product identity, buyer selection, inventory, and Order-line interpretation—not merely preserve labels and values.
Pricing, Promotions, Trade Policies, and Offers Form Separate Commercial Layers
A source export may place price, sale price, channel, marketplace, and availability values beside the Product record. VTEX separates those meanings across Catalog, Pricing, Promotions, trade policies, logistics, inventory, and seller offers. The same SKU can therefore participate in different commercial contexts without becoming multiple Products.
| Commercial record | VTEX meaning | Ownership consequence |
|---|---|---|
| Base or list price | Pricing relationship for an SKU | Price is not a permanent Product attribute. |
| Promotion or coupon outcome | Rule-driven commercial adjustment | Historical discount evidence on Orders is separate from active promotion rules. |
| Trade policy | Sales-channel context | Determines where Products or SKUs are available and can link commercial conditions. |
| Inventory and logistics | Availability and fulfillment promise | Stock and delivery meaning are owned outside the descriptive Catalog record. |
| Seller offer | A seller’s commercial offer for a catalog item | Marketplace identity and seller ownership remain distinct from the Product definition. |
| Channel-specific assortment | Product availability by trade policy or seller | Preserve the relationship rather than duplicating the Product. |
This layered model is especially important when the source Store uses regional catalogs, B2B price lists, marketplace offers, or ERP-led pricing. Migration should retain the identifiers that connect the SKU to its price, channel, seller, inventory, and logistics records.
Customers, B2B Records, and Master Data Require Explicit Identity
Customer-related data in VTEX can span shopper profiles, addresses, B2B organization structures, CRM identifiers, consent records, custom forms, and Master Data documents. Master Data is a native key-document database designed to store, search, expand, and personalize data, so a custom record can represent an operational object rather than an extra Customer field.
| Source record | Possible VTEX owner | Identity question |
|---|---|---|
| Shopper profile | Customer or profile data | Which email, document, or external key represents the person? |
| Address | Customer-related address record | Is it reusable account data, an Order snapshot, or both? |
| Company, organization, buyer role, or cost center | B2B domain or custom data model | Which relationships control access, approval, catalog, or price context? |
| Loyalty, CRM, or qualification value | Master Data or external CRM | Which system updates it and which key links it to the Customer? |
| Custom form submission | Master Data document | Is it a Customer attribute, a workflow record, or an independent entity? |
| Marketing consent | Customer or marketing-system relationship | Preserve purpose, timestamp, source, and legal meaning where required. |
Identity discipline prevents unrelated people, companies, addresses, and custom workflow records from being flattened into one profile. The migration model should define durable keys and relationship cardinality before selecting target fields.
Orders Preserve Commerce History Across Distinct Operational Domains
A historical VTEX Order can connect Customer identity, seller, trade policy, SKU lines, prices, promotions, taxes, payment evidence, shipping data, fulfillment, status, and external references. Those relationships explain the past transaction. They do not make current Checkout, Payments, OMS, Logistics, inventory, carrier, or warehouse configuration part of the Order record.
| Order-related value | Historical meaning | Separate live domain |
|---|---|---|
| SKU line and seller | What was purchased and from whom | Current Catalog and seller offers may change later. |
| Price and discount | Commercial snapshot | Active Pricing and Promotions rules are separate. |
| Payment transaction reference | Evidence of payment processing | Live gateway and antifraud configuration are separate. |
| Shipping method, SLA, and address | Historical delivery promise | Logistics, docks, warehouses, carriers, and pickup points are separate. |
| Status and fulfillment data | Past OMS state | New Orders can follow a different operational flow. |
| External Order ID | Cross-system lineage | Retain when ERP, marketplace, customer service, or reporting still uses it. |
The Article 3 boundary is the relationship model: which historical values remain attached to the Order and which live domains own future behavior.
Marketplace Catalogs, Sellers, and Offers Need Separate Ownership
VTEX can act as a marketplace, a seller, or part of a connected marketplace network. Marketplace data therefore includes more than Products and Orders. It can include seller identities, seller SKUs, catalog matches, offers, prices, inventory, commissions, fulfillment responsibility, Product and Category mappings, and external listing references.
| Marketplace layer | Meaning | Relationship to preserve |
|---|---|---|
| Canonical Product and SKU | Shared catalog identity | Seller offers should reference the intended catalog item. |
| Seller | Commercial and operational owner | Keep seller identity distinct from Brand, supplier, or manufacturer. |
| Offer | Seller-specific price, inventory, and fulfillment context | Do not merge all offers into the Product definition. |
| Catalog mapping | Relationship between external and VTEX Product/Category structures | Preserve the mapping key when the connector continues. |
| Marketplace Order origin | Channel and seller history | Retain where support, settlement, or reporting depends on it. |
| Commission or settlement reference | Marketplace financial context | Keep it with the system that owns settlement rather than forcing it into ordinary Order fields. |
A migration into VTEX should define whether each source marketplace record becomes a VTEX catalog relationship, seller offer, external connector record, historical Order attribute, or retained external-system object.
Storefront, CMS Pages, Blog Posts, Search, and URLs Should Be Separated From Core Data Transfer
VTEX storefront implementation may involve headless front ends, CMS components, search behavior, merchandising, redirects, and SEO continuity. A product can migrate into VTEX while the storefront experience remains incomplete. A CMS Page may carry content value but not have a direct one-to-one relationship with the target storefront implementation. Blog Posts may matter for organic traffic, but their handling depends on scope and platform setup.
For data-model planning, content and URL records should be evaluated by business role rather than record type alone. A source category URL may be a catalog path, a search landing page, a merchandising page, or an SEO asset. A content page may be a policy page, buying guide, campaign landing page, or custom layout. A search rule may be platform-native, app-owned, or implementation-specific.
| Source asset | VTEX planning question |
|---|---|
| Product URL | Should it redirect, remain equivalent, or be rebuilt through storefront routing? |
| Category or collection page | Is it catalog organization, navigation, search experience, SEO content, or merchandising? |
| CMS Page | Should it migrate as content, be recreated in the storefront, redirected, or retired? |
| Blog Post | Is it within migration scope, SEO scope, content strategy, or a separate CMS decision? |
| Search/filter logic | Is it driven by specifications, search configuration, app behavior, or custom implementation? |
This separation prevents Catalog records from being treated as complete while customer-facing discovery, content, and URL relationships remain unresolved.
External Systems and Custom Data Decide the Real Migration Boundary
VTEX migrations often involve ERP, CRM, PIM, OMS, WMS, marketplace middleware, payment providers, loyalty systems, tax systems, analytics, customer-service tools, and custom storefront applications. These systems may own product identifiers, prices, inventory, customer attributes, order references, seller data, fulfillment information, or custom records.
Migration scope must identify system ownership. If an ERP will overwrite a source value, that value matters only when it is needed as an opening state, historical reference, or reconciliation key. If an external ID must continue linking Orders, Customers, or Products across systems, preserving it may be critical. If a custom record supports a workflow that VTEX does not natively represent as standard commerce data, purpose-built mapping or restructuring may be needed.
| External or custom data type | Scope decision |
|---|---|
| ERP product or order ID | Preserve if required for reconciliation or synchronization. |
| PIM attribute set | Map only the values needed for VTEX catalog, specifications, or search. |
| CRM customer identifier | Preserve if customer-service or marketing workflows depend on it. |
| WMS or fulfillment reference | Decide whether it belongs to history, integration setup, or custom handling. |
| App or middleware data | Review supported migration behavior before assuming it can transfer. |
Bounded field mapping or filtering may help when the requirement involves supported filtering, mapping, or configuration. Purpose-built mapping or restructuring should be considered when the requirement involves unsupported data, custom records, bespoke transformation, custom source platform handling, or custom migration logic adjustment beyond supported behavior.
Ownership Boundaries Define the VTEX Migration Scope
VTEX scope is determined by ownership and relationships, not by record volume. A small catalog can be structurally complex when it depends on specification inheritance, assembly options, multiple trade policies, sellers, Master Data documents, or external identifiers. A large catalog can be comparatively straightforward when Products, SKUs, Categories, Brands, and specifications follow a consistent model.
| Source pattern | Core question | Scope consequence |
|---|---|---|
| Product with several purchasable variations | Which source object becomes the VTEX SKU? | Preserve parent Product, SKU identity, specifications, images, and inventory references. |
| Regional or B2B assortment | Which trade policy, price, and access relationship applies? | Keep commercial context separate from Product identity. |
| Custom Customer or workflow tables | Is the record a profile, Master Data document, B2B entity, or external-system object? | Model the entity and durable relationship rather than adding arbitrary Customer fields. |
| Marketplace catalog | Is VTEX the marketplace, the seller, or both? | Separate canonical catalog records from seller offers and mapping keys. |
| Headless or custom storefront content | Which CMS, app, or repository owns the content? | Do not treat storefront implementation as ordinary Catalog data. |
| ERP/PIM/WMS/OMS integration | Which system is authoritative for each value? | Retain cross-system IDs and ownership rules without duplicating external models. |
This boundary keeps the VTEX model coherent across Catalog, commercial, customer, marketplace, content, and operational domains.
Conclusion
VTEX distributes commerce meaning across related domains. Categories, Brands, Products, SKUs, and specifications form the Catalog; Pricing, Promotions, trade policies, inventory, logistics, and seller offers add commercial context; Customer and B2B records can extend into Master Data; Orders preserve historical relationships across Checkout, Payments, OMS, and fulfillment; storefront content and external systems retain their own ownership.
The migration model should therefore preserve keys and relationships rather than flattening every value into Products, Customers, or Orders. Clear ownership across VTEX domains is what allows a Product to remain discoverable, a SKU to remain sellable, an Order to remain understandable, a seller offer to remain attributable, and an external integration to continue referencing the correct record.
Common Questions
Why are SKUs so important in VTEX migration?
SKUs often control sellable versions, price, inventory, availability, logistics, and storefront choices. If source product options are not translated into usable VTEX SKU and specification structures, products may migrate but still fail commercial or operational expectations.
Do all source attributes become VTEX specifications?
No. Source attributes should be reviewed by purpose. Some belong as specifications, some define SKUs, some belong to content or integrations, and some should be excluded because they no longer support the target operation.
Can source promotions and price rules migrate as product fields?
Usually not. Promotions, coupons, price tables, sales-channel conditions, and external pricing logic should be reviewed separately from base product prices. Some values may be migrated as references, while active commercial behavior may require VTEX setup or integration work.
Are historical orders the same as VTEX OMS setup?
No. Historical Orders preserve past purchase context where supported. Live order processing belongs to current Checkout, Payments, OMS, Logistics, inventory, and seller configurations.
When does VTEX data need a separate entity model?
A separate entity model is needed when a source record cannot become a Catalog, Customer, Master Data, Order, CMS, seller, or external-system record without losing identity or relationships. Define the entity owner, key, and links before assigning individual fields.
How do trade policies and SKU relationships affect VTEX migration?
The Product supplies shared descriptive meaning, while SKUs represent sellable variations and trade policies can change assortment, price, logistics, or commercial context. Mapping should preserve those relationships so a record is not judged complete merely because the Product shell exists.