NetSuite RESTlet vs REST Web Services: Which Integration Approach to Use

What is a NetSuite RESTlet and how does it work?

A RESTlet is a SuiteScript 2.x script with the script type @NScriptType RESTlet. You write up to four entry point functions that correspond to HTTP methods: get, post, put, and delete. When an external system sends an HTTP request to the RESTlet's URL, NetSuite routes it to the appropriate function based on the method used.

RESTlets are deployed at Customization > Scripting > Scripts > New, selecting RESTlet as the script type. Once deployed, the URL follows this pattern:

https://[accountID].restlets.api.netsuite.com/app/site/hosting/restlet.nl?script=[scriptID]&deploy=[deployID]

Inside a RESTlet, you have full access to the SuiteScript 2.x module library. A get handler can load a record, query a saved search, call an external API, and combine results from multiple sources before returning a single JSON response. This is the primary advantage over REST Web Services: the logic lives at the endpoint layer, not in the calling system.

/**
 * @NApiVersion 2.1
 * @NScriptType RESTlet
 */
define(['N/search', 'N/error'], (search, error) => {

    function get(params) {
        if (!params.customerId) {
            throw error.create({
                name: 'MISSING_PARAMETER',
                message: 'customerId is required',
            });
        }

        const results = [];
        search.create({
            type: search.Type.TRANSACTION,
            filters: [
                ['entity', 'is', params.customerId],
                'AND',
                ['mainline', 'is', true],
                'AND',
                ['status', 'is', 'SalesOrd:B'],
            ],
            columns: ['tranid', 'trandate', 'amount', 'status'],
        }).run().each((result) => {
            results.push({
                id: result.id,
                number: result.getValue('tranid'),
                date: result.getValue('trandate'),
                amount: result.getValue('amount'),
                status: result.getText('status'),
            });
            return true;
        });

        return { customerId: params.customerId, orders: results };
    }

    return { get };
});

This RESTlet accepts a customerId query parameter, runs a search across transaction records, and returns a combined result in one HTTP call. The equivalent in REST Web Services would require a SuiteQL query and then separate record reads, or a more complex SuiteQL that joins across record types.

What is NetSuite REST Web Services and when should you use it?

REST Web Services is NetSuite's built-in REST API. No SuiteScript required. It is enabled at Setup > Company > Enable Features under the SuiteCloud tab. Once enabled, every standard NetSuite record type is accessible at a consistent endpoint:

https://[accountID].suitetalk.api.netsuite.com/services/rest/record/v1/[recordtype]/[id]

Standard operations:

• GET /[recordtype]/[id] retrieves a record
• POST /[recordtype] creates a record
• PATCH /[recordtype]/[id] updates an existing record
• DELETE /[recordtype]/[id] deletes a record
• PUT /[recordtype]/[id] creates or updates (upsert)

SuiteQL queries run at a separate endpoint:

https://[accountID].suitetalk.api.netsuite.com/services/rest/query/v1/suiteql

Batch operations, including the sequential processing added in 2026.2, are available at the batch endpoint. Sequential batch is the correct approach when one operation in a batch depends on the result of a previous one. See NetSuite REST Web Services sequential batch processing for details.

REST Web Services records every operation against the standard NetSuite audit trail. User Event scripts still fire on records created or updated through the REST API. If your account has a beforeSubmit validation that rejects certain field values, that rejection will be returned as an HTTP error response.

How does authentication differ between the two?

Both RESTlets and REST Web Services support Token-Based Authentication (TBA). The key difference is OAuth 2.0.

REST Web Services supports OAuth 2.0 Machine-to-Machine (Client Credentials grant) in addition to TBA. OAuth 2.0 is simpler for most third-party tools and iPaaS platforms to implement because it does not require computing HMAC-SHA256 signatures per request. Most modern integration platforms handle OAuth 2.0 client credentials flows natively.

RESTlets support TBA and NLAuth. NLAuth is being retired: integrations using it need to migrate to TBA before 2027.1. See NLAuth and TBA migration timeline for the deadline details. RESTlets do not support OAuth 2.0.

For a new integration where the calling system supports OAuth 2.0, REST Web Services reduces the authentication complexity for whoever builds and maintains the external side of the connection.

When should you use a RESTlet?

Use a RESTlet when the integration needs to:

• Execute business logic at the endpoint layer, not just pass data through
• Retrieve data from multiple record types and combine it into one response
• Apply transformations or validations before writing to NetSuite
• Return a custom JSON structure that does not match NetSuite's standard record format
• Support a calling system that cannot implement OAuth 2.0 or requires TBA specifically
• Call an external API as part of handling the incoming request

RESTlets are also appropriate when migrating an existing NLAuth-authenticated RESTlet to TBA is simpler than rewriting the integration around REST Web Services.

When should you use REST Web Services?

Use REST Web Services when the integration needs to:

• Perform standard CRUD operations on NetSuite records
• Run SuiteQL queries for reporting or data extraction
• Process batch operations with controlled ordering
• Integrate with third-party tools or iPaaS platforms using OAuth 2.0
• Avoid maintaining custom SuiteScript code on the NetSuite side
• Follow standard REST conventions that the wider development team already understands

REST Web Services is maintained by Oracle and updated with each NetSuite release. Standard record types gain new fields and capabilities without requiring changes to the integration code. For net-new integrations that do not require custom logic at the endpoint layer, REST Web Services is the default choice.

Decision framework: RESTlet or REST Web Services?

If the integration requirement fits one of these patterns, the choice is straightforward:

The most common case where teams choose RESTlet over REST Web Services is the combined lookup: an external system needs customer data plus open orders plus recent payments in a single API call. REST Web Services requires three separate requests and client-side assembly. A RESTlet handles the joins in SuiteScript and returns a single shaped response.

How to migrate a RESTlet from NLAuth to TBA

NLAuth-authenticated RESTlets need to migrate to Token-Based Authentication before the 2027.1 release. The migration does not require changes to the RESTlet script itself; only the authentication credentials and calling convention in the external system change.

Step 1: Create a TBA integration record. Navigate to Setup > Integration > Manage Integrations > New. Enable Token-Based Authentication and save. Note the Consumer Key and Consumer Secret.

Step 2: Create an access token. The role used must have RESTlet execution permission. Navigate to Setup > Users/Roles > Access Tokens > New and generate a token for the integration. Note the Token ID and Token Secret. These four values replace the NLAuth credentials in the calling system.

Step 3: Update the calling system's authentication header. Replace the Authorization: NLAuth ... header with an OAuth 1.0 HMAC-SHA256 signature. Most integration platforms have a TBA connector that handles signature computation automatically once the four credential values are configured.

Step 4: Validate in Sandbox before Production. The RESTlet URL does not change. Test the credential swap in Sandbox, confirm the RESTlet returns the expected response, then replicate to Production.

If you are building or maintaining NetSuite integrations and need help deciding on the right architecture, our NetSuite integrations service covers REST Web Services, RESTlet design, and OAuth 2.0 migration. For related reading, see NLAuth deprecation and TBA migration and SuiteScript best practices.

Frequently asked questions

Q: Can a RESTlet call REST Web Services internally? A: There is no practical reason to do this. A RESTlet running on NetSuite's servers already has direct access to the N/record and N/search modules, which are more efficient than making HTTP calls back to the same account. Use SuiteScript modules directly inside a RESTlet rather than making REST Web Services calls.

Q: Do User Event scripts fire when REST Web Services creates or updates a record? A: Yes. REST Web Services saves trigger the same User Event beforeSubmit and afterSubmit scripts as a UI save, a CSV import, or any other save path. If a beforeSubmit script throws an error, the REST Web Services call returns that error as an HTTP response rather than saving the record.

Q: Can REST Web Services return combined data from multiple record types in one call? A: Not directly. REST Web Services returns individual records or SuiteQL query results. If you need to combine data from multiple record types in one request, a RESTlet is the appropriate tool.

Q: What is the difference between a RESTlet and a Suitelet? A: A Suitelet is a server-side SuiteScript that generates a UI page or responds to HTTP requests, typically returning HTML. Suitelets can also return JSON, which makes them usable as REST-like endpoints, but they are primarily designed for building custom NetSuite pages. RESTlets are specifically designed as REST API endpoints and are the correct choice for machine-to-machine integrations.

Q: Are RESTlets subject to SuiteScript governance limits? A: Yes. RESTlets run as SuiteScript executions and consume governance units. A RESTlet that loads records in a loop or runs complex searches on high-volume requests can exhaust its governance budget the same way any other SuiteScript type can. REST Web Services operations are handled by NetSuite's platform layer and have separate concurrency controls.