Skip to content
SeamSetTalk to us

All guides

SuiteScript 1.0 to 2.1 migration: deadlines, inventory and an AI-assisted method

By Arnaud de Turckheim

Last verified against NetSuite 2026.2

In short

SuiteScript 1.0 to 2.1 migration means rewriting NetSuite scripts built on the legacy SuiteScript 1.0 API (global nlapi functions) into SuiteScript 2.1, the module-based standard since NetSuite 2026.2, and moving scripts tagged 2.0 or 2.x to 2.1 too. As of NetSuite 2026.2 (September 2026):

  • Deadlines. 2.0 and 2.x scripts: before 2028.1, when they run as 2.1 by default. 1.0 scripts: before 2028.2, when Oracle says “Legacy script versions will no longer run.” From 2027.1, Oracle fixes only critical 1.0 issues.
  • Inventory. Customization > Scripting > Scripts, API Version filter. No AI needed.
  • Paths. Oracle lists account preferences to test 2.0 code, its open-source netsuite-suitescript-upgrade skill for coding agents, the SuiteCloud Developer Assistant and manual guides. This guide uses the skill.
  • Method. In a sandbox, group by group: analyze, convert, compare with the original, deploy through SuiteCloud Development Framework (SDF). A person releases to production and watches the logs.
  • Hand checks. The skill’s validation is static. Sublists, dates, governance, RESTlet responses and error objects need testing.

Who this is for

Administrators who own years of scripts nobody fully remembers, the developers converting them, and IT managers who need a dated plan. Oracle’s API reference dates the 2.x record methods to 2015.2: older scripts are 1.0, and teams kept writing 1.0 for years after.

What you need

  • A sandbox, where Oracle says to convert and test (its skills page also accepts a development account). Refresh an old one at Setup > Company > Sandbox Accounts: it becomes a copy of production, so save sandbox-only work first, then review and block the integration records copied over (Oracle).
  • Roles. Administrator or Set Up Company to change the 2.1 preferences in General Preferences; they apply to the whole account, so sandbox only. SuiteScript permission: View to see script and deployment records, Edit to change them. The Developer role for SDF; more in the development guide.
  • Tools. The SuiteCloud CLI (Node.js 24 LTS, Oracle JDK 17 or 21), Claude Code, Codex or Cline, and Git.
  • A reviewer who reads JavaScript and knows the business process. Oracle says to review all generated code before production.
  • No secrets in shared code. Search old scripts for passwords, tokens and keys before any file reaches a cloud AI tool. Move them to Setup > Company > Preferences > API Secrets; Oracle says only SuiteScript 2.x APIs can use secrets.

Oracle’s timeline: SuiteScript 1.0 end of life

NetSuite release What changes
2026.2 SuiteScript 2.1 becomes the standard for new and existing scripts
2027.1 1.0 enters end-of-life support, “covering critical issues only”. Other problems require converting to 2.1 first
2028.1 1.0 scripts can no longer be deployed in new accounts; existing accounts still can. 2.0 and 2.x scripts “run as SuiteScript 2.1 by default”
2028.2 All new and existing scripts must use 2.1. The September 2026 release note adds: “Legacy script versions will no longer run.”

Sources: Transitioning To SuiteScript 2.1 and the 2026.2 September Minor Release notes. The transition guide calls the 2028.2 removal “expected”. Plan as if it is certain.

NetSuite ships two major releases a year, rolled out to accounts in phases. Counting from 2026.2, 2028.1 is three upgrades away and 2028.2 four. Your next upgrade date is on the What’s new in the Suite portlet of the home dashboard.

What to do, by script category

Scripts Action Deadline Test
1.0 server scripts Rewrite into modules and entry points; a new tag is not enough 2028.2; 2027.1 for full support Before-and-after scenarios (Step 4)
1.0 client scripts, on script records or custom forms Rewrite 2028.2 Same, in the browser
1.0 scheduled scripts that yield Rewrite; Oracle suggests Map/Reduce, which needs a new script record 2028.2 Same, plus scripts that schedule it
Shared 1.0 libraries Keep while 1.0 scripts load them; 2.1 callers need a 2.1 module 2028.2 With each caller
2.0 and 2.x server scripts Account preference, then tag @NApiVersion 2.1 2028.1 Preference (Step 4)
2.0 and 2.x client scripts Tag @NApiVersion 2.1; the preferences skip client scripts 2028.1 Retagged copy in the sandbox
SuiteApp and bundle scripts Ask the vendor Vendor’s plan Vendor’s release
Inactive or obsolete scripts Retire None Retire check (Step 1)

Per Oracle’s compatibility rules, one script cannot mix 1.0 and 2.x APIs, and nlapiScheduleScript cannot schedule a Map/Reduce script. From 2028.1, an untested 2.0 RESTlet can change its responses. Oracle does not say whether Execute As Version set to 2.0 will still hold then.

Step 1: Find every SuiteScript 1.0 and 2.0 script in NetSuite

Oracle documents three ways (source):

  1. Quick list. Customization > Scripting > Scripts, set the API Version filter to each version other than 2.1, such as 1.0 or 2.0.
  2. Reusable list. A saved search on script records where API Version is not 2.1, with results such as Name, ID, Script Type, API Version and Owner.
  3. Many scripts. Analytics > Workbooks > New Workbook, a dataset with script fields, 2.1 filtered out, grouped by API version or script type.

Oracle gives no SuiteQL (NetSuite’s SQL dialect) query. The list also misses:

  • Form-level client scripts. The Custom Code subtab of custom entry and transaction forms attaches a client script file to the form directly (Oracle).
  • Libraries. A script record’s Library Script File subtab (SuiteScript FAQ); define() dependencies in 2.x files.

Customization > Scripting also shows Script Deployments (status), Scripted Records (scripts per record type, in order) and Script Execution Logs (30 days). No logs does not prove a script is dead: logging depends on the code and the log level. Full map: Map and document a NetSuite account with AI.

Retire a script that is inactive, whose deployments all have Deployed cleared, or whose process is gone. Confirm with the process owner, and keep the file in Git so it can come back.

Prioritize. Oracle’s pages point two ways: start with low-complexity scripts to learn the process (Choosing A Migration Path), and start with scripts behind critical processes, high usage, integrations and complex dependencies (Transitioning To SuiteScript 2.1).

A workable order: one or two simple scripts, then the critical ones, in groups that share a record type or a library. Oracle says to monitor each group before the next.

Track type, version, owner, record types, process, callers, dependencies, complexity (Step 3) and decision: retire, migrate or ask the vendor.

Your SDF project can miss bundle and SuiteApp code: imports skip SuiteApp files, locked objects and files outside SuiteScripts (Step 2). Installed bundles are at Customization > SuiteBundler > Search & Install Bundles > List (Oracle: needs SuiteBundler enabled and the SuiteApp Marketplace permission), SuiteApps at Customization > SuiteCloud Development > Installed SuiteApp List.

Ask each vendor for its 2.1 plan now. Anchor Group, a NetSuite partner that sells migration services, calls vendor follow-up “the most time-consuming piece” of a migration.

Seen in practice. Anchor Group runs a prompt published on its blog in Sonar, its in-NetSuite assistant, under a view-only production role, after switching Sonar to its builder agent. The CSV adds each script’s owner email, vendor, a migrate-or-retire call, priority and complexity.

Owner emails need a role that can read employee records. Sonar is free to install, per Anchor Group, but runs on your own AI provider’s API key: you pay that provider per use, and it receives the prompts and query results. Run the secrets check first.

Step 2: Set up the project and Oracle’s netsuite-suitescript-upgrade skill

Create the project (once)

In the sandbox, an administrator checks SuiteCloud Development Framework and OAuth 2.0 (Setup > Company > Enable Features, SuiteCloud subtab) and gives you the Developer role. Then:

npm install -g @oracle/suitecloud-cli
suitecloud project:create --type ACCOUNTCUSTOMIZATION --projectname MyACP

From the project folder, suitecloud account:setup opens a browser login: use the sandbox only. Then add the guardrails that keep an agent out of production.

Import the scripts

suitecloud object:import --type ALL --scriptid ALL --destinationfolder "/Objects"
suitecloud file:list --folder "/SuiteScripts"
suitecloud file:import --paths "/SuiteScripts/shared_lib.js"
  • object:import pulls script records as XML and, in an account customization project, the files they reference (Oracle). Use -i to pick script types only, or if the non-interactive form fails (issue #1038).
  • file:import takes one path per call, or every file in a folder with -i (Oracle). Use it for files no script record references, such as libraries.
  • Not imported: SuiteApp files, locked objects, and files outside FileCabinet/SuiteScripts/ and a few template folders, so a script may arrive without its code. In a default project, files land under src/FileCabinet/SuiteScripts/.

Install the skill

netsuite-suitescript-upgrade, one of Oracle’s 10 agent skills, is open source under the Universal Permissive License: instructions and reference files for your agent, changing nothing in NetSuite by itself. Choose one option; both together install it twice.

Option A: Oracle’s plug-in for Claude Code, with its eight development skills (the other two are for business users):

claude plugin install netsuite-suitecloud@claude-plugins-official

On a machine that has never opened an interactive Claude Code session, first run claude plugin marketplace add anthropics/claude-plugins-official.

Option B: this skill only. Replace claude-code with codex or cline for those agents:

npx skills add oracle/netsuite-suitecloud-sdk --skill netsuite-suitescript-upgrade -a claude-code

Oracle documents -a codex and -a cline; -a claude-code comes from the skills CLI README.

On September 26, 2026, the skill held 125 nlapi* to N/ mappings, 34 nlobj* conversions, 13 unmapped APIs with workarounds, 16 breaking-change categories, and entry-point patterns for 11 script types, but none for plug-ins such as Custom GL Lines.

Step 3: Run the skill on one script

Oracle’s commands (source):

/netsuite-suitescript-upgrade analyze FileCabinet/SuiteScripts/customer_ue.js
/netsuite-suitescript-upgrade convert FileCabinet/SuiteScripts/customer_ue.js --annotated
/netsuite-suitescript-upgrade explain nlapiSearchRecord
/netsuite-suitescript-upgrade validate FileCabinet/SuiteScripts/customer_ue.js
  • In a default project, pass src/FileCabinet/SuiteScripts/customer_ue.js.
  • With the plug-in, type /netsuite-suitecloud:netsuite-suitescript-upgrade. In Codex, use Oracle’s explicit pattern: $netsuite-suitescript-upgrade followed by the task.
  • Options: --dry-run shows changes without editing the file, --annotated explains each change, --verbose adds detail.
  1. Analyze. Complexity, detected APIs, required N/ modules, risks, testing focus. Seven factors (lines, nlapi calls, subrecords, timezone dates, recovery points, module includes, sublist operations) score 1 to 3 points each: 7 to 10 is Low, 11 to 15 Medium, 16 to 21 High.
  2. Convert. --dry-run first, then --annotated. Output is always 2.1, without compatibility wrappers. Oracle asks you to confirm entry points, module dependencies, script IDs, deployment behavior and logic.
  3. Explain. One question at a time: explain indexing.
  4. Validate. Twenty pattern checks, such as leftover nlapi/nlobj calls, missing define(), 1-based sublist loops and log or util as variable names. FAIL while any Critical or High issue remains.

To size the project, analyze every file, then time one Low, one Medium and one High script end to end, tests included, and extrapolate.

Some 1.0 APIs have no 2.1 equivalent, such as nlapiSendFax (Oracle’s API map). The skill suggests a third-party fax service over N/https, or email. In a Suite Resources Corp vendor demo, a dunning script depends on it: a business decision for the process owner, before production.

Oracle calls validation “a static migration check, not a substitute for functional testing.” It never runs the script. On September 26, 2026, the skill’s files did not cover the 2.0-to-2.1 runtime differences below, and validation checked neither field IDs nor value types.

A converted entry-point file has this shape: Oracle requires JSDoc tags, define() and a return statement at a minimum. Illustrative:

/**
 * @NApiVersion 2.1
 * @NScriptType UserEventScript
 */
define(['N/record', 'N/log'], (record, log) => {
  const beforeSubmit = (context) => {
    // converted logic
  };
  return { beforeSubmit };
});

Oracle’s skill page converts a full 1.0 user event, and its sample conversions show every script type side by side.

Step 4: Deploy to the sandbox and test against the original

2.0 and 2.x server scripts: test the runtime first

In the sandbox, open Setup > Company > Preferences > General Preferences, check Execute SuiteScript 2.0 Server Scripts As 2.1, set Execute SuiteScript 2.x Server Scripts As to 2.1, and save (preference reference, how-to). Other Oracle pages word these labels slightly differently.

This switches every eligible 2.0 or 2.x server script at once. To test one script alone, tag it @NApiVersion 2.1 in the sandbox (Oracle). Not affected: client scripts, types 2.1 does not support, and records with Execute As Version set to 2.0.

Per Oracle, a script passes when it runs with the preference on, raises no validation error, completes its expected behavior (use the scenarios below) and logs no 2.1 compatibility errors. Then tag it 2.1.

Until then, the file is validated as 2.0 at upload, so 2.1-only syntax fails. Either preference can go back to 2.0 at any time.

Converted files: compare before and after

Our routine, built on Oracle’s validation checklist:

  1. List scenarios per entry point: record type, event (create, edit, delete), role, context (UI, CSV import, web services).
  2. Run them with the current script. Record field values, sublist lines, emails and log lines.
  3. Deploy to the sandbox: suitecloud project:deploy --dryrun, then suitecloud project:deploy. The file replaces the old one on the same script record, and NetSuite sets the record to 2.1 if the script type matches (September 2026 minor release). Script ID and deployments stay.
  4. Rerun on fresh records and compare every entry point, sublist, search, record operation and error path. Check that deployments and SDF objects point to the right files.
  5. Check the logs for 2.1 compatibility errors, and the table below.

RESTlets. Find the callers first: integration records (Setup > Integration > Manage Integrations) and their owners. Then, per Oracle, test each HTTP method with representative data, compare bodies with the old version, and check each caller’s assumptions.

Rename 1.0 variables called log or util: both are reserved in 2.1, and a record running both versions throws an error (Oracle).

Deploying the SDF object too? The skill says to drop 1.0 function-name fields such as <beforesubmitfunction>. Ignore its example root <scriptcustomization>: SDF uses the script-type object, such as <usereventscript>. Where it cites the unpublished /netsuite-sdf-leading-practices, use netsuite-sdf-safe-guide.

Step 5: Release to production and monitor

  1. Commit the converted file and the test evidence to Git, as Oracle asks, with who reviewed it, when and on what evidence (as in the Suite Resources Corp demo).
  2. A person deploys, never the agent: from a machine whose project default auth ID is production (Oracle’s example keeps sdf_sbx_deploy and sdf_prod_deploy apart), run suitecloud project:deploy --dryrun, read the preview, then suitecloud project:deploy. Avoid month-end close.
  3. The CLI does not ask for confirmation before a production deploy: the published 4.1.0 source skips the warning (Oracle’s Help Center does not describe this). Keep production credentials away from the agent.
  4. Never suitecloud file:upload to production: it overwrites the file without project validation.
  5. Check Customization > SuiteCloud Development > Deployment Audit Trail, then the execution logs before the next group, as Oracle recommends.

Rollback, decided before release:

  • Same record. Redeploy the previous file from Git. Oracle documents a record moving from 1.0 to 2.1, not back: rehearse in the sandbox and check the record’s API version and which code runs.
  • Side by side. Create a new script record for the 2.1 version, deployment status Testing: it runs only for the script owner (Oracle). In the sandbox, test with Deployed cleared on the old deployment. At release, set the new one to Released with the old one’s audience, and clear Deployed on the old one.

Rollback is the reverse. The cost: a new script ID changes Suitelet and RESTlet URLs and anything that calls or schedules the script by ID. A Released script with no audience still runs only for its owner, and Testing does not apply to scheduled scripts. See also what SDF never undoes.

What changes from 1.0 and 2.0 to 2.1 (check by hand)

Area What changes Source
Sublists Lines start at 0 in 2.x, at 1 in 1.0. Dynamic and standard record modes differ getSublistValue, skill
Dates nlapiAddDays/nlapiAddMonths have no 2.1 API: use JavaScript Date. Date fields need Date values, not strings (INVALID_FLD_VALUE), yet the skill’s example passes a string. 2.1 toLocaleDateString() defaults to short format Unmapped APIs, setValue, date strings
Checkboxes Booleans, not 'T'/'F' strings setValue, Oracle’s skill page
Client scripts 1.0 firefieldchanged true becomes ignoreFieldChange: false: the flag is inverted Skill
Governance 1,000 units for user event, client and Suitelet scripts; 5,000 RESTlet; 10,000 scheduled. 2.1 scheduled scripts cannot yield: Oracle suggests Map/Reduce. The skill’s costs for search.lookupFields (5) and search.create (10) differ from Oracle’s (1 and none) Limits, API costs
Errors nlobjError becomes N/error. In 2.1, JSON.stringify() on an Error built with a message omits message Skill, error properties
RESTlets 2.0 adds an internal JSON.stringify() to post(), 2.1 does not; with application/json, 2.1 returns an object post strings, return type
Numbers 616.00 is saved as 616 in 2.1; parseInt('08') returns 8 in 2.1, no value in 2.0 Trailing zeros, parseInt
Subrecords Saved with the parent; addresses are subrecords 1.0 vs 2.1
Syntax, debugging Strict mode, reserved words, const reassignment, for each...in, toSource. 2.1 scripts use the browser debugger, not the SuiteScript Debugger 2.0 vs 2.1

Common problems

Symptom Cause Fix
Syntax error uploading a file with 2.1 syntax Still tagged 2.0 or 2.x; validation follows the tag Tag it @NApiVersion 2.1
Still runs as 2.0 with a preference on Client script, unsupported type, Execute As Version set to 2.0, a 2.x-tagged script with only the 2.0 preference on, or a script NetSuite does not recognize as 2.1-compatible Check the tag, both preferences and the script record
Fails after a preference is enabled A 2.1 runtime difference Clear the 2.0 box or set the 2.x list back to 2.0, then reproduce in the sandbox
API version still 1.0 after replacing the file The new file has another script type; Oracle requires the same one Keep the type, or create a new script record
RESTlet returns an unexpected value post or return type handling Compare with the 2.0 version; update the caller
Skill calls netsuite-sdf-leading-practices, netsuite-suitescript-reference or netsuite-sdf-education Not published under those names Use netsuite-sdf-safe-guide, netsuite-suitescript-records-reference, netsuite-suitescript-learning
Validate passes, behavior changed Validation is static Functional tests in the sandbox

Sources: Oracle’s troubleshooting page, the September 2026 minor release, the skill’s files.

FAQ

When does SuiteScript 1.0 stop working?

Oracle fixes only critical 1.0 issues from 2027.1 and blocks 1.0 deployment in new accounts from 2028.1. In 2028.2, it says legacy versions “will no longer run.” Existing accounts can deploy 1.0 scripts until then.

Is SuiteScript 2.1 mandatory, even for 2.0 scripts?

Yes. Scripts tagged @NApiVersion 2.0 or 2.x, including recent ones written with ChatGPT, run as 2.1 by default from 2028.1 and must use 2.1 from 2028.2.

What is the difference between SuiteScript 2.0 and 2.1?

Same API functionality, per Oracle, on a newer engine with modern JavaScript (let, const, arrow functions, async/await). Error serialization, date strings, RESTlet responses and some number handling differ. @NApiVersion 2.x resolves to 2.0 by default.

How do I find all SuiteScript 1.0 scripts in NetSuite?

In Customization > Scripting > Scripts, filter API Version on each value other than 2.1, such as 1.0 and 2.0. Also check the Custom Code subtab of custom forms and each script’s library files.

Can I just change the tag of a 1.0 script to 2.1?

No. Oracle does not allow 1.0 and 2.x APIs in one script, so every nlapi call must become an N/ module call inside define(). A new tag is enough only for 2.0 and 2.x scripts, after a runtime test.

What happens if we do nothing?

2.0 and 2.x scripts switch to the 2.1 engine by default in 2028.1, tested or not. In 2028.2, Oracle says legacy versions will no longer run, without describing how such a script fails.

Why not just ask ChatGPT to convert the scripts?

Tim Dietrich, a NetSuite developer, reports that general models often return 1.0 code and invented field IDs. Oracle’s skill adds Oracle’s mapping tables and checks, but its validation is static and parts of its content are wrong. Treat each conversion as a draft.

Is Oracle’s upgrade skill free, and which AI tools can use it?

Yes, on GitHub under the Universal Permissive License; your AI tool’s plan and terms still apply to the code you send. Oracle’s docs name Claude Code, Codex and Cline; its April 2026 announcement claims more than 25 platforms.

Sources

Oracle NetSuite Help Center:

Oracle, other: the skill on GitHub, issue #1038, press release, April 28, 2026.

Tool vendors: Claude Code plugins, discovering and installing plugins, skills CLI.

Third party: Anchor Group (NetSuite partner; sells migration services, promotes its free Sonar assistant); Tim Dietrich, February 23, 2026 (NetSuite developer; co-builds Sonar with Anchor Group).

Videos (vendor demos, September 23, 2026): Anchor Group, “How to Fix NetSuite’s ‘Update Scripts to SuiteScript 2.1’ Warning” (Sonar); Suite Resources Corp, “SuiteScript Migration: 1.0 to 2.1, with the tests that prove it” (its own migration app).

SeamSet builds what a NetSuite account is missing from a request in plain words, with the discipline this migration needs: sandbox first, reviewed, and approved by your NetSuite admin before production.