Every custom script has to be on SuiteScript 2.1 by 2028.2.
Oracle has scheduled the removal of SuiteScript 1.0, 2.0 and 2.x across four releases. The date most teams write down is 2028.2. The one that reaches your account first is 2028.1, when 2.0 and 2.x scripts start executing as 2.1 by default. We count what you have, test it before that happens, and convert it.
Quick reply, from the team that lives in NetSuite.
Tell us about your project
NetSuite-only since 2017 · 75+ companies served · Sandbox-first, close-calendar aware
Deadline
2027.1: SuiteScript 1.0 support narrows to critical issues only. 2028.1: 2.0 and 2.x scripts run as SuiteScript 2.1 by default. 2028.2: every custom script must be on 2.1.
The message
You have probably already seen this.
It appears on any account still running 1.0, 2.0 or 2.x scripts. The help topic it points to sits behind a NetSuite login, which is part of why the message is hard to act on.
What it does not say is that the runtime under those scripts changes in 2028.1, six months before the date in the text.
Update Needed: Update Scripts to SuiteScript 2.1
One or more scripts in this account use SuiteScript 1.0, 2.0, or 2.x Scripts using these versions will stop working in NetSuite 2028.2. To ensure compatibility, convert your scripts to SuiteScript 2.1 as soon as possible. For details on removal timelines and next steps, see the help topic Transitioning to SuiteScript 2.1.
The problem
The deadline is not the problem. The date before it is. Most accounts also count fewer affected scripts than they actually have.
The runtime moves in 2028.1, on its own
Oracle's timeline makes 2.0 and 2.x scripts execute as SuiteScript 2.1 by default in 2028.1 — six months before the deadline. Nobody has to redeploy them and nobody has to approve it. You can switch the preference back while you fix things, which only helps if you notice in time.
Your @NApiVersion 2.x scripts are 2.0
Oracle states that a value of 2.x resolves to 2.0 when a script is uploaded and executed. Teams that wrote 2.x assuming it meant "the current version" are inside the migration, not ahead of it. On the Script record those scripts report as 2.0, so a saved search by API Version already counts them — which is not how the number usually gets read.
Half the changes are silent
Of the fourteen behavior differences Oracle documents, some throw errors and some just return something else: decimals stored as integers, dates in a different format, RESTlet responses changing shape for the partner on the other end. No alert fires. The gap between the change and the discovery is measured in weeks.
Part of the code is not yours to fix
Scripts installed by a bundle or a SuiteApp belong to the publisher. Oracle's guidance covers scripts you own and can edit, and says nothing about the rest. Their remediation date becomes your constraint, and you want that conversation early.
This is not an emergency, and it is not optional either. The work that is optional right now is finding out how much code is in scope. Teams that do the counting in 2026 get to sequence the rest around their own calendar.
The timeline
Four releases, and only one of them asks your permission.
Oracle's schedule, as published in SuiteAnswers 1047412.
2026.2
Now
SuiteScript 2.1 becomes the standard
The dashboard message starts appearing. Nothing breaks yet, and the account preferences are already there to test with.
2027.1
Support narrows
SuiteScript 1.0 goes to critical issues only
A non-critical bug in a 1.0 script comes with a prerequisite: convert it to 2.1 first, then ask for help.
2028.1
The floor moves
2.0 and 2.x scripts run as 2.1 by default
No redeploy, no approval. You can switch the preference back while you fix what broke, which only helps if you notice in time.
2028.2
Deadline
Every custom script must be on 2.1
No switch back. Anything still annotated 1.0, 2.0 or 2.x has to be updated to keep working.
Before you budget
Five questions to ask your team this quarter.
You do not need a migration project yet. You need answers to these — and if the first one takes more than a week to produce, that is itself the finding.
- 01
How many custom scripts do we have, and how many are on each version?
Careful here: scripts marked 2.x count as 2.0. Oracle resolves 2.x to 2.0 when a script runs, so a team that assumed 2.x meant "current" will report a smaller number than the real one.
- 02
How many of those can we delete?
Scripts built for a process that changed, duplicates, one-off fixes from an implementation nobody remembers. This is the only step that makes the total smaller instead of moving it.
- 03
Which scripts talk to systems we do not control?
RESTlets consumed by a partner, a storefront or a logistics provider are where a quiet change becomes someone else’s incident.
- 04
Which of our bundles and SuiteApps ship scripts, and what have their publishers committed to?
In writing, with a release number. Their date becomes your dependency.
- 05
What does our release upgrade schedule look like for 2028.1?
That date, not the 2028.2 headline, is when the behaviour changes in your account.
Clients
Trusted by mid-market companies across industries
The annotation
One line decides which runtime your script gets.
Oracle states that a value of 2.x resolves to 2.0 when the script is uploaded and executed. Only 2.1 is finished work.
/**
* @NApiVersion 2.x
* @NScriptType UserEventScript
*/
// ECMAScript 5.1 · switches to 2.1 in 2028.1/**
* @NApiVersion 2.1
* @NScriptType UserEventScript
*/
// ECMAScript 2023 · verified before the switchWhat changes
Legacy annotations vs. SuiteScript 2.1
SuiteScript 2.0 runs ECMAScript 5.1. SuiteScript 2.1 runs ECMAScript 2023 on a different runtime engine. This is what that means in practice.
On 1.0, 2.0 or 2.x today
- Required to change before the 2028.2 release
- 2.x annotations execute as SuiteScript 2.0
- Runtime switches automatically in 2028.1
- ECMAScript 5.1: const reassignment silently ignored, strict mode off by default
- Silent differences in decimals, dates and RESTlet payloads
- SuiteScript 1.0 support limited to critical issues from 2027.1
- No N/llm, N/pgp or N/crypto/random
- Debugged with the SuiteScript Debugger
On SuiteScript 2.1
- Meets the 2028.2 requirement, verified script by script
- The annotation says what the script actually runs
- Differences found in testing, not on the morning of 2028.1
- ECMAScript 2023: classes, template literals, let and const, arrow functions
- Behavior differences found in testing, not in production
- Not on a support timeline that narrows in 2027.1
- N/llm, N/pgp and N/crypto/random available
- Debugged in the browser, like the rest of your stack
What breaks
Fourteen documented differences, and only half of them tell you.
Oracle lists what behaves differently when a 2.0 script runs on the 2.1 runtime. The split below is the one that decides how much testing each script deserves.
Seven that fail loudly
The script throws and stops. Someone cannot save a record, or a queue stops draining. Bad days, but they announce themselves.
Reserved words as identifiers
A variable or parameter named extends now fails to parse.
for each...in
Removed from the standard. SyntaxError on 2.1.
Conditional catch blocks
catch (e if ...) was never standard. SyntaxError.
Strict mode
Assigning to an undeclared variable throws ReferenceError.
Reassigning a const
Silently ignored on 2.0, TypeError on 2.1.
toSource()
Obsolete. Throws on 2.1.
Invalid JSON
Trailing commas parsed on 2.0, rejected on 2.1.
Six that change quietly
The script keeps running and returns something else. No alert fires, and the gap between the change and the discovery is measured in weeks.
Decimals with trailing zeros
setValue(616.00) stored as a double, now as an integer.
parseInt
parseInt('08') returns nothing on 2.0 and 8 on 2.1.
Dates to local strings
"December 21, 2012" becomes "2012-12-21".
RESTlet POST responses
No longer stringified internally. Callers get a different length.
RESTlet return types
JSON responses come back as objects instead of strings.
Error objects
JSON.stringify drops the message property.
And one that is a limit rather than a change: async/await works in six modules only: N/http, N/https, N/llm, N/query, N/search and N/transaction. N/record is not one of them.
What we bring
NetSuite-only since
Companies served
Documented behavior differences we test for
The release everything has to be ready for
How we work
Count it properly, test it early, convert it in batches.
An inventory that is actually correct
The Script record has two version fields and reading one gives a wrong answer: API Version reports 2.0 for every 2.x script, and Execute As Version only appears when the account preference is set. We capture both, per script and per deployment, so the count you plan against is the real one.
Release Preview before production
The account-level preferences let you run 2.x and 2.0 cohorts as 2.1 separately. We test there with real volume, not in production and not on a sample, so failures surface on our schedule instead of during month-end close.
Sorted by blast radius, not by file name
A RESTlet consumed by a 3PL and a Suitelet that renders an internal form carry different risk. We separate the scripts that will fail loudly from the ones that quietly change values, and test them accordingly.
Delete before you convert
Most accounts carry scripts for processes that changed years ago, duplicates, and one-off fixes nobody remembers. Retiring them is the only step that makes the total smaller. We do that pass first, with you, before quoting conversion work.
The annotation is the deliverable
Flipping the account preference makes scripts run as 2.1, but it does not change the JSDoc tag, and 2028.2 requires the scripts themselves to be on 2.1. We verify behavior first, then update the annotation script by script, so you end the project actually finished.
Vendor coordination included
We identify which of your bundles and SuiteApps ship legacy scripts, and give you the list to take to each publisher with a specific question: which NetSuite release ships your SuiteScript 2.1 version.
The person who audits your scripts is the one who converts them. No account managers, no off-shore hand-offs.
No commitment required
Our process
From an unknown number of scripts to a finished migration
The first step answers the question that decides everything else: how much code is actually in scope.
- 01
The script audit
We inventory every script and deployment in your account, split by annotation with 2.x and 2.0 counted separately, and flag the patterns Oracle documents as different under 2.1. You get the count, the risk classification, and the list of scripts owned by third parties.
- 02
Retire what nobody uses
Before any conversion work is quoted, we go through the inactive, duplicated and superseded scripts with your team. Every script removed here is one you never pay to migrate, test, or maintain again.
- 03
Test in a sandbox or Release Preview
We switch the account preference in a test account, exercise the scripts with real data, and record what breaks loudly, what changes quietly, and what passes untouched. The result is a conversion plan with evidence behind each line.
- 04
Convert in batches, verify, annotate
We fix the patterns that behave differently, confirm the script does what it did before, and only then update @NApiVersion to 2.1. Work is sequenced around your close calendar so nothing lands during a critical week.
- 05
Clean handoff and monitoring
You get the updated scripts, the inventory kept current, and the list of anything still pending on a vendor. If we built it, we monitor the first close after the change and fix what surfaces.
The script audit
You cannot budget for this until you know the count.
The audit gives you the real number, sorted by risk, with the third-party code separated out.
- A count you can budget against
Every script and deployment, with 2.x and 2.0 separated instead of lumped together.
- Loud failures separated from silent ones
The scripts that throw errors, and the ones that quietly change values, tested differently.
- Release Preview testing
Both account preferences exercised with real data, before the release reaches production.
- Third-party scripts identified
The bundle and SuiteApp code you cannot edit, listed with the question to send each vendor.
- Annotations updated, not just preferences
The JSDoc tag moved to 2.1 after the script is verified, which is what 2028.2 requires.
Questions
SuiteScript 2.1 migration, answered
The timeline below comes from Oracle SuiteAnswers answer ID 1047412, last updated September 16, 2026. It requires a NetSuite login, so your administrator can open it from the dashboard banner.
Still have questions? Drop us a message, we'd love to hear from you!
Talk about a script audit01What does the script audit include?
+
A count of every script and deployment in your account split by annotation, with 2.x and 2.0 separated. A risk classification that separates scripts which will throw errors from scripts which will quietly return different values. A list of scripts installed by bundles or SuiteApps that you cannot edit. And a recommended sequence with an effort range. No obligation.
02How long does this take?
+
It depends on the count, on how much of it can be retired outright, and on how many scripts move by changing an annotation after testing rather than needing rework. We do not quote before the count, which is why the audit comes first: it tells you whether this is a sprint or a program.
03Do we have to convert SuiteScript 1.0 scripts too?
+
Yes, and those come first. From 2027.1, SuiteScript 1.0 support covers critical issues only, so a routine bug in a 1.0 script may require converting it before anyone can help you. 1.0 to 2.1 is a rewrite rather than an annotation change: the module pattern, the API surface and the sublist indexing are all different.
04Can you work with our in-house developers instead of replacing them?
+
Yes, and it is often the cheaper shape. A common split is that we run the audit and the Release Preview testing, hand your team the classified list with the specific fix for each pattern, and take on only the batches they do not have capacity for.
05Why start now if the deadline is 2028?
+
Three reasons. The runtime change in 2028.1 arrives whether or not you are ready. Every NetSuite account with custom code faces the same two releases, so the people who do this work get booked against the same window. And an inventory done calmly is a small fixed piece of work, while the same work after a silent data change has been running for a month becomes an investigation and a data correction.
Contact
Find out how many scripts this touches
Tell us a little about your account and we will run the inventory. You get the count, the risk classification, and the list of scripts owned by third parties — whether or not you hire us to convert them.
What happens next
- 1We look at your scripts and deployments, with 2.x and 2.0 counted separately.
- 2We classify them: fails loudly, changes quietly, passes untouched.
- 3You get the list, a recommended sequence, and an effort range.
No obligation. If the answer is that you have twelve scripts and none of them are affected, we will tell you that.
Tell us about your project
Explore related services
What usually comes with this work
- 01NetSuite DevelopmentCustom SuiteScript, SuiteApps, workflows and integrations built by the people who scope them.View Service
- 02Ongoing SupportManaged NetSuite administration once the conversion work is done.View Service
- 03SuiteApp DevelopmentMarketplace-ready SuiteApps, built on SuiteScript 2.1 from the start.View Service
- 04NetSuite IntegrationsRESTlets, REST and SOAP web services, Celigo and custom middleware.View Service
- 05NetSuite TrainingSuiteScript 2.1 training for the developers and admins who will maintain this.View Service
- 06NetSuite ConsultingArchitecture and process work when the scripts are a symptom rather than the problem.View Service
Further reading
The detail behind the deadline
- 01SuiteScript 2.1 Migration: The Timeline, the 2.x Trap, and What BreaksThe release-by-release timeline, how to inventory your scripts correctly, and the fourteen behaviors Oracle documents as different.Guide
- 02NetSuite 2026.2 Release Notes: Developers & IT ArchitectsWhat 2026.2 changed for developers, including the authentication deadlines that share release numbers with this one.Guide
- 03NetSuite Customization Guide: Configure vs CustomizeWhen a requirement needs SuiteScript at all, and when native configuration does the job without code to migrate later.Guide
- 04How to Kill a Script in NetSuiteStopping a runaway scheduled, Map/Reduce or user event script, and the governance limits behind it.Guide