SuiteScript 1.0 Is Being Phased Out: What It Means and How to Prepare

If you manage a NetSuite account that still relies on older customizations, there is an important trend you should be planning around: Oracle NetSuite is steadily moving the platform away from SuiteScript 1.0 and toward SuiteScript 2.x. While your existing 1.0 scripts continue to run for now, Oracle has made it clear that 1.0 is effectively in maintenance-only mode. No new features, APIs, or enhancements are being built for it, and all future investment is going into the 2.x framework. This post breaks down what that means in practical terms, shows real before-and-after code, and lays out the concrete steps you can take to get ahead of the change.

What Oracle Is Actually Saying

According to Oracle’s official NetSuite documentation, SuiteScript 1.0 scripts remain supported, but the framework is no longer being updated and no new feature development is happening for it. Oracle’s guidance is direct: use SuiteScript 2.x for any new script, and for any script you are substantially revising. The reasoning is that 2.x is where new APIs, capabilities, and long-term platform improvements live. In short, 1.0 is a legacy runtime that works today but represents growing technical debt for your account over time.

It is worth understanding the distinction between the two modern versions. SuiteScript 2.0 was the first major rearchitecture, introducing a modular, object-oriented model. SuiteScript 2.1 builds on that foundation and supports modern ECMAScript (ES2019+) features such as arrow functions, template literals, const/let, promises, and async/await. When you migrate, targeting 2.1 gives you the most current language support and is Oracle’s recommended destination.

Why This Matters for Your Business

Even though nothing breaks overnight, letting 1.0 customizations linger carries real risk. As NetSuite pushes new releases twice a year, older scripts can surface deprecation warnings on the Release Preview account and, in some cases, behave unexpectedly against updated underlying functionality. New hires and partners are also increasingly trained on 2.x, so maintaining a 1.0 codebase can become harder and more expensive to support. Planning a deliberate migration now is far cheaper than being forced into a rushed rewrite later.

The Biggest Structural Differences

SuiteScript 2.x generally supports everything 1.0 does, but there is not always a one-to-one mapping. The most visible change is the overall shape of a script. A 1.0 script is essentially a set of global functions referenced by name in the UI. A 2.x script uses the AMD-style define pattern, imports the modules it needs, and returns an object whose properties are the entry points.

Example: a simple User Event script

Here is a typical SuiteScript 1.0 beforeLoad user event that sets a field value:

// SuiteScript 1.0
function beforeLoad(type, form, request) {
    if (type == 'create') {
        var record = nlapiGetNewRecord();
        record.setFieldValue('memo', 'Created via automation');
        nlapiLogExecution('DEBUG', 'Record type', record.getRecordType());
    }
}

And here is the equivalent in SuiteScript 2.1, using the define function, JSDoc annotations, and the N/record and N/log modules:

/**
 * @NApiVersion 2.1
 * @NScriptType UserEventScript
 */
define(['N/record', 'N/log'], (record, log) => {

    const beforeLoad = (context) => {
        if (context.type === context.UserEventType.CREATE) {
            const rec = context.newRecord;
            rec.setValue({ fieldId: 'memo', value: 'Created via automation' });
            log.debug({ title: 'Record type', details: rec.type });
        }
    };

    return { beforeLoad };
});

Notice several things at once: the JSDoc header (@NApiVersion and @NScriptType) is mandatory in 2.x, global nlapi* functions are replaced by module methods, method arguments become named objects rather than positional parameters, and nlapiLogExecution becomes log.debug.

Example: a searched loaded record

Loading a record and reading a field is another everyday operation. In 1.0:

// SuiteScript 1.0
var so = nlapiLoadRecord('salesorder', 12345);
var total = so.getFieldValue('total');

In 2.1 the same logic uses the N/record module:

const so = record.load({ type: record.Type.SALES_ORDER, id: 12345 });
const total = so.getValue({ fieldId: 'total' });

A few 1.0 features now use plain JavaScript rather than a NetSuite API. Date manipulation is the classic example: where 1.0 offered helper functions, 2.x expects you to use the native JavaScript Date object. Logging and printing also behave a little differently, and a small number of 1.0 APIs do not map to any 2.1 module at all, so those cases need individual attention.

Steps You Can Take Now

1. Inventory your existing scripts

Start by cataloging every script in your account and flagging which ones are still on SuiteScript 1.0. In NetSuite, go to Customization > Scripting > Scripts and note the API version column. Record the script type (user event, client, scheduled, Suitelet, Map/Reduce, and so on), where it is deployed, and how business-critical it is. This inventory becomes your migration roadmap and helps you prioritize the scripts that touch core processes first.

2. Understand the differences between 1.0 and 2.x

As the examples above show, 2.x is not just a syntax refresh. Review Oracle’s overview of the differences, paying special attention to the cases where behavior changes (logging, printing, and date handling) and where a 1.0 API has no direct 2.1 equivalent. Doing this reading before you touch code will save you from surprises mid-project.

3. Put each script into the proper 2.x structure

For entry point scripts, Oracle recommends first establishing the correct 2.x script-type structure. At a minimum this means adding JSDoc comments, the define function, and a return statement so the script conforms to the 2.x anatomy, exactly as shown in the user event example. Once the shell is in place, you can convert the internal logic. Custom module scripts can generally be converted call by call without this structural step.

4. Convert calls using the API Map

Work through each SuiteScript 1.0 call and replace it with its SuiteScript 2.1 equivalent, using Oracle’s SuiteScript 1.0 to 2.1 API Map as your reference. For example, nlapiLoadRecord becomes record.load, nlapiSearchRecord becomes search.create(...).run(), nlapiGetFieldValue becomes getValue({fieldId}), and nlapiSubmitRecord becomes record.save(). Watch for the cases where behavior differs or where functionality is now delivered through native JavaScript.

5. Test thoroughly in a sandbox

Never migrate directly in production. Validate each converted script in a sandbox or Release Preview account, exercising the full range of records and edge cases the original handled. Because logging, error handling, and some methods behave differently in 2.x, testing is where you catch the subtle regressions. Use the built-in log module and the Script Execution Logs to confirm behavior at each step.

6. Adopt 2.x for everything new

Beyond migrating legacy code, set an internal policy that all new development uses SuiteScript 2.1. This stops the technical debt from growing while you work through your backlog. Note that 2.x scripts can run alongside existing 1.0 scripts, so you can migrate incrementally rather than all at once, tackling the highest-risk scripts first.

A Practical Migration Timeline

• Weeks 1–2: Build the full script inventory and rank scripts by business impact.
• Weeks 3–4: Study the API map and convert one or two low-risk scripts as a pilot.
• Weeks 5–8: Convert and sandbox-test the core, high-impact scripts in batches.
• Ongoing: Roll converted scripts to production during a release window, and mandate 2.1 for all new work.

Final Thoughts

The move away from SuiteScript 1.0 is not an emergency, but it is a clear direction from Oracle that rewards early planning. Take an inventory, learn the differences, convert methodically against the official API map, test in a sandbox, and commit new work to 2.1. Handled proactively, the transition is a manageable project that leaves your account on a supported, future-ready foundation.

This article is based on Oracle NetSuite’s official documentation on transitioning from SuiteScript 1.0 to SuiteScript 2.x. Code samples are illustrative; always review the latest Oracle NetSuite Help Center guidance for your specific account and version.