NetSuite REST API: Authentication, SuiteQL, Limits and What Replaces SOAP

The NetSuite REST API, officially SuiteTalk REST web services, lets another system read and write NetSuite records over HTTPS with JSON. You use the record service to get, create, update and upsert individual records, and the query service to run SuiteQL queries that return many rows at once. Oracle recommends OAuth 2.0 for authentication and calls REST the technology that replaces SOAP: no new SOAP or token-based authentication (TBA) integrations can be created from NetSuite 2027.1, and both stop working in 2028.2. This guide covers what you need to build against it: endpoints, authentication, reading, writing, limits, and when to use something else.

What the NetSuite REST API covers

REST web services sit on an account-specific domain, <accountID>.suitetalk.api.netsuite.com, and are split into services. The two you use most:

• Record service (/services/rest/record/v1/): one record at a time, for example GET /record/v1/customer/1234 to read a customer or POST /record/v1/salesOrder to create an order. Each record type also has metadata describing its fields, which NetSuite's REST API Browser lets you explore.
• Query service (/services/rest/query/v1/suiteql): SuiteQL, NetSuite's SQL-style query language, for reading many rows and joining record types in one request.

That split is the first design decision in any integration: read with SuiteQL, write with the record service. Pulling 5,000 open orders one record at a time costs 5,000 requests against your concurrency limit; one paged SuiteQL query costs a handful.

Authentication: OAuth 2.0, and what happens to TBA

Oracle's guidance is plain: OAuth 2.0 is the preferred method, and new integrations should use REST with OAuth 2.0. Two OAuth 2.0 flows matter for integrations:

• Authorization code grant: a user approves the application once and it receives tokens to act as that user and role. Typical for apps a person connects interactively.
• Client credentials (machine-to-machine): no user in the loop. You tick Client Credentials (Machine to Machine) Grant on the integration record, then map the application, an entity, a role and a certificate on the OAuth 2.0 Client Credentials (M2M) Setup page. The integration sends a JWT signed with the certificate's private key to the token endpoint, /services/rest/auth/oauth2/v1/token, and gets a short-lived access token back. Each integration, entity and role combination can have up to five active certificates.

Two things catch teams out with M2M. The setup is not copied between accounts, and it is cleared every time a sandbox is refreshed, so plan to redo the certificate mapping after each refresh. And when a certificate expires or is revoked, the flow stops until you create a new mapping.

TBA timeline. From NetSuite 2027.1, no new TBA integrations can be created for SOAP, REST or RESTlets; existing ones keep working until support ends in 2028.2. If an integration still runs on TBA, our TBA deprecation guide covers the move to OAuth 2.0.

Reading data: records and SuiteQL

For a single known record, a GET on the record service is simplest. For anything else, use SuiteQL. You send it as a POST to the suiteql resource with the query in the body under q, and the Prefer: transient header, which Oracle's examples include as required:

POST https://<accountID>.suitetalk.api.netsuite.com/services/rest/query/v1/suiteql?limit=500&offset=0
Authorization: Bearer <access token>
Content-Type: application/json
Prefer: transient

{ "q": "SELECT id, tranid, entity, trandate FROM transaction WHERE type = 'SalesOrd' AND trandate >= TO_DATE('2026-11-01', 'YYYY-MM-DD')" }

The response carries the rows plus hasMore, offset, totalResults and links to the next page. Keep requesting with a larger offset until hasMore is false. One limit to design around: a SuiteQL query returns at most 100,000 results in total, however you page it. For bigger extracts, Oracle points to SuiteAnalytics Connect; in an integration, the practical fix is to narrow each query, for example by date range or last-modified date, so every run stays well under the cap.

If you build in n8n, our n8n NetSuite pagination guide shows the paging loop node by node.

Writing data: create, update, upsert, async and batch

• Create: POST to the record type, for example POST /record/v1/customer. The new record's location comes back in the response headers.
• Update: PATCH the record with only the fields you change.
• Upsert: PUT with an external ID in the URL, for example PUT /record/v1/customer/eid:SHOP-10042. NetSuite creates the record if no match exists and updates it if one does. Oracle allows upsert only with PUT and an external ID. This is the safest way to sync records from another system, because a retry can't create a duplicate.
• Asynchronous requests: add Prefer: respond-async to any request and NetSuite answers HTTP 202 with a job URL under /services/rest/async/v1/job/ to poll for the result. You can send an idempotency key with an async request; resubmitting the same key returns a conflict pointing at the original job instead of running it twice.
• Batch: batch operations run asynchronously and take up to 100 records per request, which suits nightly loads.

Concurrency limits and errors

NetSuite doesn't cap requests per minute; it caps how many run at the same time. The limit is set per account from its service tier, plus 10 for each SuiteCloud Plus license, and it is shared: web services (SOAP and REST) and RESTlet requests all draw from the same pool. Development accounts stay at a base of five. When a request would exceed the limit, REST returns HTTP 429 with CONCURRENCY_LIMIT_EXCEEDED and the request is not processed. Requests that run longer than 15 minutes time out.

What that means in practice:

• Retry 429s with exponential backoff; they are expected under load, not a bug.
• Know what else uses the pool. A new integration can start failing because an unrelated RESTlet or an iPaaS sync is busy at the same time.
• Read with SuiteQL and write in batches, so each job uses fewer slots.
• Schedule heavy loads away from business hours, when users' own integrations are quieter.

REST vs SOAP vs RESTlets vs an integration platform

Oracle's own target state is REST with OAuth 2.0. An integration platform doesn't change that; it calls the same services. The difference is how much of the plumbing above you build and maintain yourself. We compare the platforms in n8n vs Celigo, and cover the n8n route in our n8n NetSuite integration guide.

Getting started checklist

1. Enable the features: REST Web Services and OAuth 2.0, under Setup > Company > Enable Features > SuiteCloud.
2. Create a dedicated integration role with only the record and REST web services permissions the integration needs. Never use an administrator role.
3. Create an integration record for the application and choose the OAuth 2.0 flow: authorization code, or client credentials with a certificate mapping for machine-to-machine.
4. Test in a sandbox: one GET, one SuiteQL query with paging, one upsert by external ID. Remember that a sandbox refresh clears M2M mappings.
5. Add retry with backoff for 429s and decide where failed records go before you go live.

Frequently Asked Questions

Does NetSuite have a REST API? Yes. SuiteTalk REST web services let other systems read and write NetSuite records over HTTPS with JSON, through a record service for individual records and a query service for SuiteQL. Oracle positions it as the replacement for SOAP web services.

How do I authenticate to the NetSuite REST API? With OAuth 2.0, which Oracle recommends: the authorization code grant when a user connects the app, or the client credentials (machine-to-machine) grant with a certificate for server-to-server integrations. Token-based authentication still works for existing integrations, but no new TBA integrations can be created from NetSuite 2027.1 and support ends in 2028.2.

How do I query many records through the NetSuite REST API? Send a SuiteQL query as a POST to /services/rest/query/v1/suiteql with the Prefer: transient header, and page through the results with the limit and offset parameters until hasMore is false. A single SuiteQL query returns at most 100,000 results.

What are the NetSuite REST API rate limits? NetSuite limits concurrent requests, not requests per minute. The limit depends on the account's service tier plus 10 per SuiteCloud Plus license, and it is shared by SOAP, REST and RESTlet requests. Exceeding it returns HTTP 429 with CONCURRENCY_LIMIT_EXCEEDED.

Should I use REST, SOAP or a RESTlet? Use REST for new integrations. SOAP is being retired: no new SOAP integrations from 2027.1 and removal in 2028.2. Use a RESTlet only when custom SuiteScript logic has to run inside NetSuite.

Sources

Oracle NetSuite documentation: REST Web Services and Other Integration Options; REST Web Services URL Schema and Account-Specific URLs; Executing SuiteQL Queries Through REST Web Services; OAuth 2.0; OAuth 2.0 Client Credentials Setup; Preparing for TBA End of Support; SOAP Removal Plans FAQ; Using the Upsert Operation; Sending an Asynchronous Request; Batch Operations; Concurrency Governance Limits; Error Handling in REST Web Services.

Entech Solutions is a certified Celigo partner and builds NetSuite integrations on Celigo, n8n and the NetSuite APIs directly. If you're planning a REST integration or moving one off SOAP or TBA, talk to us.