SuiteScript 2.1 Migration Services
Every custom script in your NetSuite account has to run on SuiteScript 2.1 by the 2028.2 release. EPIQ Infotech counts what you actually have, tests it before the runtime changes under it in 2028.1, and converts it in waves scheduled around your close calendar.
NetSuite SuiteScript retirement schedule
- 2026.2
- SuiteScript 2.1 becomes the standard scripting model
- 2027.1
- SuiteScript 1.0 support narrows to critical issues only
- 2028.1
- 2.0 and 2.x scripts execute as 2.1 by default
- 2028.2
- Every custom script must be annotated 2.1
What is SuiteScript 2.1 migration?
SuiteScript 2.1 migration is the work of inventorying every custom script in a NetSuite account, testing each one against the SuiteScript 2.1 runtime, correcting the code where behavior differs, and updating the @NApiVersion annotation to 2.1 before the 2028.2 release removes support for SuiteScript 1.0, 2.0 and 2.x.
- It affects any account running custom scripts, including scripts installed by bundles and SuiteApps.
- A 1.0 script is a rewrite. A 2.0 or 2.x script is usually a test, a few targeted fixes, then an annotation change.
- Flipping the account preference is not migration. The 2028.2 requirement is on the annotation in each script file.
- The date that reaches most accounts first is 2028.1, when the runtime changes without anyone redeploying anything.
Four releases, and only one of them waits for your approval
Oracle has staged the removal of older SuiteScript versions across four NetSuite releases. The headline date is 2028.2. The one that changes behavior in your account is 2028.1, roughly six months earlier.
SuiteScript 2.1 becomes the standard scripting model. The account dashboard warning starts appearing. Nothing stops working yet, and the account preferences you need for testing are already available.
SuiteScript 1.0 support covers critical issues only. A routine bug in a 1.0 script can come back with a prerequisite: convert it to 2.1 first, then raise the case.
2.0 and 2.x scripts execute as SuiteScript 2.1 by default, with no redeploy and no approval step. 1.0 scripts can no longer be deployed in new accounts.
Every custom script must use SuiteScript 2.1. Anything still annotated 1.0, 2.0 or 2.x has to be updated to keep running.
Release dates follow Oracle's published transition schedule. NetSuite ships two releases a year and each account moves on its own date inside the release window, so your 2028.1 upgrade date is the one that matters, not the release opening date.
Most accounts undercount this work, because the Script record hides half of it
Before anyone can budget for a SuiteScript 2.1 migration, someone has to produce a number. The number is usually wrong the first time, and it is wrong in the same way across most accounts.
2.x is not current
A script annotated @NApiVersion 2.x resolves to SuiteScript 2.0 when it is uploaded and executed. Teams who assumed 2.x meant "the newest 2 series" report a smaller migration scope than the one they have.
One field, two meanings
The API Version field on the Script record reports 2.0 for 2.x scripts. Execute As Version only appears once the account preference is set. Reading either field alone produces a count you cannot plan against.
Deployments count too
A single script can carry several deployments with different statuses, contexts and parameters. We capture both version fields per script and per deployment, so the scope you approve is the real one.
Runs as SuiteScript 2.0 today
/**
* @NApiVersion 2.x
* @NScriptType UserEventScript
*/
// ECMAScript 5.1 engine
// Switches to the 2.1 runtime in 2028.1
// Still fails the 2028.2 requirementFinished work
/**
* @NApiVersion 2.1
* @NScriptType UserEventScript
*/
// ECMAScript 2023 engine
// Behavior verified in a test account
// Meets the 2028.2 requirementWhat changes when a 2.0 script runs on the 2.1 runtime
SuiteScript 2.0 runs on an ECMAScript 5.1 engine. SuiteScript 2.1 runs ECMAScript 2023. Some of the differences throw an error the moment the script executes. Others let the script finish and return a different value, which is the category that decides how much testing a script deserves.
Differences that fail loudly
The script throws and stops. A record will not save, or a queue stops draining. Disruptive, but they announce themselves immediately.
- Strict mode is on by defaultAssigning to an undeclared variable throws a ReferenceError instead of creating a global.
- Reassigning a constSilently ignored under 2.0. Throws a TypeError under 2.1.
- Reserved words used as identifiersA variable or parameter named
classorextendsnow fails to parse. - for each...inNever part of the standard and removed. Produces a syntax error.
- Conditional catch blocks
catch (e if ...)is a non-standard construct and no longer parses. - Invalid JSONTrailing commas tolerated under 2.0 are rejected under 2.1.
Differences that change quietly
The script keeps running and returns something else. Nothing alerts, and the gap between the change and the discovery is usually measured in weeks of posted transactions.
- Decimals with trailing zerosA value set as
616.00can be stored with a different numeric type than it was under 2.0. - parseInt and leading zerosOctal-style strings such as
'08'are parsed differently across the two engines. - Date to string conversionDefault string formats differ, which quietly breaks downstream parsing and file output.
- RESTlet response handlingReturn values are no longer stringified the same way, so external callers receive a different payload shape.
- Error object serialization
JSON.stringifyon an Error can drop the message property, so logs lose the detail you need. - Limited async supportAsynchronous patterns are supported in a short list of modules only, which rules out some refactors you might expect to work.
Why this table drives the plan
A Suitelet that renders an internal form and a RESTlet consumed by a third-party logistics provider carry very different risk. We sort your scripts by what happens when they fail, not by file name, and give the quiet ones the testing they need before the runtime changes on its own in 2028.1.
SuiteScript 2.1 Migration Readiness Calculator
Seven questions about your scripts, your integrations and who looks after them. It takes about a minute. Enter your email at the end and the result lands in your inbox as well as on screen. It is a planning aid, not a technical audit.
Start with the script audit. You cannot budget what you have not counted
The audit is read-only. We review script records, deployments and source code, and we do not extract transactions, customer records or financial data. You receive the deliverable whether or not you hire EPIQ to do the conversion work.
- A count you can budget against. Every script and deployment, with 2.x and 2.0 separated rather than merged.
- Risk classification. Loud failures separated from silent value changes, each with the testing each one needs.
- Effort estimate per script. Hours banded by the work required, grouped into waves you can approve one at a time.
- Third-party code identified. Bundle and SuiteApp scripts you cannot edit, listed with the question to send each publisher.
- Dependency map. Which workflows, searches, records and integrations sit behind each script.
- Retirement candidates. Inactive, duplicated and superseded scripts, flagged before anyone pays to convert them.
- Authentication exposure. Every integration still signing in with TBA or NLAuth, listed as its own line item.
- Current-state findings. Governance, performance and security issues worth fixing regardless of the migration.
Every script takes one of five paths
Converting every script is the most expensive way to reach 2028.2. Sorting them first is how the number comes down.
Retire
Inactive, duplicated, or built for a process that changed. The only path that makes the total smaller instead of moving it.
Test and annotate
2.0 or 2.x code that behaves identically on the 2.1 runtime. Verified in a test account first, then the annotation moves to 2.1.
Refactor
2.0 or 2.x code that hits one of the documented behavior differences. Targeted fixes, retested, then annotated.
Rewrite
SuiteScript 1.0. The module pattern, API surface and sublist handling all differ, so this is new development, not conversion.
Vendor follow-up
Scripts shipped inside bundles and SuiteApps. We give you the list and the specific question: which release ships your 2.1 version.
How an EPIQ SuiteScript 2.1 migration runs
The same consultants who audit your scripts convert them. No handover to a separate delivery pool between the assessment and the work.
-
Inventory every script and deployment
We capture both version fields per script and per deployment, separate 2.x from 2.0, flag the patterns that behave differently under 2.1, and list the scripts owned by third parties. Integrations authenticating with TBA or NLAuth are tracked as their own group.
-
Retire what nobody uses
Before conversion work is quoted, we walk the inactive, duplicated and superseded scripts with your team. Every script retired here is one you never pay to convert, test or maintain again.
-
Test in sandbox and Release Preview
We set the account preferences in a test account so the 2.0 and 2.x cohorts run on the 2.1 engine, then exercise the scripts with representative volume. What fails, what changes quietly and what passes untouched is recorded as evidence behind each line of the plan.
-
Convert in waves, sequenced around your close
Scripts move in batches grouped by shared dependencies and record events, not alphabetically. Nothing lands during a period close, a physical inventory count or a peak season window.
-
Verify, then update the annotation
We confirm the script does what it did before, and only then move
@NApiVersionto 2.1. Where possible we replace the file on the existing script record so deployments, parameters and settings stay in place. -
Document and monitor the first close
You receive the updated inventory, a map of what changed and why, and the list of anything still pending with a vendor. We monitor the first period close after each wave and resolve what surfaces.
The systems calling your RESTlets have a deadline in the same releases
A RESTlet converted to SuiteScript 2.1 still fails if the system calling it signs in with a retired authentication method. The two timelines overlap, and the files involved are often the same files.
2027.1 closes the door on new TBA
From the 2027.1 release, new Token-Based Authentication integrations can no longer be created for REST web services or RESTlets, and NLAuth stops working. New OAuth 2.0 authorization code integrations must use PKCE.
Full detail in our TBA to OAuth 2.0 migration guide.
2028.2 carries both requirements
Support for existing TBA integrations is scheduled to end in the same release that requires every script to be on SuiteScript 2.1. Running the two efforts as one project means each RESTlet is opened, converted, re-authenticated and tested once.
See how we handle the connected systems in NetSuite Integration Services.
What the assessment covers
Scope is set by what a script touches, not by how long it is.
| Area | What EPIQ reviews |
|---|---|
| Script version | 1.0, 2.0, 2.x and 2.1, read from both the API Version and Execute As Version fields so 2.x is never counted as current |
| Script type | User Event, Client, Scheduled, Map/Reduce, Suitelet, RESTlet, Portlet, Mass Update, Workflow Action, Bundle Installation |
| Deployments | Status, execution context, audience, parameters and log level for every deployment of every script |
| APIs in use | Deprecated and migration-sensitive APIs, plus 1.0 global functions that have no direct 2.1 equivalent |
| JavaScript patterns | The constructs that fail or change behavior under the 2.1 engine, located line by line |
| Dependencies | Workflows, saved searches, custom records, custom fields, bundles and SuiteApps connected to each script |
| Integrations | External systems, middleware, RESTlet consumers, and the authentication method each one uses |
| Business processes | Order to cash, procure to pay, close, fulfilment and reporting flows affected by each customization |
| Governance | Usage units, execution time and queue behavior, since a refactor is the moment to fix a script that was already near its limits |
| Ownership | Who built each script, whether source is in SDF or only in the account, and what documentation exists |
SuiteScript 1.0 is a rewrite. SuiteScript 2.0 is usually a test
The two starting points produce very different estimates, which is why a single per-script price is a warning sign rather than a convenience.
Coming from SuiteScript 1.0
The architecture is different, not just the syntax. The module pattern replaces global functions, the API surface is organised into N/ modules, record and sublist handling changed, and entry points are declared rather than selected on the deployment.
These scripts go first, because from 2027.1 a non-critical bug in a 1.0 script can require conversion before support will engage with it.
Coming from SuiteScript 2.0 or 2.x
Most of this code runs on 2.1 with no change at all. The work is proving which scripts those are, fixing the handful that hit a documented difference, and then updating the annotation so the account meets the 2028.2 requirement.
Testing comes before the annotation change, never after. An annotation updated on an untested script moves the risk, it does not remove it.
Where AI-assisted conversion helps, and where it does not
Oracle's SuiteCloud tooling and AI-assisted conversion can handle repetitive syntax translation, draft test cases and speed up SDF work. EPIQ uses that tooling where it earns its place, and a certified developer reviews every converted script before it reaches a sandbox. Automated conversion is not an assessment, and it does not know which of your scripts posts to the general ledger. More on this in how AI is changing SuiteScript development.
Why NetSuite teams bring this work to EPIQ
Certified consultants, not subcontractors
Certified NetSuite administrators and SuiteCloud developers, with 15+ years of Oracle ERP depth behind the NetSuite practice. The person who audits your scripts is the person who converts them.
We inherit other partners' code regularly
Undocumented scripts from an implementation nobody remembers are the normal starting point, not an obstacle. We reconstruct what each script does from the code, the deployment and the process behind it.
Close-calendar aware delivery
Waves are scheduled around period close, audit windows and peak season. Finance teams should not learn about a migration wave from a failed posting.
Where SuiteScript migration sits in your NetSuite roadmap
Script conversion rarely travels alone. These are the engagements it most often connects to.
Customization
A migration is the right moment to ask whether a script should exist at all. Our NetSuite customization services cover the full ladder, from configuration through Suitelets built on SuiteScript 2.1.
Ongoing support
Converted scripts still need an owner at the next release. NetSuite Support Services and NetSuite Managed Services keep the same team on your account after the last wave ships.
Health check
If the script count is one of several unknowns, a NetSuite health check looks at the whole environment, including saved searches, roles and data hygiene.
Integrations
RESTlets, middleware and connectors are assessed alongside your scripts under NetSuite Integration Services, so authentication and script versions move together.
Implementation and rescue
Accounts carrying heavy legacy customization often need a wider conversation. See NetSuite Implementation Services and NetSuite Consulting Services.
One accountable partner
License advisory through long-term support under a single relationship, as a certified NetSuite solution provider. Moving data as well as code? See NetSuite Data Migration Services.
SuiteScript 2.1 migration questions, answered
Is SuiteScript 2.1 migration mandatory?
Yes, for any account with custom scripts. Oracle has scheduled the removal of SuiteScript 1.0, 2.0 and 2.x, and from the 2028.2 release every custom script must use SuiteScript 2.1. Scripts still annotated with an older version stop working at that point.
Is changing @NApiVersion from 2.x to 2.1 enough?
Sometimes, but only after testing. Run the script in a sandbox or Release Preview account with the 2.1 preference enabled first. If it behaves identically, the annotation can be updated. If it does not, the code is corrected and retested before the annotation changes. Updating the tag on an untested script is how a quiet value change reaches production.
How many scripts do we actually have to migrate?
Fewer than the raw count, usually. A typical account retires a meaningful share outright, moves most of the 2.0 and 2.x code with testing and an annotation change, and reserves real development effort for the 1.0 scripts and the handful that hit a documented behavior difference. The audit produces the split before anyone quotes the work.
How much does a SuiteScript 2.1 migration cost?
Cost tracks three things: how many scripts survive the retirement pass, how many are on 1.0 rather than 2.0 or 2.x, and how many touch integrations or posting transactions and therefore need deeper testing. EPIQ does not quote conversion work before the audit, because a per-script average on an uncounted account is a guess with an invoice attached.
Why start now when the deadline is 2028?
Three reasons. The runtime change in 2028.1 arrives whether or not you have tested. Every NetSuite account with custom code faces the same two releases, so developer capacity gets booked against one window. And an inventory produced calmly is a small fixed piece of work, while the same work after a silent value change has been posting for a month becomes an investigation and a data correction.
Can you migrate scripts another partner wrote?
Yes, and that is the common case. We reconstruct behavior from the code, the deployment configuration and the business process it supports. Where documentation is missing we rebuild it as part of the engagement, so you are not in the same position at the next platform change.
What about scripts inside bundles and SuiteApps?
You cannot edit them, so they are tracked separately. We identify which installed components ship legacy scripts and give you a list to take to each publisher with one specific question: which NetSuite release ships your SuiteScript 2.1 version. Their date becomes a dependency in your plan.
Does the audit change anything in our account?
No. The audit reads script records, deployments and source code and produces a report. It does not extract transactions, customer records or financial data, and no code is changed. Changes happen only in the conversion phase, one approved wave at a time.
Can our in-house developers run the migration instead?
Many teams can, and the audit still earns its keep. Your developers receive the inventory, the risk classification, the dependency map and the specific fix for each pattern, and you decide what to keep internal. A common split is that EPIQ runs the audit and the Release Preview testing, and your team takes the batches it has capacity for.
Does this affect our integrations and authentication too?
Often yes, because the same releases carry both changes. From 2027.1, new Token-Based Authentication integrations can no longer be created and NLAuth stops working, and support for existing TBA integrations is scheduled to end in 2028.2, the same release that requires SuiteScript 2.1. RESTlets called by external systems usually need both the script conversion and the authentication move, so we scope them together.
Find out how many scripts this touches
Tell us about your account and EPIQ will run the inventory. You get the real count, the risk classification and the list of scripts owned by third parties, whether or not you hire us to convert them.
Sources and further reading
- Oracle NetSuite Help Center, Transitioning to SuiteScript 2.1
- Oracle NetSuite 2026.2 Release Notes, SuiteCloud Platform
- Oracle NetSuite Help Center, SuiteScript 2.x API differences and authentication release notes
EPIQ Infotech LLC, Cerritos, CA, USA. Oracle NetSuite Alliance Partner since 2013. Release timing reflects Oracle guidance as published at the time of writing and each account moves on its own upgrade date.