If you’ve logged in to NetSuite lately and seen a banner telling you to update your scripts to SuiteScript 2.1, you’re not alone. The notice says one or more scripts in your account use SuiteScript 1.0, 2.0, or 2.x, and that scripts on those versions will stop working in NetSuite 2028.2. That deadline is real, and it reaches further than your oldest code.
The good news is that you have time, and this work goes well when it’s planned well. This guide covers:
- What the announcement means
- How to find scripts in your account
- How to prioritize which scripts you update
- Choosing the right path for each script
- Converting a SuiteScript 1.0 script
- Updating a SuiteScript 2.0 or 2.x script
- Getting more out of SuiteScript 2.1
- How to test and roll out safely
- Working with a SuiteRep developer on the update
What NetSuite Announced and What It Means
The notice names three groups: SuiteScript 1.0, 2.0, and 2.x. The last two surprise a lot of teams. Many people assume that anything written in “2.x” is current, but that isn’t the case. Version 2.0 runs on the older engine, and a
@NApiVersion 2.x tag isn’t a version at all. It resolves to whatever your account preference says, and by default that resolves to 2.0. So a script tagged 2.x is a 2.0 script unless someone changed the preference. To be safe, a script needs to be declared and running as 2.1.
The notice began appearing with NetSuite 2026.2, and the cutoff is 2028.2. That’s about two years and four more releases. It sounds like plenty of time, but the work is rarely just translation. Most of the effort goes into understanding what each script does for your business, and that takes calendar time.
Step 1: Take Inventory of Every Script
Start with the Scripts list under Customization > Scripting > Scripts. It shows the API version for each script, so you can filter for 1.0 and then work through 2.0 and 2.x. Two habits will save you trouble later.
First, compare the version a script declares with the version it actually runs as. Check the
@NApiVersion tag in the file, then check the account preference under Setup > Company > Preferences > General Preferences. Second, don’t stop at the list. Search your file cabinet or SDF project for nlapi, which is the prefix on every 1.0 function. Also look at custom plug-in implementations, which are easy to miss, and at scripts that arrive inside bundles or SuiteApps. Those belong to the vendor, so you’ll need their updated bundle before those scripts can move to 2.1. Ask each vendor what their plans and timeline are.
For each script, record the type, the deployments, what it does in plain language, who owns the process, and what it touches. That means records, saved searches, workflows, and outside systems that call it. If nobody can explain why a script exists, find out before you convert it. Some scripts can simply be retired.
Step 2: Sort and Prioritize
Not every script deserves the same urgency. A useful way to rank them:
- Business impact. Anything that touches transactions, fulfillment, billing, or month-end close goes near the top.
- Integration exposure. RESTlets and Suitelets that outside systems call carry more risk, because a small change in response format can break something you don’t control.
- Complexity. Line count, use of APIs with no direct 2.1 equivalent, and subrecord scripting all add effort.
- Necessity. Inactive or redundant scripts should be retired, not converted.
Step 3: Choose the Right Path for Each Script
Most scripts fall into one of three paths. A 2.0 or 2.x script usually needs a header change plus a careful review for behavior differences. A 1.0 script needs a real rewrite. And when a 1.0 script can’t be fully converted right away, NetSuite documents a bridge: put the 2.x logic in a RESTlet and call it from the 1.0 script with
nlapiRequestRestlet(). Because the 1.0 script itself is also on the clock, treat that as a temporary step and not a destination.Converting a SuiteScript 1.0 Script
SuiteScript 1.0 was a set of global functions. SuiteScript 2.1 is modular, so every script needs a defined structure: two JSDoc tags (
@NApiVersion and @NScriptType), a define() call that loads the modules you need, entry point functions that receive a context object, and a return statement that maps entry points to functions. Here is a simple user event script before and after:// SuiteScript 1.0
function beforeSubmit(type) {
var total = nlapiGetFieldValue('total');
nlapiLogExecution('DEBUG', 'Order total', total);
}/**
* @NApiVersion 2.1
* @NScriptType UserEventScript
*/
define(['N/log'], (log) => {
const beforeSubmit = (context) => {
const total = context.newRecord.getValue({ fieldId: 'total' });
log.debug({ title: 'Order total', details: total });
};
return { beforeSubmit };
});Once the structure is in place, convert the individual calls. Parameters in 2.1 are passed as a single object of key-value pairs, and some parameter names changed along the way. A few of the most common mappings:
| SuiteScript 1.0 | SuiteScript 2.1 |
|---|---|
nlapiLoadRecord |
record.load (N/record) |
nlapiSearchRecord |
search.create or search.load (N/search) |
nlapiLookupField |
search.lookupFields (N/search) |
nlapiLogExecution |
log.debug, log.audit, log.error, log.emergency (N/log) |
nlapiSendEmail |
email.send (N/email) |
nlapiGetContext |
runtime.getCurrentScript, getCurrentUser, getCurrentSession (N/runtime) |
nlapiRequestURL |
http.request and related methods (N/http, N/https) |
A few differences deserve extra attention because they change how the code has to be written, not just what it’s called:
- Line numbers start at 0. Sublist line indexes in 2.1 are zero-based, where 1.0 started at 1. Every loop over a sublist needs a second look.
- Subrecords work differently. There is one method to create or load them, they save automatically with the parent record, and addresses are subrecords instead of individual fields.
- Some APIs have no direct match. Date math like
nlapiAddDaysmoves to standard JavaScript dates. Time zone-aware datetime functions move to the N/format module.nlapiEncryptis replaced by N/crypto or N/encode. Recovery points and yielding (nlapiSetRecoveryPoint,nlapiYieldScript) have no equivalent, so scheduled scripts that relied on them need a rethink. Map/Reduce is often the better home for high-volume work. - Entry points changed. Client script
pageInitnow receivesmodeinstead oftype, andrecalcbecamesublistChanged. User event scripts getcontext.newRecordandcontext.oldRecord. Mass update parameters becameparams.typeandparams.id.
One more rule to plan around: 2.1 scripts can’t call 1.0 APIs, so a partial conversion inside a single script isn’t an option.
Updating a SuiteScript 2.0 or 2.x Script
Changing
@NApiVersion to 2.1 takes seconds. The real work is what happens next, because 2.1 runs on a different engine and some code that quietly worked in 2.0 now fails or behaves differently. These are the ones we see most:
- Stricter JavaScript rules. Assigning to an undeclared variable now throws a
ReferenceError. Reassigning aconstthrows aTypeError, where 2.0 silently ignored it. Words likeextendsare now reserved and can’t be used as identifiers. - Old syntax now fails.
for each...inloops, conditionalcatchblocks (catch (e if ...)), andtoSource()all cause errors in 2.1. - JSON parsing is stricter. Trailing commas in a JSON string, which 2.0 tolerated, now throw a syntax error, and the error messages themselves are worded differently. That matters if any of your code matches on error text.
- Error objects serialize differently. If you log errors with
JSON.stringify, an Error created with an argument can lose its message in 2.1. Creating the Error with no argument and setting the message afterward avoids it. - Formatting and number quirks. Converting a date to a local date string now defaults to the short format (2012-12-21 instead of December 21, 2012). A decimal with trailing zeros, such as 616.00, is now set as an integer. And
parseInt('08')now returns 8, where 2.0 failed to assign a value. - RESTlet responses changed. In 2.0, a
JSON.stringifycall was added internally to what a RESTletpost()returned, and 2.1 no longer does that. Also, when the request’s Content-Type isapplication/json, 2.1 hands back an object where 2.0 returned a string. Any integration that consumes your RESTlets should be retested.
Rather than depend on the account preference for testing, set the tag to 2.1 explicitly. A preference exists that runs 2.0 server scripts as 2.1 across the whole account, and it can be useful for a quick smoke test in a sandbox. But a script tagged 2.x is still validated as 2.0 on upload, so 2.1-only syntax will fail there until the tag says 2.1.
Getting More Out of 2.1
Once a script is safely converted, 2.1 opens up modern JavaScript:
let and const, classes, destructuring, the spread operator, and promises with async and await. Server-side promises only work with a specific set of modules (N/http, N/https, N/llm, N/query, N/search, and N/transaction), and using them elsewhere throws an error. The N/llm and N/pgp modules are available only in 2.1. Debugging changes too. 2.1 scripts use a Chrome DevTools-based debugger inside NetSuite, with full support in Chrome only and a role that has SuiteScript permission at Full level.
This is also the natural moment to refactor. Searching in loops, redundant record loads, and heavy scheduled scripts that could be Map/Reduce are all easier to fix while the code is already open.
Testing and Rolling Out
A conversion can be syntactically perfect and still behave differently, so test against outcomes, not just errors. Run old and new versions in a sandbox with the same data and compare what matters: field values, related records, system notes, execution time, governance usage, and any calls that leave NetSuite. Test edge cases and bulk volumes, and rehearse with the people who own the process. Then roll out in phases, keep the previous version on hand for a quick rollback, and watch the execution logs right after go-live. If your scripts still live only in the UI, this is a good time to move them into an SDF project under version control.
You may also see AI-assisted tools for this work. NetSuite added a SuiteScript upgrade skill to its SuiteCloud Agent Skills, and it can speed up analysis and first-pass conversion. But no tool knows your approval sequences, your integrations, or which script fires at month-end. A converted script still needs a person who understands your business to sign off on it.
What to Expect When You Work With a SuiteRep Developer
Everything above can be done in-house, but many teams don’t have the time or the ES6-era experience to do it well alongside their day jobs. Here’s how it works when you bring in a SuiteRep developer.
Discovery. We start by looking at all the active scripts in your account, then categorize them and show you which ones are candidates for an update. That gives you a clear picture before any code changes. A second phase looks at ways to refactor for efficiency.
Prioritizing. We settle this on our intro call. We walk through your processes and decide together which scripts matter most, so the ones your business leans on hardest get handled first.
Scope. The work covers all script types: user event, client, scheduled, Suitelet, RESTlet, Map/Reduce, and the rest. There is one caveat, which we cover next.
Scripts outside our control. Not every script in your account is one we can change. Scripts that come inside bundles belong to the vendor who built them, so only that vendor can release an updated version. We can still help you oversee the process of updating those bundles, and we can manage the bundle upgrades as vendors make them available. That way, the scripts we can’t touch don’t fall through the cracks while we work on the ones we can.
Timeline. It depends mostly on how many lines of code need translating, and this is one of the faster jobs we do. We’ll give you an estimate once discovery shows what’s in your account.
Communication. You’ll hear from us throughout. We stay in constant contact for validation and testing, because you know how these processes are supposed to behave. We also encourage code review, so you’re welcome to see what we’re changing and why.
Our approach. You won’t get a blind translation that could introduce errors. You’ll get a process-based conversion that keeps your functionality intact and takes advantage of NetSuite’s updated APIs to make your scripts more efficient. That is what dedicated, U.S.-based NetSuite specialists who know your account bring to the table.
Start Planning Now
The 2028.2 deadline is still a ways off, but the scripts that take the longest to sort out are usually the ones that matter most. Getting your inventory done now gives you options later. If you’re not sure where your account stands, or you’d like help with the update, the team at SuiteRep is happy to take a look. Reach out and we’ll review your scripts with you, and if you’re thinking bigger about NetSuite digital transformation services, this is a good moment to talk about that too.