NetSuite REST API vs RESTlets: choosing an integration API
SuiteTalk REST web services give you standard create, read, update and delete on NetSuite records plus a SuiteQL endpoint. A RESTlet is your own SuiteScript endpoint with whatever contract you design. Use REST for plain record access; use a RESTlet when one call must do several things in NetSuite.
- Updated
- October 5, 2026
- Written by
- Nitya Hoyos
- Covers
- Approach, trade-offs
- Questions
- 3 answered below
(01)The situation
SuiteTalk REST web services expose NetSuite records at standard URLs, with metadata describing each record and its fields, including custom ones. For an integration that reads and writes ordinary records, this means no NetSuite-side code to deploy and maintain. It also offers the SuiteQL endpoint, which is often the simplest way for an outside system to read data. Its limits are that each call does one thing, the record shape is NetSuite’s rather than yours, and business rules have to live in the caller.
A RESTlet is a SuiteScript server script with get, post, put and delete entry points. The caller sends whatever payload you define, and the script can look up, validate, create several records and return a shaped response in one call. That makes RESTlets a good fit for idempotent order creation, for hiding NetSuite’s record structure from a portal or partner, and for logic that must run inside NetSuite. The cost is code you own: it needs deployment, tests and someone who knows SuiteScript.
Both count against your account’s concurrency limit, both support token-based authentication and OAuth 2.0, and both run as a NetSuite role whose permissions decide what they can do. A RESTlet also has a governance budget per call, so a script that loops over many records has to be written with that in mind. Many integrations end up using both: REST for simple reads and lookups, a RESTlet for the writes that need rules.
(02)The options
Which approach fits
| Approach | Best for | Trade-off |
|---|---|---|
| SuiteTalk REST web services | Reading and writing standard and custom records; SuiteQL queries from outside NetSuite. | One record per call; your rules live in the caller. |
| RESTlet | Multi-step writes, idempotent order creation, a stable contract for a portal or partner. | SuiteScript to deploy, test and maintain; per-call governance. |
| SOAP web services | Existing integrations already built on it. | Oracle directs new integrations to REST; avoid it for new work. |
(03)Example
/**
* @NApiVersion 2.1
* @NScriptType Restlet
*/
define(['N/record', 'N/search'], (record, search) => {
// Creates a sales order once per external ID. A retry after a timeout
// returns the existing order instead of creating a duplicate.
const post = (body) => {
const existing = search.create({
type: search.Type.SALES_ORDER,
filters: [['externalid', 'anyof', body.externalId], 'AND', ['mainline', 'is', 'T']],
}).run().getRange({ start: 0, end: 1 });
if (existing.length) return { id: existing[0].id, created: false };
const order = record.create({ type: record.Type.SALES_ORDER, isDynamic: true });
order.setValue({ fieldId: 'entity', value: body.customerId });
order.setValue({ fieldId: 'externalid', value: body.externalId });
body.lines.forEach((line) => {
order.selectNewLine({ sublistId: 'item' });
order.setCurrentSublistValue({ sublistId: 'item', fieldId: 'item', value: line.itemId });
order.setCurrentSublistValue({ sublistId: 'item', fieldId: 'quantity', value: line.quantity });
order.commitLine({ sublistId: 'item' });
});
return { id: order.save(), created: true };
};
return { post };
});(04)Where it goes wrong
The mistakes that cost the most
- 01Writes without an external ID or another idempotency key turn every client retry after a timeout into a duplicate record.
- 02User event scripts and workflows on the target record run on integration writes too; a slow one makes every API call slow.
- 03Integration roles with Administrator access work in testing and become a security problem in production. Give the integration its own role with only the permissions it needs.
- 04Concurrency is shared by every integration in the account, so a bulk sync can starve the storefront’s order calls unless it is throttled.
(05)Before you build
When not to do this
Don’t write a RESTlet to wrap a single record read or update that REST web services already do; it adds code to maintain without adding anything the caller needs.
(06)Questions
What is a NetSuite RESTlet?
A RESTlet is a SuiteScript server script exposed as an HTTP endpoint. You define the request and response, and the script can read and write any records its role allows.
What is SuiteTalk REST?
SuiteTalk REST web services are NetSuite’s standard REST API for records, with metadata for each record type and a SuiteQL query endpoint. The REST Web Services feature must be enabled in the account.
Should new NetSuite integrations use SOAP?
No. Oracle directs new integrations to REST web services and RESTlets. Existing SOAP integrations keep working on the endpoint versions they use but should be planned for migration.
Free checklist