SuiteScript or SuiteQL? A field guide for NetSuite teams

The one-sentence rule

Use SuiteQL when you want to read something. Use SuiteScript when you want NetSuite to do something.

That covers 90% of the real decisions. The remaining 10% is where teams waste time, and it is where most consulting hours go. Let’s walk through the decision tree.

When SuiteQL is the right answer

SuiteQL is Oracle’s SQL dialect layered on top of the NetSuite data model. It ships with read-only access to a surprising amount of the record catalog, including transaction, customer, item, employee, subsidiary, and most custom records.

Reach for SuiteQL when:

• Finance asks a one-off analytical question (“which customers haven’t ordered in 60 days but did over $50k last quarter?”).
• You need a data export that a saved search can’t cleanly join (transaction lines + related customer + subsidiary currency in one row, for example).
• You want the answer now and don’t need the result to persist as a scheduled job.
• You want to prototype a metric before deciding whether it deserves a dashboard tile.

The failure mode here is writing SuiteQL for things SuiteQL can’t do: write records, call external APIs, run on a schedule, or react to user events. For those, you need SuiteScript.

When SuiteScript is the right answer

SuiteScript 2.1 is the modern scripting runtime in NetSuite. It runs server-side and client-side, it deploys as a record, and it comes in several flavors — User Event, Scheduled, Map/Reduce, Restlet, Suitelet, Client Script, and Portlet.

Reach for SuiteScript when:

• Something needs to happen when a record saves, transitions, or gets created.
• You need to call an external API (Stripe, Salesforce, a Slack webhook) from NetSuite.
• A manual process needs to run on a schedule with no human in the loop.
• You need to expose a custom UI inside NetSuite (Suitelet) or a custom endpoint (Restlet).

The failure mode here is the opposite: writing a 400-line User Event script when a saved search and a SuiteQL report would have answered the actual question.

The gray zone: reports that feed automations

Most consulting bills come from the gray zone. Someone wants a dashboard tile that also triggers an action. Or an export that emails finance every Monday. Or a SuiteQL result that feeds a Map/Reduce job.

The clean pattern is: keep the question in SuiteQL, and keep the action in SuiteScript. A Scheduled Script runs the SuiteQL, grabs the result, and takes action. The SuiteQL stays editable by an admin. The SuiteScript stays small and focused.

Teams that conflate the two end up with thousand-line scripts that embed business logic that should have been a query. Then six months later, a new analyst rewrites it as a saved search, and nobody knows which source of truth is real.

What SuiteGenius picks automatically

When you ask SuiteGenius a question, it reads your intent and picks the right tool. “Show me customers who haven’t ordered in 60 days” becomes SuiteQL. “Email me the customers who haven’t ordered in 60 days every Monday” becomes a Scheduled Script that wraps the SuiteQL. “Block the save on a sales order if the customer is on credit hold” is a User Event.

You see exactly which artifact you’re about to get before you run it. For most questions, the right answer is a one-paragraph SuiteQL. For the rest, SuiteGenius generates a SuiteScript 2.1 file you can review, tweak, and deploy.

The takeaway

Default to SuiteQL. Upgrade to SuiteScript when you actually need NetSuite to act, not answer. And keep the boundary clean — query for reads, script for writes.

If you’re spending more than an hour deciding which to use, that’s the exact moment to try SuiteGenius. First 20 queries are free.