NetSuite SuiteScript 2.1: The 2028.2 Deadline, the Warning, and What Actually Breaks

What the "Update Scripts to SuiteScript 2.1" warning actually means

If a yellow banner has appeared on your NetSuite dashboard telling you to update scripts to SuiteScript 2.1, nothing in your account has broken. What you have received is a deadline.

The warning is deliberately generic, because NetSuite cannot tell you from a banner which of your scripts will misbehave. It gives you the date. Working out the scope is your job, or your partner's.

The versions named in the warning are not in the same position as each other, which is the part most teams miss:

• SuiteScript 1.0 uses global nlapi functions and a completely different script structure. Moving it to 2.1 is a conversion, not an edit.
• SuiteScript 2.0 already uses the module pattern that 2.1 uses. The API surface is the same. What differs is the engine underneath it.
• SuiteScript 2.x is an annotation, not a version. Oracle resolves it to 2.0 at runtime, so these scripts are legacy code wearing a label that sounds current.

The NetSuite SuiteScript deprecation timeline, release by release

Oracle has staged the removal across four releases. NetSuite ships two releases a year, so 2027.1 is the first half of 2027 and 2028.2 is the second half of 2028. Each account upgrades on its own date inside the release window.

Oracle's stated reasons for the change are a newer JavaScript standard, better performance, stronger security, and a single version to support going forward. That is reasonable, and it does not make the work any smaller.

Why 2028.1 is the date that should be in your calendar

Most coverage of this topic, including NetSuite's own banner, puts 2028.2 front and centre. That is the compliance date. It is not the date your account changes.

In 2028.1, SuiteScript 2.0 and 2.x server scripts begin running on the 2.1 runtime by default. No redeploy. No approval step. No code change on your side. If a script behaves differently on the new engine, it starts behaving differently then, roughly six months before the headline deadline, and it does so in production unless you have already tested it.

How to find out how many scripts this affects

Before anything else, produce a number. In NetSuite, go to Customization > Scripting > Script Deployments, set the filters to show all deployments, and add the API version so you can see which version each script reports.

Two things make that count unreliable on the first pass, and both of them push the number downward:

1. The 2.x problem. A script annotated @NApiVersion 2.x resolves to 2.0. Teams reading a version column that says 2.0 often assume they have no 2.x scripts at all, when in fact the two are merged in that view. The source file is the truth, not the column.
2. What the deployment list leaves out. Custom modules and library files are not script records. Neither are the scripts inside bundles and SuiteApps you installed. All of them still have to be on 2.1 by 2028.2, and the ones you did not write are the ones you cannot fix yourself.

For each script and deployment worth tracking, capture the internal ID, the deployment status, the real annotation from the file, the script type, its dependencies, the business process behind it, when it last executed, and whether it is yours or a vendor's. That last column decides who does the work.

What actually changes when a 2.0 script runs on SuiteScript 2.1

The SuiteScript API is the same across 2.0 and 2.1. The engine is not. Server scripts on 2.1 run on the Graal runtime, which supports ECMAScript 2023, while 2.0 runs an older standard. Oracle documents thirteen specific behaviors that differ as a result.

What matters for planning is not the list itself but how each one fails. Some stop the script. Others let it finish and quietly return something else.

Differences that throw an error

Differences that change the result without raising an error

The second table is the expensive one. A script that throws gets noticed within the hour. A script that posts a slightly different number, or hands a RESTlet consumer a payload in a different shape, can run for weeks before anyone connects the symptom to the cause. When you decide how much testing each script deserves, sort by which table it falls into rather than by how long the file is.

NetSuite does give you a way to test this before the engine changes on its own. Account level preferences under Setup > Company > Preferences > General Preferences let you run 2.x and 2.0 server scripts on the 2.1 runtime without editing a single file. Use them in a sandbox or Release Preview account with a written test plan, never in production, because they affect many scripts at once.

SuiteScript 1.0 is a different kind of work

For a clean 2.0 script, the migration can genuinely end with changing one annotation after the script passes testing:

/**
 * @NApiVersion 2.1
 * @NScriptType UserEventScript
 */

SuiteScript 1.0 offers no such shortcut. The script has to be rebuilt with the correct 2.1 structure and entry points, the global nlapi functions and nlobj objects have to be mapped to their 2.1 module equivalents, and the places where no direct equivalent exists have to be solved rather than translated. Sublist handling, logging, URL resolution and error handling all behave differently.

There is also a practical problem that has nothing to do with code. SuiteScript 1.0 scripts tend to be old, which means the person who wrote them has usually left and the original requirement was never written down. Working out what the script is supposed to do often takes longer than writing the replacement. Budget for the archaeology, not just the development.

What you get in return for the work

This is a forced migration, so it is tempting to treat it as pure cost. A few things are only available on 2.1, and some of them are worth having:

• The AI modules. N/llm for generative AI, N/documentCapture for extracting structured data from documents such as invoices and receipts, and N/machineTranslation for translation are supported in SuiteScript 2.1 only. If your roadmap includes AI inside NetSuite, 2.1 is the entry ticket. We covered the development side of this in how AI is changing SuiteScript development.
• Modern language features. ECMAScript 2023 brings let and const, arrow functions, template literals, classes and the spread operator. Code written this way is shorter and easier for the next person to read.
• Browser based debugging. SuiteScript 2.1 scripts are debugged in your browser's debugger rather than the SuiteScript Debugger, which puts NetSuite development in line with the rest of your stack.
• Security modules. N/pgp for secure messaging, and N/crypto/random in server scripts, are 2.1 only.

If a script is being opened anyway, that is the cheapest moment it will ever be to fix the governance problem it has always had. A migration is a reasonable time to review how your customizations are built, not just which version they declare.

Where SuiteScript 2.1 is not supported yet

Two limitations are worth knowing before you plan a clean sweep of every script in the account.

SuiteScript 2.1 client scripts are not currently supported in the Scriptable Cart. If you run SuiteCommerce with custom cart scripts, moving those to 2.1 today means running a configuration Oracle does not support. Oracle's own instruction for this situation is to follow the version requirements documented for a feature until its help content is updated, so the correct move is to inventory those scripts as their own group, leave them where they are, and re-check at each release.

Separately, some 2.1 features are not fully supported in client scripts, subrecords being the documented example. A 2.1 client script deployed to All Records can error because that includes subrecords. Oracle's workaround is to keep such a client script on older language features. It is a small detail that will cost someone a confusing afternoon if they meet it without warning.

The other deadline sitting in the same releases

SuiteScript is not the only thing changing in this window. From 2027.1, NetSuite stops accepting new Token-Based Authentication integrations and NLAuth stops working, with support for existing TBA integrations expected to end in 2028.2, the same release that requires SuiteScript 2.1.

These two timelines collide in one place: RESTlets. A RESTlet converted to 2.1 still fails if the system calling it signs in with a retired method, and it is the same file either way. Teams that run the two efforts as separate projects end up opening, testing and redeploying the same scripts twice. Our TBA to OAuth 2.0 migration guide covers that side in detail, and the connected systems themselves fall under NetSuite integration services.

A five step plan you can start this quarter

1. Stop adding to the problem

   Every new script written from today should be 2.1, and any legacy script a developer touches for another reason should come back as 2.1. The option of leaving a 1.0 script alone because it still works has an expiry date on it now. Factor the extra refactoring time into estimates for any project that opens old code.

2. Build the inventory

   Script records, deployments, custom modules, library files, and the scripts inside bundles and SuiteApps. Read the annotation from the source file rather than trusting a version column, and record who owns each item.

3. Sort every script into one of four outcomes

   Retire it, hand it to the vendor who owns it, migrate it as a routine change, or migrate it carefully because it touches transactions, integrations or shared libraries. Retirement is the only one of the four that makes the total smaller, so do that pass before anyone estimates the rest.

4. Test on the 2.1 runtime in a sandbox

   Enable the account level preferences in a test account and exercise the scripts with realistic data, roles and volumes. Record the expected and the actual result for each deployment. A script that ran without error is not the same as a script that did the right thing.

5. Convert in waves, then update the annotation

   Move lower risk scripts first, keep a rollback plan, and change @NApiVersion only after the behavior is verified. Monitor the first period close after each wave, because that is when a silent value change shows up if one slipped through.

Vendor coordination deserves its own calendar entry. Ask each bundle and SuiteApp publisher which NetSuite release ships their SuiteScript 2.1 version, and get the answer with a release number attached. If a publisher no longer exists or has no plan, you are not looking at a migration for that component. You are looking at a replacement, and that is a decision you want to make in 2027 rather than in 2028.

Frequently asked questions

Keeping it that way after the last wave

Converted scripts still need an owner at the next release. Two NetSuite releases a year means two chances a year for something to drift, which is what NetSuite support services and managed services exist to absorb. If the script count is only one of several unknowns in your account, a NetSuite health check is the wider version of the same exercise.