Guide · Updated October 2026

SuiteScript 2.1 migration: what changes, who is affected, and how to get there before 2028.2

Oracle has set a date: by the NetSuite 2028.2 release, custom scripts must run on SuiteScript 2.1. That covers the obvious SuiteScript 1.0 code and, less obviously, every 2.0 script in the account. This guide walks through the timeline, the technical differences, and a plan that starts from what is actually deployed.

The timeline

Source: Oracle NetSuite SuiteAnswers article 1047412, “SuiteScript 2.1 Required for All Custom Scripts in NetSuite 2028.2”. Release dates for 2028 are not yet published; plan against the release number.

Which scripts are affected

Three groups, with very different amounts of work:

• SuiteScript 1.0 (nlapi* functions, no define() block). These need a rewrite into the 2.1 module structure. End-of-life support begins in 2027.1, a full year before the hard stop.
• SuiteScript 2.0 and 2.x (define() with N/ modules, @NApiVersion 2.0 or 2.x). These need testing under the 2.1 engine and an annotation change. Most pass; some break on strict mode.
• Scripts you cannot read: locked bundles, vendor SuiteApps, restricted folders. These are not yours to convert. Each one is a vendor conversation and a line in the risk register.

Client scripts, user events, Suitelets, RESTlets, scheduled scripts, Map/Reduce, portlets, mass updates and workflow actions are all in scope. Only active deployments matter; inactive scripts can be retired.

2.0 to 2.1: why “just change the annotation” is not enough

SuiteScript 2.0 and 2.1 share the same API surface, so the migration looks trivial. The difference is the engine underneath. 2.1 runs on GraalJS and applies rules that Rhino-era 2.0 code was never held to:

NetSuite exposes an account preference that runs 2.0/2.x server scripts under the 2.1 engine. Turn it on in a Sandbox, run the real business flows, and fix what throws. When a script is clean, change its annotation to 2.1 and move on.

1.0 to 2.1: what a rewrite involves

A 1.0 script is a set of global functions calling nlapi* helpers. A 2.1 script is a module: a JSDoc header, a define() call that loads the N/ modules it needs, entry points that take a context object, and a returned object naming those entry points. The same user event, before and after:

// SuiteScript 1.0 — User Event
function beforeSubmit(type) {
  var rec = nlapiGetNewRecord();
  var limit = nlapiLookupField('customer',
    rec.getFieldValue('entity'), 'creditlimit');
  if (parseFloat(rec.getFieldValue('total')) > parseFloat(limit)) {
    rec.setFieldValue('custbody_credit_hold', 'T');
    nlapiLogExecution('AUDIT', 'Credit hold', rec.getId());
  }
}

/**
 * @NApiVersion 2.1
 * @NScriptType UserEventScript
 */
define(['N/search', 'N/log'], (search, log) => {
  const beforeSubmit = (context) => {
    const rec = context.newRecord;
    const { creditlimit } = search.lookupFields({
      type: 'customer',
      id: rec.getValue({ fieldId: 'entity' }),
      columns: ['creditlimit'],
    });
    if (parseFloat(rec.getValue({ fieldId: 'total' })) > parseFloat(creditlimit)) {
      rec.setValue({ fieldId: 'custbody_credit_hold', value: true });
      log.audit({ title: 'Credit hold', details: rec.id });
    }
  };
  return { beforeSubmit };
});

Beyond the structure, every nlapi* call maps to a module method. The most common ones:

The mapping is not always one-to-one, and Oracle’s API map lists 1.0 functions with no 2.1 equivalent. Those steps need a redesign rather than a translation. Checkbox fields also change type: 1.0 used the strings ‘T’ and ‘F’; 2.1 uses booleans.

A migration plan that starts from the live account

Tools that help

• Oracle’s SuiteScript upgrade skill. Free and open source. It analyses, converts and validates script files in a local SuiteCloud project. Best when your code already lives in source control.
• SuiteMigrate. A Chrome extension that works from the NetSuite account you are signed in to. It inventories active scripts with their API version, checks which source files your role can read, and converts the scripts you choose into reviewable 2.1 drafts with side-by-side review and change notes. Free for five conversions.
• NetSuite’s own 2.1 runtime preference for testing 2.0 scripts, and the SuiteScript 2.1 debugger in Chrome DevTools for working through failures.
• A NetSuite partner for large estates or when nobody in-house has time. Typical rates run from roughly $120 to $275 per hour, so use the inventory to scope the engagement precisely.

Whatever produces the converted code, the rule is the same: review it, test it in Sandbox, then deploy. No tool is a substitute for that.

Frequently asked questions

SuiteMigrate is not affiliated with or endorsed by Oracle Corporation or NetSuite. NetSuite and SuiteScript are trademarks of Oracle and/or its affiliates.