A SuiteCommerce facet displaying a field ID name instead of a customer-friendly label usually indicates a mapping problem between the NetSuite item field, the SuiteCommerce facet configuration, and the storefront’s search or display layer. The field exists and may filter products correctly, but SuiteCommerce is rendering the internal field ID, such as `custitem_product_material`, instead of a label such as “Material.”
The fix is to separate three values that are frequently treated as if they were the same: the NetSuite field ID, the storefront facet label, and the indexed facet value. Confirm the field used by the facet, assign a customer-facing label in the active SuiteCommerce configuration, verify that the search index exposes the expected metadata, then clear the relevant cache or redeploy the configuration before testing the live storefront. If the label is controlled by custom JavaScript or a theme template, update that presentation layer as well.
This issue is different from a general facet URL configuration problem. For the broader setup process, see our guide on configuring SuiteCommerce facet URLs without SEO problems. This article focuses specifically on diagnosing why a working or partially working facet exposes an internal field name to shoppers.
Why does a SuiteCommerce facet display the field ID name?
A SuiteCommerce facet displays a field ID when the storefront does not receive, recognize, or apply a separate display label for the facet field. The field ID is the technical identifier used by NetSuite and the commerce search configuration, while the display name is the human-readable text intended for shoppers.
For example, a NetSuite item field might contain:
Field ID: `custitem_finish_type`
NetSuite label: Finish Type
SuiteCommerce facet label: Finish
Facet values: Matte, Gloss, Brushed
If the storefront receives only `custitem_finish_type` and no usable label, it may render that internal identifier in the filter heading. A similar problem occurs when custom code derives the visible name directly from the field key instead of reading the configured facet label.
The field itself is not necessarily broken. In many cases, the search service returns valid product results, the facet counts are present, and only the presentation metadata is missing or mismatched. That distinction matters because changing the item field, URL component, or stored values without checking the display mapping can create a larger catalog problem.
How SuiteCommerce separates field IDs, labels, and facet values
SuiteCommerce uses several layers to turn a NetSuite field into a storefront filter. Understanding those layers makes the problem easier to isolate.
The NetSuite field ID identifies the source field. Standard fields have platform-defined identifiers, while custom item fields commonly use IDs beginning with `custitem_`. This identifier is useful for configuration and integration work, but it is not suitable as a shopper-facing label.
The facet definition tells SuiteCommerce which field should appear as a filter and how the filter should behave. Depending on the implementation, this configuration may be held in commerce configuration records, extension configuration, theme settings, or custom code.
The display label is the text shown in the facet heading. It should be independent of the field ID so that the technical identifier can remain stable while the customer-facing wording changes.
The indexed value is the information used to filter products. A list or record field might return an internal value, a display value, or both. If the storefront has no mapping from the returned value to its display text, shoppers might see a numeric internal ID or an untranslated value inside the facet options.
The rendering layer produces the final HTML visible in the browser. In SuiteCommerce implementations, this may involve templates, view models, theme code, or custom extensions. A correct configuration can still appear wrong if custom presentation code prints the raw field key.
This separation provides an important diagnostic rule: a field ID showing as a facet heading points primarily to label metadata or rendering, while a numeric value showing as a facet option points more directly to value mapping or search-index metadata.
What should you check first?
Start in the browser, not in the NetSuite record. The storefront reveals whether the issue affects the facet heading, the option values, the URL, or all three.
Open the affected category or search results page and inspect the facet in both desktop and mobile layouts. Record exactly what appears:
Is the heading the internal field ID?
Are the selectable values readable?
Does selecting a value filter the catalog?
Does the URL use a readable component or an internal identifier?
Does the problem occur on one facet or every custom facet?
Does the issue appear in the preview environment, production, or both?
Use the browser’s developer tools to inspect the data returned to the page. Look for the facet field identifier, label, selected value, and display value in the relevant network response or rendered page data. The exact response structure depends on the SuiteCommerce implementation, but the objective remains the same: determine whether the label is absent from the response or ignored by the storefront.
If the response already contains “Finish” but the page displays `custitem_finish_type`, the rendering layer is likely overriding or bypassing the configured label. If the response contains only the field ID, investigate the active facet configuration and search metadata before changing templates.
Confirm that the facet points to the intended NetSuite field
A common cause is a facet definition that references the wrong field. This happens after a custom field is replaced, duplicated, renamed, or copied between environments.
Check the field ID in the facet configuration against the actual item field record. Do not rely only on the field’s visible label because multiple fields can have similar names, and the label may have changed while the internal ID remained the same.
Confirm all of the following:
The field exists in the target NetSuite account.
The field is applied to the intended item types.
The field is available to the storefront catalog and item search process.
The facet references the correct internal ID.
The field is not an obsolete version left behind after a catalog redesign.
The field has values on the items expected to appear in filtered results.
A custom field can exist on an item record without being available to SuiteCommerce search or facet processing. Availability depends on the account configuration, item data exposure, search indexing, and the way the storefront is implemented.
This is also where field type matters. A free-form text field, list or record field, checkbox, and multi-select field do not behave identically in a catalog filter. A list or record field may have a separate internal value and display text. A multi-select field may require special handling because one item can contribute more than one facet value.
Set a customer-facing facet label independently
The most direct fix is to configure a customer-facing label rather than allowing the storefront to fall back to the field ID.
Use concise wording that describes what the shopper is filtering. For example, `custitem_power_rating` should not appear in the interface. Depending on the catalog, the appropriate label could be “Power Rating,” “Wattage,” or “Output.”
Keep the technical field ID stable unless there is a compelling data-model reason to change it. Changing the field ID creates unnecessary risk for saved searches, scripts, integrations, imports, analytics, and existing configuration. A label change is a presentation decision. A field ID change is a structural decision.
Also check whether the active configuration has separate labels for different contexts. A SuiteCommerce implementation may distinguish between:
The facet heading
The field label
The URL component
The selected filter summary
The mobile filter label
Accessibility text
Breadcrumb or applied-filter text
Updating only the NetSuite field label might not update all of these areas. The storefront may use a specific facet label stored in commerce configuration instead of reading the standard NetSuite field label.
If the configuration includes both a field reference and a display label, make sure the label belongs to the active facet record and not to an unused definition. Duplicate facet records, environment-specific settings, and extension overrides can make an apparently correct change ineffective.
Check whether custom code is printing the raw field key
If the label is present in the configuration or response but the storefront still shows the field ID, inspect custom code before changing the NetSuite field.
A custom extension may build a facet object using a property such as `fieldId`, `id`, or `facetField` and then print that property as the visible heading. The code may have been written for an earlier configuration format in which the field ID and label happened to match.
Look for code that:
Uses the field identifier as a fallback without checking for a configured label
Converts an internal ID into a title by replacing underscores
Reads a field key from the URL and displays it directly
Overrides the standard facet view or template
Applies different logic to desktop and mobile facet controls
Uses a hard-coded list of facet fields
Translates only standard fields and ignores custom fields
A safe presentation rule is to use the configured customer-facing label first, then a valid NetSuite field label, and use the internal field ID only as a diagnostic fallback. The fallback should not be visible to shoppers in a finished storefront.
Avoid fixing the problem by hard-coding one label into a template unless the facet is genuinely static. A hard-coded label becomes inaccurate when the field is reused, renamed, localized, or replaced. Configuration-driven labels are more maintainable and reduce the chance that the same defect appears in another facet.
Verify indexed metadata and display values
A SuiteCommerce facet depends on more than the item record. The storefront must receive usable field and value metadata through its search process.
If the facet heading is correct but its options display as numbers or internal record IDs, inspect the indexed values. A list or record field can have a stored internal value and a separate display name. The storefront needs the display representation if shoppers are expected to see names such as “Stainless Steel” rather than an internal record number.
Check whether:
The field is included in the item search or catalog index
The index was refreshed after field values or labels changed
The search response includes both value and display text
The field uses a list, record, or multi-select source
The field is translated or localized
The facet configuration expects a slug but receives an internal value
A custom extension transforms values before rendering
A reindex or catalog refresh is important after changing field availability, list values, or searchable metadata. The exact command and deployment process depend on the SuiteCommerce version and account setup, so follow the implementation’s established release process rather than assuming that saving the NetSuite field immediately changes the storefront.
Do not confuse a stale index with a missing label. If the response has an old label, refresh the relevant index or cache. If the response never includes a label, correct the configuration or data mapping first.
Test the fix in a controlled sequence
Changing several layers at once makes the cause difficult to prove. Test one layer at a time and record the result.
Confirm the source field and its internal ID.
Confirm the intended customer-facing label in the active facet configuration.
Confirm the field and label in the storefront response.
Check the rendered facet in a private browser session.
Test the filter with one value and confirm the result set changes.
Test the generated URL and applied-filter text.
Test desktop and mobile presentations.
Refresh the relevant cache, index, or deployment artifact if the old label remains.
Use a private browsing session or clear the appropriate browser cache during testing. Browser caching is not the only cache involved. SuiteCommerce environments may also cache configuration, search responses, static assets, or rendered application files. A label change that is correct in source configuration can remain invisible until the changed asset or configuration reaches the storefront.
Test more than one product and more than one value. A facet can appear correctly while filtering only items with a particular value. Include an item with no value, an item with one value, and, where relevant, an item with multiple values. This verifies that the display fix did not conceal a separate data-quality or indexing problem.
Common fixes that create new SuiteCommerce problems
Some quick fixes appear to work but introduce maintenance or SEO issues.
Renaming the field ID is rarely the right response. Internal IDs support configuration and integrations, so changing them can break references that are not visible in the storefront.
Editing only the HTML in the browser proves that the label can be changed visually, but it does not correct the source configuration. The next deployment will remove the change, and other templates may continue to show the field ID.
Using the field ID as the URL component does not solve a display-label problem. A URL component is a routing and shareability decision. The facet heading is a presentation decision. They should be reviewed together, but they are not interchangeable.
Changing all facet settings at once makes troubleshooting harder. It can also alter URL behavior, selected values, sort order, or crawlable page variants when the original defect was only a missing label.
Forcing display values in a template can hide a search-index problem. If the index returns only internal values, update the field mapping or indexing process rather than maintaining a fragile lookup table in front-end code.
The safest repair preserves the field ID, corrects the label source, confirms the search metadata, and tests the deployed storefront from the shopper’s perspective.
How to prevent field ID display problems in future releases
Treat facet labels as part of the storefront’s configuration contract. Document each facet with its source field ID, customer-facing label, field type, value source, URL component, and intended visibility.
Include facet validation in release testing. A simple checklist should confirm that every customer-facing facet:
Uses a readable label
Displays readable option values
Filters the expected products
Produces a stable URL
Shows the correct applied-filter summary
Works on mobile and desktop
Does not expose internal IDs in visible text or accessibility attributes
Use separate configuration validation for standard and custom fields. Custom fields are more likely to expose differences between NetSuite record labels, search-index metadata, and SuiteCommerce presentation logic.
It is also useful to monitor for raw identifiers in storefront output. Search rendered HTML, application data, and screenshots for patterns such as `custitem_`, `custbody_`, or unexpected numeric record IDs. This catches regressions that manual testing of only the most popular facets can miss.
For broader NetSuite data structure, catalog, and ecommerce configuration support, our NetSuite consulting services provide a wider implementation context. Facet presentation problems frequently cross the boundary between item data, commerce configuration, search behavior, and front-end code, so resolving them at the correct layer matters.
When should you involve a SuiteCommerce developer?
Involve a developer when the configured label exists but the storefront still renders the field ID, when the behavior differs by device or template, or when custom extensions alter facet data. These symptoms indicate that the presentation layer may be bypassing standard configuration.
Technical support is also appropriate when:
The facet works in one environment but not another
A deployment changes the label unexpectedly
The search response lacks the field or display value
Multiple fields share similar labels
A multi-select or record field returns unusable values
The issue affects URL generation and visible labels together
Reindexing does not update the storefront
The facet is localized and only one language exposes the ID
Before escalating, capture the field ID, configured label, affected URL, environment, browser, response payload if available, and the exact visible text. That evidence shortens diagnosis and prevents repeated checks of the wrong configuration layer.
If you need help tracing the issue from NetSuite field configuration through SuiteCommerce search and storefront rendering, contact Versich with those details.
Conclusion
A SuiteCommerce facet displaying a field ID name is usually a metadata or presentation mismatch, not proof that the underlying NetSuite field is unusable. Start by separating the internal field ID, customer-facing facet label, indexed value, and rendering layer. Confirm the source field, configure the visible label independently, inspect the storefront response, check custom templates or extensions, and refresh the appropriate cache or search artifact.
The durable fix preserves technical identifiers while making shopper-facing labels configuration-driven and testable. That approach corrects the immediate display problem without creating unnecessary changes to item data, URLs, integrations, or search behavior.
