Implementation Guide

How to Migrate SuiteScript 1.0 to 2.1 in NetSuite

A practical, step-by-step guide that turns the playbook into a real migration — the audit, the official API map, the module rebuild, and a safe rollout — with links to the official NetSuite documentation so you can verify everything for yourself.

Practical developer guide · Backed by the official NetSuite Help Center

Chief Technology Officer · 3x NetSuite Certified
Updated 8 min read
Back to the main article

This is the practical companion to our SuiteScript 1.0 to 2.1 Migration guide. The main article explains why 1.0 is a liability and what 2.1 buys you; this page is the plain checklist for actually doing the migration. Work through the steps in order — audit first, roll out sandbox-first — and use the official NetSuite documentation link under every step to confirm the exact API as you go.

Before you start — prerequisites

  • A sandbox: do the whole migration in a Sandbox or Release Preview account first — never in Production.
  • Source control: get your scripts into Git (e.g. via SuiteCloud CLI/SDF) so every change is reviewable and reversible.
  • Target 2.1: write all new code as SuiteScript 2.1 (@NApiVersion 2.1) for modern language features.

What you'll set up

  1. Audit your 1.0 codebase
  2. Map every 1.0 API to its 2.x equivalent
  3. Rebuild on the AMD module architecture
  4. Adopt SuiteScript 2.1 async/await
  5. Add real error handling
  6. Deploy with the right JSDoc tags
  7. Roll out sandbox-first
1

Audit your 1.0 codebase

You can’t plan a rewrite you haven’t measured. Inventory every 1.0 script and learn where 2.x differs before touching code.

Go to:  Customization > Scripting > Scripts (filter by API Version)
  1. List every script, its type, deployments, and dependencies; flag the high-risk and high-traffic ones.
  2. Read the differences overview so you know what changes structurally (modules, subrecords, error handling).
  3. Prioritize: start with small, low-risk scripts to build a pattern before tackling the critical ones.
NetSuite docs 1.0 vs 2.x Differences Converting a 1.0 Script
2

Map every 1.0 API to its 2.x equivalent

Your migration dictionary. Each nlapi* function and nlobj* object maps to a 2.x module method — or a documented workaround where there isn’t a 1:1.

Reference:  nlapi* / nlobj* → N/ modules (official API Map)
  1. Look up each call in the 1.0→2.x API Map (functions and objects are listed separately).
  2. Watch for the not directly mapped cases — some 1.0 APIs become plain JavaScript or move to a different module.
  3. Remember subrecords (like addresses) work fundamentally differently in 2.x.
NetSuite docs 1.0 → 2.x API Map API Map — Functions (nlapi)
3

Rebuild on the AMD module architecture

2.x scripts are modular. An entry-point script uses define() to load only the modules it needs, and supporting logic lives in reusable custom modules.

Code:  define(['N/record'], (record) => { ... return { ... }; })
  1. Wrap each entry-point script in a single define() with its dependency list and a callback.
  2. Return an object whose keys are entry points (e.g. beforeSubmit) for one — and only one — script type.
  3. Use require() only for ad-hoc loading; move shared logic into custom modules.
NetSuite docs Anatomy of a Script define() Function
4

Adopt SuiteScript 2.1 async/await

2.1 brings modern JavaScript — including non-blocking server-side promises — so you can replace callback nesting with clean async/await.

Code:  @NApiVersion 2.1 — await in N/search, N/query, N/https, N/http, N/transaction
  1. Tag scripts @NApiVersion 2.1 to unlock promises, destructuring, and optional chaining.
  2. Use await with the .promise() APIs in the supported modules to flatten async flows.
  3. Remember: async/await improves readability — it does not bypass governance (Step costs are unchanged).
NetSuite docs Promise Object Promises in 2.1 Server Scripts
5

Add real error handling

1.0’s “return false and hope” habit hides failures. 2.x gives you structured errors you can create, throw, catch, and log.

Code:  N/error.create({ name, message }) + try / catch + log.error
  1. Create custom errors with error.create and throw them where data is invalid or missing.
  2. Wrap risky operations in try/catch; log with log.error so failures are visible in execution logs.
  3. Decide deliberately whether each error should halt the script or be caught and recovered.
NetSuite docs N/error — Create & Throw
6

Deploy with the right JSDoc tags

A 2.x script won’t deploy without the right metadata. Tag it, upload it, then create the script record and deployment.

Code:  @NApiVersion 2.1 & @NScriptType UserEventScript (etc.)
  1. Add the required @NApiVersion and @NScriptType JSDoc tags; the file must have exactly one define() and one return interface.
  2. Upload to the File Cabinet, then create the Script record and a Deployment (or deploy with SDF).
  3. Set the same execution context, roles, and parameters the old 1.0 deployment used.
NetSuite docs Entry Point Validation & JSDoc Script Creation Process
7

Roll out sandbox-first

Migration risk is rollout risk. Move one script at a time, prove it in Sandbox, run old and new side by side, then cut over.

Process:  Sandbox → parallel run → cut over (with rollback)
  1. Validate each migrated script in Sandbox against real data and the old script’s output.
  2. Where possible, run the 1.0 and 2.x versions in parallel and compare results before disabling the old one.
  3. Cut over deployment by deployment, keeping the previous version ready to re-enable as a rollback.
NetSuite docs SuiteScript 2.x Script Types

A note on accuracy: NetSuite menu paths, modules, and supported async APIs evolve between releases (the set of modules that support server-side await, for example, has grown over time). Always confirm each mapping and capability against its official reference, and test the migrated script in Sandbox before cutting over in Production.

Official NetSuite documentation

Every step links to the source. Full help center: NetSuite Applications Suite — Online Help.

Where native setup ends and engineering begins

Everything above gets your scripts onto the modern 2.1 runtime. What sits beyond a mechanical port — async refactors, a real error-handling architecture, performance re-tuning under 2.x governance, and regression coverage — is engineering work. It often means restructuring modules and adding tests, not just swapping API calls.

A migration touches live business logic, so port in a Sandbox, run both versions side by side where you can, and validate every script before cutting over. For the full background on each decision — the API map, the module model, and the rollout plan — read the companion guide.

Back to the main article
Planning a SuiteScript migration? Our NetSuite engineers audit your 1.0 estate, rewrite scripts on the 2.1 module architecture with proper error handling, and roll out Sandbox-first — so nothing breaks in Production.
Talk to a NetSuite migration engineer

Documentation links point to the official Oracle NetSuite Help Center (docs.oracle.com). Exact menu paths and feature names vary by NetSuite version and edition — confirm each step against the linked Help Center page and validate in Sandbox first.