SuiteScript Migration
Every script on SuiteScript 2.1 before 2028.2 — converted or retired, and tested before it ships.
The SuiteScript 2.1 deadline
Oracle is retiring SuiteScript 1.0, 2.0 and 2.x. By the 2028.2 release, every script in every account has to run on SuiteScript 2.1 — not just the ones that matter.
- 2026.2
- SuiteScript 2.1 becomes the standard for new and existing scripts.
- 2027.1
- SuiteScript 1.0 support narrows to critical issues. Anything else, Oracle asks you to convert to 2.1 first.
- 2028.1
- SuiteScript 1.0 can no longer be deployed in new accounts. SuiteScript 2.0 and 2.x scripts run as 2.1 by default — whether or not anyone has tested them.
- 2028.2
- All new and existing scripts must use SuiteScript 2.1.
Oracle’s own AI tooling doesn’t vouch for its output either. The SuiteScript Upgrade agent skill says its “validation is a static migration check, not a substitute for functional testing,” and Oracle’s Developer Assistant guidance says to “never deploy assistant-generated code directly to a production environment.”
Sources — Oracle NetSuite Help Center
- Transitioning To SuiteScript 2.1
- Differences Between SuiteScript 2.0 and SuiteScript 2.1
- SuiteScript 1.0 APIs Not Directly Mapped to a SuiteScript 2.1 Module
- Updating Scripts Using the SuiteScript Agent Skill
- Best Practices for SuiteCloud Developer Assistant
- Choosing A Migration Path
- Enabling SuiteScript 2.1 at the Account Level
What changes underneath
Changing @NApiVersion to 2.1 moves a server script onto a different JavaScript engine. Oracle documents the differences. These are the ones I measured on NetSuite 2026.2, running the same code under both versions, plus one gap Oracle documents.
- RESTlet responses
- A RESTlet POST that returns JSON.stringify("flower") sends 12 characters under 2.0 and 8 under 2.1. Both return HTTP 200, so nothing fails inside NetSuite; the break shows up in whatever calls it.
- Error messages
- JSON.stringify(new Error("msg")) gives {"message":"msg"} under 2.0 and {} under 2.1. A script that logs errors that way keeps running and stops recording why.
- Field values
- Setting 616.00 on a free-form text custom field saves 616.0 under 2.0 and 616 under 2.1.
- Dates
- toLocaleDateString() returns “December 21, 2012” under 2.0 and “12/21/2012” under 2.1.
- Syntax that no longer parses
- for each…in, conditional catch blocks and a variable named extends become syntax errors. project:validate passes them; the deploy fails when NetSuite creates the script record.
- APIs with no 2.1 equivalent
- Oracle lists 24 SuiteScript 1.0 APIs with no direct 2.1 mapping, including nlapiYieldScript, nlapiSetRecoveryPoint and the time-zone-aware date-time functions. Those need a different implementation, not a find-and-replace.
Where the documentation and the account disagree
The account preference “Execute SuiteScript 2.0 Server Scripts as 2.1” lets you try the 2.1 runtime without editing code. Oracle says that if a script doesn’t validate, it “continues to run as SuiteScript 2.0.” In my test account, three working 2.0 Suitelets with 2.1-invalid syntax, uploaded while the preference was off, didn’t: each failed with a SyntaxError instead. With the preference off again, the one I re-ran worked. Try it in a sandbox, not production.
Measured on 2026-10-21 in a NetSuite 2026.2 test account. Method and full results: Changing @NApiVersion is the easy part
A SuiteScript 1.0 rewrite, in production
A client’s royalty and third-party-cost engine, written mostly in SuiteScript 1.0, rebuilt on 2.1 and now live in production.
- It started as about 1,080 lines of SuiteScript 1.0, not counting libraries: six user event scripts, a client script, two scheduled scripts, a Suitelet and a Custom GL Lines plugin, plus mass updates (three already on 2.x) and two bundled libraries.
- Six files were retired instead of converted: three one-time mass updates that had already run, a delete helper and both libraries. One more script turned out to be dead code in the old system too.
- The rest was rebuilt in TypeScript compiled to SuiteScript 2.1. Saved searches became SuiteQL, the scheduled-script queue became per-record processing, the GL plugin’s logic moved into a user event, and there are no runtime dependencies.
- A written, line-by-line parity audit compared every legacy file against the new code: 85 exact matches, 38 documented intentional changes and no regressions found.
- Test coverage is held at 100%: branches, functions, lines and statements.
- An adversarial code review caught a caching change that would have overbilled the second of two sliding-scale fees sharing the same tool and licence. It was fixed before deploy.
- Users used to click a button and wait for a scheduled script to pick the order up. Now the work finishes in the same request and the page refreshes with the result.
It isn’t the only one. I’ve worked in NetSuite for more than fifteen years, converting scripts and SuiteApps along the way.
The free migration audit
Every migration starts here. It costs nothing, has no size cap, and ends with a fixed quote for the conversion.
- An inventory of every script: type, API version, and whether it’s deployed
- A convert-or-retire recommendation for each one
- Risk flags: SuiteScript 1.0 APIs with no 2.1 equivalent, scripts annotated 2.x, and bundles or SuiteApps you don’t own
- A fixed quote for the conversion
All it needs is access to a sandbox.
More than a version bump
Long-running accounts carry a decade of scripts, and not all of them still matter. Three solutions to the same problem. Code paths nobody deletes because nobody is sure what calls them. Converting all of it line for line means paying to migrate code you should retire. The migration is the moment to remove that liability.
What's included
- Conversion of SuiteScript 1.0, 2.0 and 2.x scripts to 2.1 — every script converted or retired before the 2028.2 cutoff
- Consolidation of duplicated customizations
- Dead-code removal, with evidence of non-use
- Refactoring toward governance-aware patterns: Map/Reduce where appropriate, deferred execution, idempotent integration jobs
- Test scaffolding where it makes economic sense
Deliverable
Working code in your account, with a written summary of what changed and why. Each change reviewable as its own atomic unit.
Ideal fit
- Your account still runs SuiteScript 1.0, 2.0 or 2.x scripts, and 2028 is closer than the backlog
- You spend more time managing the customization layer than building on it
- Every new feature collides with old code in unexpected ways
- You've already audited (here or elsewhere) and now want execution
Questions
- Do 2.0 scripts really need migrating, if the API is the same?
- Yes. Oracle says all new and existing scripts must use SuiteScript 2.1 in 2028.2, and support for 2.0 and 2.x is expected to be removed then. The modules are largely the same; the engine underneath isn’t, and that’s where the differences above come from.
- What happens at 2028.1 if we do nothing?
- Oracle’s timeline says SuiteScript 2.0 and 2.x scripts run as 2.1 by default from 2028.1, and SuiteScript 1.0 can no longer be deployed in new accounts. Untested scripts start running on the new engine anyway.
- Is @NApiVersion 2.x the same as 2.1?
- No. Oracle treats 2.x as a legacy annotation alongside 2.0, expected to lose support in 2028.2. To use 2.1 syntax, the annotation has to say 2.1.
- Can’t Oracle’s AI agent skill convert everything for us?
- It does a lot of the conversion: Oracle’s SuiteScript Upgrade skill assesses, converts and validates 1.0, 2.0 and 2.x scripts. But Oracle says that validation “is a static migration check, not a substitute for functional testing,” and not to change production behaviour just because a conversion completed without errors. The testing is the part that takes judgement.
- What does the free audit need from us?
- Access to a sandbox. There’s no size cap, and it ends with a fixed quote for the conversion.