Migrating SuiteScript 1.0 to 2.1 with AI before 2028.2

Oracle now puts a release number on the end of SuiteScript 1.0. Its Transitioning To SuiteScript 2.1 guide, last updated 19 October 2026, says support for SuiteScript 1.0, SuiteScript 2.0 and scripts annotated with @NApiVersion 2.0 or 2.x "is expected to be removed in NetSuite 2028.2." For anyone still running old customizations, the move from SuiteScript 1.0 to 2.1 has a deadline, and Oracle has started shipping AI tooling to do the conversion. At SuiteWorld on 26 October 2026, a Director of Application Software Engineering at Oracle NetSuite presented "Use AI to Accelerate the Migration from SuiteScript v1.0 to v2.1", a session on using AI coding assistants for exactly this job.

Oracle says these tools "can accelerate migration," and its own documentation shows where their output still needs a person: some conversion mistakes deploy cleanly and change what a script does.

Oracle's SuiteScript 2.1 timeline

The 2026.2 release made SuiteScript 2.1 "the standard scripting model for new and existing scripts." From 2027.1, SuiteScript 1.0 gets critical fixes only: "Other problems will require you to convert scripts to SuiteScript 2.1 first." In 2028.1, 1.0 scripts can no longer be deployed in new accounts, and 2.0 and 2.x scripts start running as 2.1 by default. In 2028.2, "All new and existing scripts must use SuiteScript 2.1."

The 2.x annotation catches teams out. It reads like "latest 2," but Oracle's earlier versioning page stated that a value of 2.x "will resolve to 2.0 when the script is uploaded and executed" (archived copy, May 2026), and the current timeline only switches 2.0 and 2.x scripts to the 2.1 runtime by default in 2028.1. A script you converted to 2.x years ago is on Oracle's removal list too.

For those scripts Oracle offers a test switch. Two account preferences, "Execute SuiteScript 2.0 Server Scripts as 2.1" and "Execute SuiteScript 2.x Server Scripts as 2.1", run compatible server scripts on the 2.1 runtime without touching the files, and "You can change either account-level preference back to 2.0 at any time," per the preference docs. Nothing equivalent exists for 1.0 code. A 1.0 script has to be rewritten against the N/ modules, because "NetSuite does not support calling SuiteScript 1.0 APIs from SuiteScript 2.1 scripts," per Oracle's API map.

Oracle's agent skill and its fine print

Oracle published an open-source agent skill for the rewrite, netsuite-suitescript-upgrade, in its SuiteCloud SDK repository in April 2026. It has four modes (analyze, convert, explain and validate), and its description claims "125+ API mappings, 34 object conversions, 13 unmapped API workarounds" plus guidance on breaking behavioral changes. You install it with npx skills add oracle/netsuite-suitecloud-sdk --skill netsuite-suitescript-upgrade, and the README for Oracle's agent skills says they work across coding agents, Claude Code among them. Oracle's other tool, SuiteCloud Developer Assistant, is "an AI-powered coding assistant designed for SuiteCloud developers" that runs in VS Code through the Cline extension, per its guide.

The Help Center documents the skill as a supported migration path, with a warning attached: "Automated tools and agent skills can accelerate migration, but you must review all generated code, object updates, and deployment changes before using them in production." The skill's own page adds that "Validation is a static migration check, not a substitute for functional testing."

That review has to cover the skill's reference data as well as its output. The governance table in the skill's breaking-changes.md lists record.load at a flat 10 units. Oracle's record.load reference gives 10 units for transaction records, 2 for custom records and 5 for all other records. It is a small error, but an agent that plans governance budgets from that table will get them wrong for every non-transaction record.

The skill also has a blind spot on script types Oracle itself keeps on older versions. Its validate mode flags any @NApiVersion 2.0 or 2.x annotation as Critical, with no exception, while Oracle's Financial Institution Connectivity plug-in only supports SuiteScript 2.0: "Your entry point scripts and supporting library scripts must also use SuiteScript 2.0." The SDF object page repeats it: "SuiteScript 2.1 is not supported." Run the skill over a bank connectivity plug-in and it will push you to an upgrade NetSuite does not accept.

Inventory before you convert

Oracle's guide gives every legacy script three options: update it, test it on the 2.1 runtime first, or "Retire the script if it is inactive, obsolete, or duplicated." Start with the list. Customization > Scripting > Scripts filters by API version, and a saved search on script records with "API Version is not 2.1" gives you the full set, per Oracle's inventory page. Oracle asks you to "Give higher priority to high-usage scripts, integrations, and scripts with complex dependencies," and the migration-path page says to "Start with low-complexity scripts." Both make sense together: practice on simple scripts, then spend most of your review time on the ones that matter.

Check the script type of everything on that list before an agent touches it. Oracle's transition guide says that where "a feature or product area still requires an older SuiteScript version, follow the version requirements documented for that feature until related help content is updated." Apideck's own bundle is a case in point: Apideck's NetSuite bank feeds bundle runs on SuiteScript 2.1 except the connectivity plug-in, which Oracle limits to 2.0.

Bugs in SuiteScript 1.0 to 2.1 conversions

The API mapping is the easy part: Oracle's skill ships more than 125 of them. The bugs come from places where the same-looking call returns something different in 2.1, and Oracle's own worked example shows the first one. In the 1.0 user event script on the skill's Help Center page, an inactive-customer check reads customer.getFieldValue('isinactive') === 'T', because 1.0 returns checkbox values as the strings 'T' and 'F'. In 2.1, Oracle's Record.getValue reference says "All fields of type CHECKBOX return true or false." Oracle's converted version drops the comparison. A conversion that keeps === 'T' compiles, deploys and never blocks an inactive customer again.

Sublist loops have the same problem. 1.0 code walks lines from 1 to the line count, and in 2.x "line indexing begins at 0," per the setSublistValue reference. A loop copied without changing its bounds skips the first line and asks for one past the end.

Some models also "modernize" while they translate, and 2.1 limits that. Server-side async, await and promises are "only valid for a subset of modules: N/http, N/https, N/llm, N/query, N/search, and N/transaction," and Oracle's promises page says you get an error if you use them with any other module. A tidy async rewrite of a record update fails at runtime.

The phased rollout Oracle recommends has a trap of its own. In 2.1, log and util are reserved global names, and "If SuiteScript 1.0 and SuiteScript 2.1 scripts run on the same record, a SuiteScript 1.0 variable named log or util causes an error," per Oracle's API and language differences page. Converting one script on a record can break an unconverted one beside it.

A few 1.0 functions have no direct replacement at all. nlapiAddDays "does not have a SuiteScript 2.1 equivalent," and for nlapiSetRecoveryPoint and nlapiYieldScript the API map only notes that "The SuiteScript 2.1 Map/Reduce Script Type automatically incorporates yielding." A scheduled script that yields is a redesign into Map/Reduce, which deserves a human decision about how the work splits into stages.

If 2.0 RESTlets go along in the same project, their output can change shape too. Oracle's RESTlet return type note shows a RESTlet returning JSON.stringify(x) to an application/json request: the caller gets a string from 2.0 and an object from 2.1. Oracle's troubleshooting page says to "Review any calling integration for assumptions about response type, serialization, or error handling."

Testing a converted script

Oracle's Jest package, @oracle/suitecloud-unit-testing, "Supports unit testing for SuiteScript 2.x files," per its README. It has no stubs for 1.0, so you cannot write tests against the old script and rerun them against the new one. Record the old behavior in a sandbox instead: for each entry point, the inputs you send and the records, field values and responses that come out. Then run the converted script through the same cases. Oracle's own checklist asks for the same evidence: test all entry points, verify sublist behavior, searches, record operations and error handling, and "Compare behavior against the original customization."

Keep the script record. Oracle's instruction is to "update the existing SuiteScript 1.0 script record to use the converted file," after which NetSuite sets the record's API version to 2.1, per its script record page. The converted file must be the same script type. Script and deployment IDs then stay the same, and so do the URLs that outside systems call for your RESTlets.

The point Apideck made about AI-built accounting integrations holds here as well. An agent makes the first version cheap. The cost sits in the review and the testing, and those still need someone who knows what each script is for.

RESTlet callers face the same releases

When a 1.0 script is a RESTlet that an outside system calls, the releases that end 1.0 support also end the old ways of calling it. From 2027.1, Oracle says you will "no longer be able to create new integrations that use TBA for SOAP and REST web services, and RESTlets," per its TBA end-of-support notice. The 2026.2 release notes add that "As of 2027.1, all integrations that use NLAuth as an authentication method will stop working." With 2028.2, Oracle's SOAP overview says existing SOAP integrations "will stop working."

You will retest every converted RESTlet anyway, so move its callers to OAuth 2.0 in the same pass. The TBA end-of-support notice linked above has Oracle's full TBA timeline, and our NetSuite TBA to OAuth 2.0 migration guide covers which OAuth 2.0 flow fits a RESTlet caller and how to move accounts off TBA one at a time.

The share of the work a provider absorbs

If NetSuite is one of several systems your product connects to, a unified API provider takes most of this off your team, though not all of it. Apideck writes and maintains the SuiteScript in its NetSuite bank feeds bundle and tracks Oracle's version requirements for it, including the plug-in limit above, so customers don't port scripts themselves. Customers do install the bundle once. For bank feeds that also means Oracle's Bank Statement Parsers SuiteApp, a Format Profile and linking accounts, per the bank feeds setup guide.

Updates still need a customer admin. Apideck's NetSuite connection bundle is unmanaged, so when Apideck publishes a new bundle version, the admin applies it from Customization > SuiteBundler > Installed Bundles, and any permissions they added to the role by hand must be re-added afterwards, per the NetSuite connection guide. Customers also re-authorize when NetSuite's authentication requirements change the connection. Apideck's connector uses TBA today and will handle the OAuth 2.0 switch once for every connected account, instead of every customer of every product building it again.

Run Oracle's analyze mode across your File Cabinet this quarter and retire the scripts nobody uses. Keep the plug-in types Oracle pins to older versions out of any batch conversion, and record behavior in a sandbox before you convert the rest. For the NetSuite integrations your product needs alongside other ERPs, look at Apideck's NetSuite API integration before you write another RESTlet.