SuiteCommerce Developer common mistakes
SuiteCommerce Developer · Understand the traps and how to avoid them.
Treating the Site Builder 'theme' as the place where all customization lives, and editing theme files for logic that actually belongs in a custom module or extension.
Site Builder themes are presented prominently in the admin UI, so candidates assume theme = application code. In practice the theme controls templates, Sass, and configuration, while behavior belongs in SuiteScript, custom modules, or extensions.
What to do instead
Before editing anything, classify the change: presentation (theme templates/Sass), configuration (Site Builder settings, facets, search), or behavior (SuiteScript/custom module/extension). Put logic in the correct layer and keep theme edits limited to markup, styling, and template bindings.
Assuming a single deployment covers all environments and that code pushed to production automatically matches sandbox behavior.
Candidates confuse the file-based customization model with a full CI pipeline. SuiteCommerce uses SCA/SSP deployment bundles and theme/extension activation steps, and each account has its own file cabinet and deployment state.
What to do instead
Learn the deployment path explicitly: develop in sandbox, deploy the customization bundle, activate the theme or extension, then verify in the target account. Account for per-account differences in configuration, catalog, and file cabinet paths before promoting.
Writing SuiteScript that queries the item record directly for pricing or availability instead of using the commerce search/index layer.
Developers used to ERP-side SuiteScript reach for nlapiSearchRecord or record.load on items. On the storefront, high-volume catalog and search paths are served by the search index, so direct record queries are slow and can bypass intended visibility rules.
What to do instead
Use the commerce search APIs and indexed fields for catalog listing, faceting, and search. Reserve record loads for single-record detail operations, and cache or batch any unavoidable record access.
Hard-coding record IDs, internal IDs, or account-specific URLs inside templates or frontend modules.
Sandbox data is convenient to reference directly, and it 'works' during development, so the value never gets parameterized. It breaks on promotion because IDs differ across accounts and environments.
What to do instead
Resolve IDs at runtime via configuration records, custom fields, or lookup by external ID/name. Expose environment-specific values through Site Builder configuration or a custom config record rather than literals in code.
Overriding a core template or core module by copying it wholesale and editing the copy, then losing upstream fixes.
Copy-paste is the fastest way to get a change working, and the platform allows template overrides. Candidates do not consider upgrade and maintenance impact.
What to do instead
Prefer the extension/plugin mechanism and targeted template overrides that call the parent or include the original. Keep overrides minimal, document every overridden file, and re-check overrides after platform updates.
Confusing the roles of SSP application, extensions, and Site Builder themes when troubleshooting why a change does not appear.
Each layer has its own activation and caching behavior. A change may be deployed but not activated, activated but cached, or applied to the wrong site/domain.
What to do instead
Build a troubleshooting checklist ordered by layer: is the file deployed, is the extension or theme activated for this site, is the touchpoint/domain mapping correct, and has the cache been invalidated? Verify each step before changing code.
Ignoring the asynchronous and client/server split in frontend customization, mutating models directly and expecting immediate persistence.
The frontend uses a modular architecture with models, collections, and views plus backend services. Candidates treat it like plain DOM scripting and mutate data without going through the proper API or save call.
What to do instead
Follow the module pattern: extend the appropriate view/model, use the provided APIs and events, and trigger persistence through the documented service calls. Test with network throttling and confirm the backend call actually fires.
Deploying SuiteScript with incorrect execution context or entry point for the storefront, such as using a user-event script where a service or RESTlet is required.
Candidates memorize script types generically and do not map them to how the storefront calls backend logic. The wrong script type deploys fine but is never invoked, or fails under shopper permissions.
What to do instead
Map each requirement to the correct script type and context: service scripts for checkout/cart flows, RESTlets or custom modules for extension backends, and scheduled or map/reduce for batch work. Confirm the deployment's audience, role, and status.
Skipping permission, role, and audience configuration on script deployments and then debugging 'it works for admin but not shoppers'.
Administrators have broad permissions, so tests pass in the admin session. Shopper and logged-in customer roles have narrower access to records and script deployments.
What to do instead
Test every change while logged in as the actual target role in an incognito session. Set deployment audience and permissions deliberately, and grant only the record-level permissions the script truly needs.
Treating caching as an afterthought, so catalog, search, or content changes appear stale and candidates misdiagnose it as a code bug.
SuiteCommerce caches pages, search results, and content aggressively for performance. Candidates change code or data repeatedly without invalidating the relevant cache, then chase phantom failures.
What to do instead
Know which cache applies to each surface (page, search index, content) and how to invalidate it. After data or config changes, clear the relevant cache and re-test; when diagnosing, confirm whether the issue reproduces with cache bypassed.