---
title: "SuiteScript 2.1 Migration Guide: Timeline, Testing, and Checklist"
description: Plan your SuiteScript 2.1 migration with the release timeline, script inventory, sandbox tests, conversion steps, and a practical checklist.
---

[Maayins Blog](https://blog.maayins.com)

# [SuiteScript 2.1 Migration Guide: Timeline, Testing, and Checklist](https://blog.maayins.com/suitescript-2.1-migration-guide-timeline-testing-and-checklist)

 Written by [Tushar Rai](https://blog.maayins.com/author/tushar-rai) | Sep 30, 2026, 2:07:30 AM

That “Update Needed” banner in NetSuite is a prompt to examine the scripts your business depends on. Oracle plans to require SuiteScript 2.1 for new and existing scripts by NetSuite 2028.2. More urgently, 2.0 and 2.x scripts will run under the 2.1 runtime by default in 2028.1. Your testing should start well before the final deadline.

 

This guide shows you how to inventory your scripts, decide which ones are worth keeping, rehearse the runtime change, and test the business processes behind the code. When the scope exceeds your team’s capacity, we can help with [NetSuite custom development](https://maayins.com/custom-development) and ongoing support.

**In this guide:**

- [Key takeaways](https://blog.maayins.com/suitescript-2.1-migration-guide-timeline-testing-and-checklist?hs_amp=true#key-takeaways)
- [What is changing in NetSuite?](https://blog.maayins.com/suitescript-2.1-migration-guide-timeline-testing-and-checklist?hs_amp=true#whats-changing)
- [What is the SuiteScript 2.1 timeline?](https://blog.maayins.com/suitescript-2.1-migration-guide-timeline-testing-and-checklist?hs_amp=true#timeline)
- [Why does NetSuite 2028.1 matter?](https://blog.maayins.com/suitescript-2.1-migration-guide-timeline-testing-and-checklist?hs_amp=true#why-2028-1)
- [What behaves differently in 2.1?](https://blog.maayins.com/suitescript-2.1-migration-guide-timeline-testing-and-checklist?hs_amp=true#differences)
- [How do you find scripts that need attention?](https://blog.maayins.com/suitescript-2.1-migration-guide-timeline-testing-and-checklist?hs_amp=true#find-scripts)
- [Which scripts should you keep?](https://blog.maayins.com/suitescript-2.1-migration-guide-timeline-testing-and-checklist?hs_amp=true#keep-scripts)
- [How do you test 2.0 and 2.x server scripts?](https://blog.maayins.com/suitescript-2.1-migration-guide-timeline-testing-and-checklist?hs_amp=true#test-scripts)
- [How do you convert SuiteScript 1.0?](https://blog.maayins.com/suitescript-2.1-migration-guide-timeline-testing-and-checklist?hs_amp=true#convert-1-0)
- [Can AI help with conversion?](https://blog.maayins.com/suitescript-2.1-migration-guide-timeline-testing-and-checklist?hs_amp=true#ai)
- [Migration checklist](https://blog.maayins.com/suitescript-2.1-migration-guide-timeline-testing-and-checklist?hs_amp=true#checklist)
- [Mistakes to avoid](https://blog.maayins.com/suitescript-2.1-migration-guide-timeline-testing-and-checklist?hs_amp=true#mistakes)
- [FAQ](https://blog.maayins.com/suitescript-2.1-migration-guide-timeline-testing-and-checklist?hs_amp=true#faq)

## Key Takeaways: SuiteScript 2.1 Migration

- SuiteScript 2.0 and 2.x scripts will run as 2.1 by default in NetSuite 2028.1.
- Scripts still on 1.0, 2.0, or 2.x will stop working in NetSuite 2028.2.
- A script that executes successfully can still produce a different transaction, date, number, or RESTlet response.
- Retire, replace, improve, or migrate each script based on its purpose, dependencies, and business risk.
- Our free readiness audit helps you prioritize the work and estimate the effort.

## What Is Changing in NetSuite?

SuiteScript 2.1 is the standard scripting model. Oracle’s transition covers SuiteScript 1.0 and scripts annotated `@NApiVersion 2.0` or `@NApiVersion 2.x`. Version 2.1 supports newer JavaScript language features and is the destination for existing customizations. Some modules, including N/llm and N/pgp, are supported only in 2.1.

Standard modules such as `N/record` and `N/search` keep the same API in 2.1, but they run on a newer JavaScript engine. That is where most surprises come from, including in code produced by automated converters. Changing the version annotation does not, by itself, prove that a script still performs its job. Review both code compatibility and the records, integrations, and reports the script affects. See Oracle’s [Transitioning to SuiteScript 2.1](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_7161922360.html) guide.

## What Is the SuiteScript 2.1 Timeline?

Oracle describes a phased transition. These are planned release milestones, not dates on your account’s upgrade calendar.

| Release | Planned change | Your move |
| --- | --- | --- |
| 2026.2 | SuiteScript 2.1 becomes the standard scripting model. | Inventory and plan. |
| 2027.1 | SuiteScript 1.0 receives critical-issue support only. | Start converting 1.0 scripts. |
| 2028.1 | 2.0 and 2.x scripts run as 2.1 by default. 1.0 scripts can no longer be deployed in new accounts; existing accounts can still deploy them. | Validate in Release Preview before your upgrade. |
| 2028.2 | All new and existing scripts must use 2.1. Scripts still on 1.0, 2.0, or 2.x stop working. | Complete the transition. |

*Sources: Oracle Help Center, [Transitioning to SuiteScript 2.1](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_7161922360.html), and SuiteAnswers 1047412, SuiteScript 2.1 Required for All Custom Scripts in NetSuite 2028.2 (updated September 23, 2026).*

For 2028.1, the key phrase is “by default.” Test your own account and its overrides rather than assuming every script has switched. Oracle’s [General Preferences guidance](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_3131752831.html) explains the compatibility and validation exceptions for the 2.0 test preference.

## Why Does NetSuite 2028.1 Matter?

Version 2.x can look like a future-proof annotation, but Oracle says it currently resolves to 2.0 by default. Oracle’s account-level preference can run 2.x server scripts as 2.1 for testing, with a separate preference for scripts explicitly annotated 2.0.

Plan your testing around 2028.1, when those scripts switch to 2.1 by default. Oracle says you can switch the preference back to 2.0 if something breaks, but treat that as a short-term fallback, not a plan: 2028.2 removes the option. Use the Release Preview account to see the impact before your production upgrade.

Pay particular attention to integrations and financial processes. A script that still runs might return a changed RESTlet value or alter a date format that another system depends on.

## What Behaves Differently in 2.1?

The SuiteScript API is the same in 2.0 and 2.1. The differences come from the newer JavaScript engine. These examples come from Oracle’s documentation:

| Behavior | SuiteScript 2.0 | SuiteScript 2.1 |
| --- | --- | --- |
| RESTlet returning `JSON.stringify(x)` with `Content-Type: application/json` | Caller receives a string | Caller receives an object |
| Default `toLocaleDateString()` output | December 21, 2012 | 2012-12-21 |
| `setValue(field, 616.00)` | Saves 616.0 (double) | Saves 616 (integer) |
| `parseInt('08')` | No value assigned | Returns 8 |
| JSON with a trailing comma | Parses successfully | Throws a syntax error |
| Assigning an undeclared variable | Runs without error | Throws a ReferenceError |

Oracle also lists differences in reserved words, error object properties, `const` reassignment, and legacy syntax such as `for each...in` and conditional catch blocks. See the full list in [Differences Between SuiteScript 2.0 and SuiteScript 2.1](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_158755248128.html).

## How Do You Find Scripts That Need Attention?

The fastest reusable option is a saved search on script records with the criteria **API Version is not 2.1**, returning name, ID, script type, API version, and owner. For a quick look, filter Customization \> Scripting \> Scripts by API version. For larger accounts, a SuiteAnalytics Workbook lets you group results by version and script type. See Oracle’s [Identifying Scripts That Are Not Using SuiteScript 2.1](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_0827101556.html).

Make sure your inventory includes every script type, including workflow action and mass update scripts, not just user event and scheduled scripts. Check bundles and SDF projects too, so a later deployment does not reintroduce an old version. Record each script’s deployments, owner, last-known purpose, and business process.

Trace dependencies too. Does a script call a RESTlet, write to a custom record, use a saved search, or feed an external integration? Ask vendors about SuiteApp or locked scripts you cannot maintain yourself. Rank financial, fulfillment, and integration scripts by impact before sorting by code length.

**Staring at a long script list?** Our free SuiteScript 2.1 Readiness Audit sorts it for you and tells you where to start. [Book your audit](https://maayins.com/support)

## Which Scripts Should You Keep?

| Decision | When it fits | Next action |
| --- | --- | --- |
| Retire | Unused, duplicated, or obsolete | Confirm dependencies, then remove safely. |
| Replace | Native features or a workflow now meet the need | Test the replacement and decommission the code. |
| Improve | Still needed, but fragile or undocumented | Refactor with tests and documentation. |
| Migrate | Still needed and working well | Test behavior, then update to 2.1. |

Moving dead code onto a newer engine adds maintenance work without preserving value. Make the keep-or-retire decision before you estimate development time.

## How Do You Test 2.0 and 2.x Server Scripts?

1. Refresh a sandbox or use an appropriate test environment. Check that integrations point to safe test endpoints, not live payment, warehouse, or fulfillment systems.
2. At Setup \> Company \> Preferences \> General Preferences, set the **Execute SuiteScript 2.x Server Scripts As** dropdown to 2.1 and, separately, check the **Execute SuiteScript 2.0 Server Scripts As 2.1** box as needed. Test the groups separately if possible.
3. Check which scripts actually execute as 2.1. The 2.0 preference affects compatible server scripts. Scripts that fail validation or explicitly have “Execute As” set to 2.0 may remain on 2.0.
4. Exercise real entry points: create transactions, run scheduled jobs, submit forms, and call RESTlets from their consuming systems.
5. Compare before-and-after records, field values, search results, response payloads, logs, and downstream results. Fix discrepancies and retest before changing the annotation.
6. When your Release Preview account is available for 2028.1, repeat the key tests there before your production upgrade.

These account-level preferences apply only to server scripts. Client scripts run in the user’s browser, so they are not part of this rehearsal, but they still need their annotation updated to 2.1 before 2028.2. Update each client script’s annotation, then test the forms people actually use in the browser. Convert 1.0 scripts separately. The preference is a rehearsal tool, not the final migration deliverable.

## How Do You Convert SuiteScript 1.0?

SuiteScript 1.0 uses global functions and objects, while 2.1 uses modules. Add the correct JSDoc tags, structure dependencies with `define()`, return the relevant entry points, and map each legacy call to the appropriate module method. For instance, `nlapiLoadRecord` maps to `record.load()`, but mappings are not always one-to-one.

Use Oracle’s [1.0-to-2.1 API map](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/chapter_4752722762.html) to identify calls without direct equivalents. Test record modes, searches, sublists, checkbox values, and date handling rather than relying on a mechanical find-and-replace.

## Can AI Help with Conversion?

Yes, with review. Oracle offers a [SuiteScript Agent Skill](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_0818030029.html) that can upgrade 1.0, 2.0, and 2.x scripts and custom objects to 2.1, and the SuiteCloud Developer Assistant for AI-assisted refactoring and testing. Oracle states that you must review all generated code before using it in production.

AI-assisted conversion can speed up code analysis and mapping. It does not know which report consumes a custom field or which external system expects a particular payload. Keep a developer and business owner responsible for review and acceptance.

A useful sequence is inventory, assess, convert, review, test, and validate. Use the resulting documentation to preserve ownership and explain the changes for the next release.

## SuiteScript 2.1 Migration Checklist

### Discover and decide

- Run a saved search on scripts where API Version is not 2.1.
- Include workflow action and mass update scripts, bundles, and SDF projects.
- Record owners, integrations, dependencies, and business criticality.
- Label each script retire, replace, improve, or migrate.
- Contact vendors about bundled scripts.

### Test and convert

- Configure safe sandbox integration endpoints.
- Test the 2.x and 2.0 server-script preferences separately.
- Verify which scripts actually ran on 2.1.
- Convert 1.0 scripts using Oracle’s API map.
- Update annotations on tested 2.0 and 2.x scripts.
- Update client script annotations and test them in the browser.
- Rehearse 2028.1 in your Release Preview account.

### Validate and deploy

- Compare transactions, searches, field values, and integration payloads.
- Test full business processes, not just individual script execution.
- Confirm no retained script still uses `@NApiVersion 2.0` or `2.x`, and no `nlapi*` or `nlobj*` calls remain.
- Deploy in manageable groups and monitor logs and downstream systems.
- Document what each script does and who owns it.

## Migration Mistakes to Avoid

- Planning only for 2028.2 while ignoring the 2028.1 default runtime change.
- Assuming a 2.x annotation already means 2.1.
- Assuming the sandbox preference switches every 2.0 script.
- Forgetting client scripts because the preference only covers server scripts.
- Checking for exceptions but not comparing business outputs.
- Pointing sandbox integrations at live systems.
- Converting obsolete scripts instead of retiring them.
- Accepting AI-generated code without developer and business review.

## Frequently Asked Questions

### When do legacy scripts stop working?

In NetSuite 2028.2. Oracle’s in-account banner and SuiteAnswers 1047412 both state that scripts still using SuiteScript 1.0, 2.0, or 2.x will stop working in that release. Before then, in 2028.1, 2.0 and 2.x scripts start running on the 2.1 runtime by default. Confirm your account’s release schedule as you plan.

### Do SuiteScript 2.0 scripts need a rewrite?

Not necessarily. Test each script under the 2.1 runtime and update the annotation only after confirming it produces the right results. Fix compatibility issues where tests reveal them.

### Does the preference test client scripts?

No. The account-level execution preferences apply to server scripts. Client scripts still need their annotation updated to 2.1, so update them and test through the forms and browser interactions people actually use.

### What about SuiteApp scripts?

Ask the vendor for its migration plan. Test its integrations and business workflows in your account even if the vendor owns the source code.

### How long will migration take?

That depends on the number and complexity of scripts, how many can be retired, and the depth of testing required. Inventory and risk assessment give you a defensible estimate.

## Start with a SuiteScript Readiness Audit

We provide experienced NetSuite developers and administrators for projects, backlogs, and ongoing [managed services](https://maayins.com/managed-services). Our free SuiteScript 2.1 Readiness Audit covers a full script inventory, keep-or-retire decisions, risk ranking, and an effort estimate.

[Book your free audit](https://maayins.com/support)

[View full post](https://blog.maayins.com/suitescript-2.1-migration-guide-timeline-testing-and-checklist)

```json
{
  "@context" : "http://schema.org",
  "@type" : "BlogPosting",
  "author" : {
    "@type" : "Person",
    "name" : "Tushar Rai"
  },
  "dateModified" : "2026-10-12T13:21:16.110Z",
  "datePublished" : "2026-09-30T02:07:30Z",
  "headline" : "SuiteScript 2.1 Migration Guide: Timeline, Testing, and Checklist",
  "image" : {
    "@type" : "ImageObject",
    "height" : 559,
    "url" : "https://47612832.fs1.hubspotusercontent-na2.net/hubfs/47612832/SuiteScript%202.1%20migration%20overview.jpeg",
    "width" : 1024
  },
  "mainEntityOfPage" : "https://blog.maayins.com/suitescript-2.1-migration-guide-timeline-testing-and-checklist",
  "publisher" : {
    "@type" : "Organization",
    "logo" : {
      "@type" : "ImageObject",
      "height" : 60,
      "url" : "/hs/hsstatic/content_shared_assets/static-1.4092/img/default-amp-logo.png",
      "width" : 60
    },
    "name" : "Maayins Technologies Blog"
  }
}
```