Bound Parameters in NetSuite REST SuiteQL: What They Are and Why You Should Use Them

Bound parameters are a parameterized query technique where dynamic values are passed separately from the query string, preventing injection vulnerabilities and making queries easier to maintain. In SuiteQL, a bound parameter replaces an embedded value with a placeholder that NetSuite substitutes safely at execution time.

If you build SuiteQL queries in NetSuite that include dynamic values, such as a date range, a user-supplied record ID, or a value from another transaction, there is now a safer way to write them.

NetSuite 2026.2 adds support for bound parameters in REST SuiteQL queries. Instead of embedding values directly in the query string, you put placeholders in the query and pass the values separately. NetSuite handles the substitution safely.

Bound parameters parse the query once, then substitute values safely. The ? placeholder is never interpreted as SQL.

Quick answer

Bound parameters in NetSuite REST SuiteQL separate query structure from query values by replacing dynamic values in the SQL string with ? placeholders and passing the actual values in a separate params array. Available from NetSuite 2026.2 on the REST SuiteQL endpoint at POST /services/rest/query/v1/suiteql. The request body takes a q field with the query containing ? placeholders and a params array where each value maps positionally to a placeholder. NetSuite substitutes each placeholder with the corresponding params value, treating it as data rather than SQL. This prevents injection vulnerabilities where a crafted value could otherwise alter the query structure. The primary benefit is security: values in params cannot change the query structure regardless of what they contain. A secondary benefit is clarity: query logic and query values are readable separately. Use bound parameters whenever query values come from dynamic sources such as user input, request parameters, or values fetched at runtime.

What Is the Problem With Inline Values in SuiteQL?

A common pattern for building SuiteQL queries with dynamic values looks like this:

const status = getUserInput(); // value comes from somewhere dynamic

query.runSuiteQL({
  query: `SELECT id, tranDate FROM Transaction WHERE status = '${status}'`
});

If status contains unexpected input, it can alter the structure of the query. This is SQL injection, one of the most common and serious vulnerabilities in software that constructs database queries dynamically. In the context of SuiteQL via REST, a crafted value in that string can change what the query returns or how it behaves.

How Do Bound Parameters Work in SuiteQL?

With bound parameters, you replace each dynamic value in the query with a ? placeholder, and pass the actual values in a separate params array:

{
  "q": "SELECT id, tranDate FROM Transaction WHERE tranDate > SYSDATE + ? AND status = ?",
  "params": ["-7", "0"]
}

NetSuite substitutes each ? with the corresponding value from params in order. The values are treated as data, not as part of the query structure. A value that looks like SQL syntax is never interpreted as SQL.

Why Do Bound Parameters Matter in SuiteQL?

The separation between query logic and query values is what makes bound parameters secure. When a value is passed through params, NetSuite knows it is a value, regardless of what the string contains. There is no way for a value in params to change the structure of the query.

For queries built entirely from hardcoded values, the risk is low and bound parameters make less difference. The benefit is greatest for queries that include:

Values from user input
Values from request parameters or external systems
Record IDs or field values fetched from other sources at runtime

Where Should You Use Bound Parameters in SuiteQL?

Bound parameters are available on the REST SuiteQL endpoint:

POST /services/rest/query/v1/suiteql

In SuiteScript using the N/https module or in any REST client hitting this endpoint, the request body format is:

{
  "q": "SELECT id FROM Transaction WHERE custbody_field = ?",
  "params": ["value"]
}

The params array maps positionally to the ? placeholders in the query. The first ? gets the first value, the second ? gets the second, and so on.

What Is the Practical Default for Writing SuiteQL Queries?

Even for queries where injection risk seems low, using bound parameters is a good habit. It makes the intent of the query clearer (logic is separate from values), simplifies testing (you can change values without touching the query string), and eliminates an entire class of vulnerability without any meaningful cost.

Frequently asked questions

Q: Do bound parameters work in SuiteScript as well as direct REST calls? A: Bound parameters are a feature of the REST SuiteQL endpoint. When making calls to this endpoint from SuiteScript using the N/https module, you pass the same JSON body format with q and params fields and bound parameters work the same way.

Q: Can I use multiple placeholders in the same query? A: Yes. Each ? in the query maps positionally to the corresponding element in the params array. The first ? gets params[0], the second gets params[1], and so on. You can use as many placeholders as your query requires.

Q: Is there a performance difference between bound and inline queries? A: Bound parameters parse the query structure once and substitute values separately, which is generally comparable to string interpolation for typical query lengths. The main benefit is security and readability, not performance.

Q: Do bound parameters work with all SuiteQL data types? A: Values in the params array are passed as strings and NetSuite handles the type conversion based on the query context. For date values and numeric comparisons, pass the value as a string in the format expected by the query.

Q: Should I rewrite existing SuiteQL queries to use bound parameters? A: For queries with dynamic values, especially those where any value comes from user input or external sources, converting to bound parameters is recommended. For queries with only hardcoded values, the injection risk is low, but bound parameters still improve readability.

For step-by-step guidance on converting existing SuiteQL queries to use bound parameters, see How to Use Bound Parameters in NetSuite REST SuiteQL.

For help reviewing or rewriting SuiteQL queries in your account, see SuitePacific's NetSuite SuiteScript development service.