Implementation Guide

How to Apply SuiteScript Performance Patterns in NetSuite

A practical, step-by-step guide that turns the ten patterns into the right API for each job — with the exact governance costs and 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 Performance Patterns guide. The main article explains why scripts hit governance walls and slow the account; this page is the plain checklist for actually applying the patterns. Work through the steps in order — know your governance budget first — and use the official NetSuite documentation link under every step to confirm the exact API as you go.

Before you start — prerequisites

  • SuiteScript 2.1: write new scripts in 2.1 for modern language features and the best APIs.
  • A budget in mind: know your script type’s limit — User Event & Client get 1,000 units, Scheduled gets 10,000, RESTlet 5,000.
  • Test in the Debugger: measure usage with getRemainingUsage() before and after, in a non-production account.

What you'll set up

  1. Know your governance budget
  2. Read fields with search.lookupFields
  3. Update fields with record.submitFields
  4. Page large result sets — never query in a loop
  5. Cache reference data with N/cache
  6. Move heavy jobs to Map/Reduce
  7. Monitor usage & yield gracefully
1

Know your governance budget

Every script type has a fixed unit budget and every API call spends from it. Optimization starts with knowing both numbers.

API:  N/runtime → runtime.getCurrentScript().getRemainingUsage()
  1. Look up your script type’s limit (User Event 1,000; Scheduled 10,000; RESTlet 5,000; Map/Reduce per stage).
  2. Call getRemainingUsage() at key points to measure what each section actually costs.
  3. Treat exceeding the budget as a hard failure — it throws SSS_USAGE_LIMIT_EXCEEDED and abandons the run.
NetSuite docs SuiteScript Governance & Limits Script Type Usage Limits
2

Read fields with search.lookupFields

To read a few body fields, don’t load the whole record. lookupFields returns just what you ask for, for a fraction of the cost.

API:  N/search → search.lookupFields(options) — 1 unit
  1. Replace record.load (up to 10 units) with search.lookupFields (1 unit) when you only need values.
  2. Request only the columns you need; select fields return {value, text} objects.
  3. Use the .promise() variant for non-blocking reads in 2.1.
NetSuite docs search.lookupFields(options)
3

Update fields with record.submitFields

To set a few body fields, skip the load-and-save round trip. submitFields does an inline edit at roughly a third of the cost.

API:  N/record → record.submitFields(options) — 10 units vs ~30
  1. Use record.submitFields (10 units for transactions) instead of record.load + record.save (~30 units).
  2. It works for body fields that support inline editing — not sublist lines or subrecords.
  3. For line-level or nested changes you still need load/save or a transform.
NetSuite docs SuiteScript 2.x API Governance
4

Page large result sets — never query in a loop

A standard result set caps at 4,000 rows, and running a search or load inside a loop is the classic governance killer.

API:  N/search → Search.runPaged(options) — pageSize up to 1,000
  1. For more than 4,000 results, use Search.runPaged and iterate page by page.
  2. Pull reference data once before a loop, then read from memory inside it — never query per iteration.
  3. If you find yourself looping over thousands of rows, that’s the signal to move to Map/Reduce (Step 6).
NetSuite docs search.ResultSet (4,000 cap) Search.runPaged / PagedData
5

Cache reference data with N/cache

If every execution re-fetches the same tax codes, rates, or settings, you’re paying for the same lookup thousands of times. Cache it.

API:  N/cache → cache.getCache(); Cache.get({ key, loader })
  1. Create a named cache with cache.getCache and choose its scope (PRIVATE, PROTECTED, or PUBLIC).
  2. Use a loader so the expensive lookup runs only on a cache miss.
  3. Set a sensible TTL so cached values refresh, but rarely-changing reference data stays cheap.
NetSuite docs N/cache Module
6

Move heavy jobs to Map/Reduce

For large data volumes, no single execution has the budget. Map/Reduce splits the work, runs it in parallel, and gives each stage its own budget.

Script:  @NScriptType MapReduceScript → getInputData / map / reduce / summarize
  1. Return the dataset from getInputData; process one key at a time in map or reduce.
  2. Choose the concurrency (parallelism) on the deployment to balance speed against account limits.
  3. Keep map/reduce keys under 3,000 characters and values under 10 MB.
NetSuite docs Map/Reduce Script Type
7

Monitor usage & yield gracefully

The difference between a script that fails halfway and one that finishes: stop cleanly before you hit zero.

Pattern:  getRemainingUsage() checks + Map/Reduce auto-yield
  1. In long loops, check getRemainingUsage() and break to save state and reschedule before the limit.
  2. In Map/Reduce, let the framework yield automatically when a job nears a governance limit.
  3. Make work resumable — persist progress so a yield or restart never loses data.
NetSuite docs Map/Reduce Reference (Yielding)

A note on accuracy: exact usage-unit costs vary by record category (custom, non-transaction, and transaction records cost different amounts), and APIs evolve between releases. The figures here reflect standard transaction-record costs; always confirm the governance for each method against its official reference, and measure real usage with getRemainingUsage() in your own account.

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 keeps scripts fast and within governance. What sits beyond the core patterns — a Map/Reduce architecture for huge jobs, custom caching layers, concurrency design, and usage monitoring — is engineering work. It often means restructuring how work is batched and yielded, on top of the lookup, submit, and paging patterns above.

Governance limits bite hardest at scale and at month-end, so measure real usage units in a Sandbox under production-like volume before you rely on a script. For the full background on each decision — the governance model and where units disappear — read the companion guide.

Back to the main article
SuiteScript hitting governance walls? Our NetSuite engineers profile slow scripts, swap heavy calls for lightweight APIs, and re-architect batch jobs as Map/Reduce — so your customizations finish reliably as volume grows.
Talk to a SuiteScript 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.