Your e-commerce site needs to send its orders to NetSuite. Your CRM needs to retrieve invoices. Your payroll tool needs to post its journal entries. Behind each of these connections lies the same technical question: which API should you use?
NetSuite offers three: SOAP, REST and RESTlets. For years, the choice mostly came down to developers’ preferences. Not anymore: NetSuite has scheduled the end of SOAP, and the API you choose now determines how long your integrations will last.
At SuiteVise, we design and maintain NetSuite integrations every day. Here, in simple terms, is what sets these three APIs apart and how to choose the right one.
The three NetSuite APIs in a nutshell
SOAP (SuiteTalk SOAP Web Services): NetSuite’s original API. It relies on XML exchanges and service contracts (WSDL) versioned with each release. Robust and widely used by off-the-shelf connectors, it is now reaching end of life.
REST (SuiteTalk REST Web Services): NetSuite’s modern API. It exchanges data in JSON, can read, create, update and delete most records, and gives access to SuiteQL, a SQL-like query language. It is the API NetSuite recommends for any new integration.
RESTlets: not a “ready-to-use” API, but entry points you develop yourself in SuiteScript, inside NetSuite. A RESTlet can hold the full logic of a business process: validating data, creating several records, applying specific rules, all in a single call.
SOAP: a scheduled end
This is the most important point in this article. NetSuite has announced the gradual removal of its SOAP web services, in favor of the REST API and OAuth 2.0 authentication.
The main milestones of the announced timeline:
| NetSuite release | What changes |
|---|---|
| 2025.2 | Last planned SOAP endpoint |
| 2026.1 | No new SOAP endpoint with each release; NetSuite asks that every new integration be built on REST, with OAuth 2.0 |
| 2027.1 | No more new integrations built on SOAP, or with token-based authentication |
| 2027.2 | Only the 2025.2 SOAP endpoint remains supported |
| 2028.2 | Full removal of SOAP: SOAP integrations stop working |
Each SOAP endpoint is supported for three years after its release, and the oldest one is disabled with each new release. An integration still pointing to an old endpoint can therefore stop working well before 2028.
What this means in practice:
- No new integration should be built on SOAP.
- Existing SOAP integrations should move at least to the 2025.2 endpoint, then be migrated to REST or RESTlets.
- Off-the-shelf connectors (integration platforms, third-party applications) need to be checked: some still use SOAP behind the scenes.
REST, SOAP and RESTlets: the comparison
| Criterion | SOAP | REST | RESTlets |
|---|---|---|---|
| Format | XML | JSON | JSON, text or XML, depending on the development |
| Nature | Standard NetSuite API | Standard NetSuite API | Custom-built entry point |
| Future | Full removal in 2028.2 | API recommended by NetSuite | Long-lasting, based on SuiteScript |
| Authentication | Token-based authentication (TBA) | OAuth 2.0 (tokens accepted for existing integrations) | OAuth 2.0 (tokens accepted for existing integrations) |
| SuiteQL queries | No | Yes | Possible in the code |
| Business logic | In the calling system | In the calling system | In NetSuite, in the RESTlet |
| Calls per process | Often several | Several, sometimes fewer than with SOAP | Often just one |
| Development | No code in NetSuite | No code in NetSuite | SuiteScript code to write and maintain |
| Use of NetSuite resources | Concurrency limits | Concurrency limits | Concurrency limits and SuiteScript governance units |
Key takeaway: concurrency limits are shared by all three APIs. They depend on your account’s service tier and on any SuiteCloud Plus licenses. More integrations means sharing the same number of simultaneous calls.
Which API for which need?
Choose REST when…
- You need standard operations on records: create a customer, update an order, read an invoice.
- You want to extract data flexibly with SuiteQL, for example to feed a data warehouse or a reporting tool.
- You use an integration platform or a connector that speaks REST.
- You want to limit the code to maintain in NetSuite.
It is the default choice for a new integration.
Choose a RESTlet when…
- The business process requires several linked operations: create an order and its lines, reserve stock and return a status, in a single call.
- You need specific validation rules in NetSuite before saving the data.
- You want to reduce the number of calls to preserve your concurrency limits.
- The REST API does not cover the use case or certain specific records.
A RESTlet is powerful, but it is code: it must be documented, tested and maintained with every NetSuite update.
Keep SOAP only…
For an existing integration, while you migrate it, moving at least to the 2025.2 endpoint.
And often, both
In practice, many architectures combine REST for standard operations and RESTlets for complex processes. It is often the most balanced approach: little code, but custom work where it really adds value.
Points to watch, whatever the API
- Authentication: favor OAuth 2.0, the method NetSuite recommends and makes mandatory for every new integration from release 2027.1. Token-based authentication remains possible for existing integrations. In every case, set up a dedicated user and role for each integration. Never use a real user’s credentials.
- Permissions: the integration role should have only the rights it needs. This is a matter of security, but also of traceability.
- Concurrency: monitor the number of simultaneous calls. Beyond the limit, calls are rejected. Grouping processing and scheduling heavy flows during off-peak hours prevents many incidents.
- Error handling: an integration must detect, log and replay failed calls. Otherwise, orders or invoices disappear without anyone noticing.
- Existing scripts: API calls trigger server-side scripts and workflows, but not client-side scripts. A control rule placed only in a client script will not apply to data received through the API.
- External IDs: use external IDs to link records across systems and avoid duplicates.
- Documentation: every flow should be documented (direction, frequency, data, owner) so it can be maintained and evolve.
Frequently asked questions
What is the difference between REST and a RESTlet in NetSuite?
The REST API is a standard API provided by NetSuite to work with records and run SuiteQL queries. A RESTlet is an entry point you develop in SuiteScript to run custom business logic in a single call.
Is NetSuite’s SOAP API going away?
Yes. According to the timeline announced by NetSuite, the 2025.2 endpoint is the last one planned, new SOAP integrations are no longer possible from 2027.1, and SOAP is fully removed with release 2028.2.
Should SOAP integrations be migrated now?
At a minimum, they should move to the 2025.2 endpoint, and their migration to REST or RESTlets should be planned. An integration on an old endpoint can stop working before 2028.
What is SuiteQL?
A SQL-like query language, available in particular through the REST API. It extracts data more flexibly than saved searches.
Do RESTlets use NetSuite resources?
Yes. They share concurrency limits with the other APIs and consume SuiteScript governance units. But a well-designed RESTlet often replaces several calls.
Which API does NetSuite’s MCP connector use?
The standard tools of the AI Connector Service rely on NetSuite’s REST web services.
In short: REST by default, RESTlets for custom work, SOAP to migrate
For any new integration, the REST API is the natural choice: standard, modern and recommended by NetSuite. RESTlets complement it for complex business processes, provided you accept the code they involve. As for SOAP, its removal is scheduled: it is time to take stock of your existing integrations and plan their migration.
Not sure which integrations still use SOAP, or preparing a new flow with NetSuite? SuiteVise can help: an inventory of your integrations, the choice of architecture, migration to REST and RESTlet development. Let’s take 30 minutes to talk it through.