Moving commerce categories between SuiteCommerce sites looks simple until hierarchy, website assignments, URL components, and internal IDs enter the process. A CSV file can transfer the basic records, but it does not automatically recreate every dependency that makes a category work correctly in the destination account.
SuiteCommerce category import via CSV requires three controls: a reliable source-to-target field map, a staged parent-child import sequence, and a post-import check of website visibility and URLs. We recommend exporting the source Commerce Category records, replacing account-specific internal IDs with stable external IDs where appropriate, importing parent categories before child categories, and validating navigation, SEO fields, and storefront URLs before publishing the destination site.
This approach focuses specifically on moving category records between SuiteCommerce sites. For the broader process of copying configuration records and checking their dependencies, see our guide on SuiteCommerce configuration record copying without broken settings.
Why SuiteCommerce category migration needs more than a CSV export
A Commerce Category record is not just a label displayed in a navigation menu. It typically participates in several connected systems:
The category hierarchy, including parent and child relationships
Website or domain assignments
Storefront navigation and category landing pages
URL components and canonical paths
SEO title, description, and metadata fields
Category descriptions, images, and merchandising content
Item or commerce catalog associations
Visibility and publishing controls
The destination NetSuite account has its own internal IDs, website records, scripts, extensions, and configuration. An internal ID that represents a parent category in the source account does not represent the same record in the destination account. Importing that value without validating it can attach a child category to the wrong parent or cause the import to fail.
This is the main distinction between copying data and migrating a working commerce structure. The CSV contains values. The SuiteCommerce website depends on relationships among records.
The first information-gain detail to keep in mind is that parent category references are account-specific unless you deliberately create a stable cross-account identifier. A migration plan that relies only on source internal IDs is fragile. External IDs, controlled naming conventions, or a temporary mapping table provide a more dependable way to rebuild relationships in the target account.
What should you export from the source SuiteCommerce site?
Export the complete Commerce Category dataset that supports the storefront, not only the category names visible in the navigation menu. The precise fields available depend on the NetSuite account, enabled features, SuiteCommerce version, and record configuration, so verify the available fields through the CSV Import Assistant and the relevant saved search or export definition.
At minimum, review these categories of information:
| Data group | Examples of values to review | Why it matters |
|---|---|---|
| Identity | Name, external ID, internal ID | Identifies the record and supports mapping |
| Hierarchy | Parent category, level, path | Rebuilds the category tree |
| Website relationship | Site, domain, catalog, visibility | Determines where the category appears |
| URL behavior | URL component, slug, path | Protects storefront links and redirects |
| Content | Description, images, merchandising text | Preserves the landing page experience |
| SEO | Page title, meta description, keywords where supported | Maintains search-oriented content |
| Status | Inactive, hidden, published, display settings | Prevents unintended storefront exposure |
Do not assume that every field shown in the source account is importable. Some values are calculated, system-controlled, or dependent on a record that must already exist in the destination account. A field that exports successfully can still be read-only during import.
Before building the final file, perform a small export and compare the column headers with the fields offered by the target account’s Import Assistant. This catches differences in account configuration before the migration file becomes difficult to audit.
How do you prepare a Commerce Category CSV for import?
Preparation should convert source-account references into destination-safe values. The file should not be treated as a direct copy if it contains source internal IDs, source website references, or parent values that do not exist in the target account.
Create a mapping workbook alongside the CSV. It should identify the source category, its intended target category, the parent relationship, the website assignment, the URL component, and the validation status. This mapping is especially important when the destination site has a different hierarchy or when some categories already exist.
A practical preparation process includes the following steps.
1. Confirm the target record type
Open the CSV Import Assistant in the destination NetSuite account and confirm that the expected Commerce Category record type is available. Record names and import capabilities vary by enabled features and SuiteCommerce implementation, so do not rely on a file created for another account.
Confirm whether the import supports:
Creating new category records
Updating existing categories
Using external IDs for matching
Importing parent relationships
Setting website or catalog associations
Updating URL-related fields
Importing descriptions and SEO content
If a field is not available in the target import mapping, do not place it in the file and assume it will be processed. Remove it from the transactional import and plan a separate supported method, such as a different record update, a script, or manual configuration.
2. Normalize the category identity
Use a stable external ID convention that is unique across the target account. A useful convention identifies the site and category path without depending on a source internal ID. For example, an external ID might reflect a business-defined category key rather than a numeric database value.
Avoid changing the external ID after the initial test import. It becomes the key used to identify records during later updates and repeatable migration runs.
Names alone are not sufficient identifiers. Two categories can share similar names under different parents, and a category name can change for merchandising reasons. The external ID should remain stable even when the display name changes.
3. Replace source parent references
A child category should point to the destination parent record, not the source parent internal ID. Build the parent mapping before importing any children.
For example, if “Safety Equipment” is the source parent and “Protective Gloves” is its child, the target file must reference the target record created for “Safety Equipment.” If the target parent already exists, use its valid target identifier. If it does not exist, import it first.
4. Check URL components independently from names
Category names and URL components serve different purposes. A name can change without necessarily changing the desired URL, while a URL component can create a storefront path conflict even when the category names look correct.
Review every category for:
Duplicate URL components
Invalid characters
Leading or trailing spaces
Unexpected capitalization
Existing destination paths
Changes that would require redirects
Do not automatically regenerate URL components from category names. That approach can create unnecessary URL changes and weaken existing search visibility. Preserve the intended path when the destination structure supports it.
How should you import parent and child categories?
Import parent categories first, then import child categories in one or more controlled passes. This is the safest way to ensure that every child record can resolve its parent relationship in the target account.
A reliable sequence is:
Import top-level categories without child references.
Confirm that the top-level records were created or updated correctly.
Import the next hierarchy level using destination-safe parent identifiers.
Continue through deeper levels.
Re-run validation after the final level is loaded.
Do not import the entire hierarchy in one file unless the target account demonstrably resolves parent references through the selected external ID or mapping method. A single-file import can work in some configurations, but it makes troubleshooting harder because an early parent failure affects every dependent child.
The Import Assistant’s matching behavior also matters. Decide whether the operation should add new records, update records, or perform both. A file intended to update existing categories should not be run as an add-only import, and an initial migration should not overwrite production categories without a clear matching rule.
Use a small test batch first. Include one top-level category, one child category, one inactive category if applicable, and one record with the content and SEO fields used by the storefront. This test reveals whether the destination account accepts the record type and whether the hierarchy and website relationships behave as expected.
Which fields require special attention during SuiteCommerce category import?
Some fields create more risk than others because they depend on account structure or storefront behavior.
Website and domain assignments
A category may be valid in NetSuite but invisible on the storefront if it is not associated with the correct website, domain, catalog, or visibility configuration. Confirm the target site’s expected assignment before importing.
Do not copy a source website internal ID into the destination. Map the source site to the corresponding target website record. If the destination contains multiple sites, document which categories belong to which site before the import begins.
Parent category
Parent values control navigation and landing page paths. A category placed under the wrong parent can appear operational while producing an incorrect customer journey and URL structure.
Validate both the direct parent and the full path. A child with the correct immediate parent can still be wrong if that parent sits under an unintended top-level category.
URL component
The URL component should be tested in the actual storefront, not only checked in the CSV. SuiteCommerce routing and category path behavior depend on the website configuration and hierarchy. A file can contain a valid-looking slug while the published site produces an unexpected path.
Record the intended URL for each migrated category. This creates a baseline for post-import validation and makes it easier to identify changes that need redirects.
Images and file references
Images may use file cabinet references that do not exist in the destination account. A category import can complete while the image field remains empty, points to an unavailable file, or references a different asset.
Migrate or confirm the required file cabinet assets separately. Then validate image URLs and storefront rendering at desktop and mobile breakpoints.
SEO fields
Preserve page titles and meta descriptions when the destination site is intended to retain the source site’s search structure. Also check whether the new domain, brand, product assortment, and regional language require updated content.
SEO fields should not be copied blindly when the target site serves a different audience. The migration should preserve structure while allowing content owners to approve changes that are intentional.
What should you validate after the import?
A completed import is not proof that the category migration succeeded. NetSuite may report that records were processed even though website visibility, navigation, content, or URLs still require attention.
Validate the migration at three levels.
Record validation confirms that each expected Commerce Category exists, has the correct external ID, and contains the intended name, parent, status, website assignment, and content.
Relationship validation confirms that the hierarchy is intact. Check top-level categories, intermediate levels, leaf categories, duplicate parents, orphaned records, and categories assigned to the wrong website.
Storefront validation confirms that users can reach the categories through navigation and direct URLs. Test category landing pages, breadcrumbs, images, SEO metadata, search behavior, filters, and links from related content.
Create a comparison report that includes source value, target value, and validation result. A simple report with statuses such as “matched,” “intentionally changed,” “missing,” and “needs review” provides a much stronger audit trail than relying on the import summary alone.
Also review the browser response for old and new URLs. A category that returns a 404, redirects unexpectedly, or resolves to the wrong landing page requires correction before launch. If URLs changed intentionally, define redirects through the supported SuiteCommerce or NetSuite configuration rather than relying on customers to discover the new path.
Should scripts and workflows run during a category CSV import?
Only enable automation when you understand how it affects category records. Server-side SuiteScript, workflows, user event logic, and other automation can change values, reject records, create related records, or apply business rules during an import.
NetSuite provides CSV import controls for server-side scripts and workflow triggers. The setting and role permissions should be reviewed before a production run, especially if the account uses automation to control website visibility, data standards, or record approvals. Our guide to scripts and workflows during NetSuite CSV imports explains why these controls affect import outcomes.
Use the test batch to determine whether automation is required. If scripts should run, confirm that they produce the expected values and do not introduce unintended updates. If scripts should not run, document the setting and confirm that disabling them does not bypass required validation.
The goal is not to turn automation on or off by default. The goal is to make the import behavior intentional and repeatable.
Common failure points in SuiteCommerce category migration
The most common problems are mapping and dependency failures rather than CSV formatting errors.
Source internal IDs are reused in the destination. This creates missing or incorrect parent relationships because internal IDs belong to one NetSuite account.
Child categories are imported before parents. The import cannot resolve the hierarchy, leaving orphaned categories or rejected rows.
Website assignments are assumed rather than mapped. Records exist in NetSuite but do not appear on the intended SuiteCommerce site.
URL components are regenerated without review. Categories load successfully, but existing paths change and links break.
Inactive and hidden records are treated as errors. Some categories are intentionally unavailable to customers. Their status should be compared with the source business rules before being changed.
The import is tested only in the record list. A category record can look correct in NetSuite while its storefront navigation, breadcrumb, image, or URL is wrong.
A controlled migration separates data correctness from storefront correctness. Both must pass before the categories are considered ready.
When is CSV the right method for moving SuiteCommerce categories?
CSV is appropriate when the category structure is manageable, the target account supports the necessary record type and fields, and the migration team can create reliable mappings. It is also useful for repeatable updates when external IDs and validation procedures are already established.
CSV is less suitable when the migration involves extensive restructuring, complex dependencies, large-scale content transformation, multiple websites, or a need for automated repeatability across environments. In those cases, a scripted migration or integration layer may provide better control.
Our NetSuite integration platform services support API-based and automated data movement when manual CSV processing no longer provides sufficient consistency. The appropriate method depends on the number of records, dependency complexity, audit requirements, and whether the process will be repeated.
If the category structure is changing at the same time as the account migration, treat the work as a transformation project rather than a simple export and import. Define the future hierarchy first, then map source categories to their intended target records.
Conclusion
A SuiteCommerce category CSV import succeeds when it recreates the relationships that make the storefront work, not merely when the file uploads without errors. Map identifiers deliberately, create parents before children, verify website assignments, preserve URL intent, and test the actual storefront before publishing.
For complex migrations, automated synchronization, or a target account with significant customization, contact Versich to discuss the mapping, migration method, and validation plan. A controlled process protects navigation, search visibility, and the customer experience while giving your team a repeatable way to manage future category updates.
