NetSuite RESTlet Capabilities

TL;DR

• Bottom line: RESTlets are custom-built REST endpoints in NetSuite via SuiteScript 2.x -- they give you 5,000 governance units per execution and full SuiteScript API access, making them the most flexible integration surface for complex logic. [src1]
• Key limit: 5,000 governance units per execution (5x Suitelets), 10 MB input/output payload, 5 concurrent calls per user (default). [src1, src4]
• Watch out for: HTTP status codes are not controllable -- normal returns always send 200 OK, thrown errors always send 400 Bad Request. Build error semantics into the response body, not HTTP codes. [src3]
• Best for: Custom integrations requiring complex business logic, multi-record operations in one call, or non-standard record types that the standard REST API doesn't expose. [src6]
• Authentication: Token-Based Authentication (TBA / OAuth 1.0) or OAuth 2.0 for external calls; automatic for internal SuiteScript calls. [src2]

System Profile

NetSuite RESTlets are server-side SuiteScript scripts that expose custom RESTful endpoints within Oracle NetSuite. They support GET, POST, PUT, and DELETE HTTP methods, and can return JSON or plain text responses. RESTlets operate within SuiteScript 2.x and have complete access to all NetSuite APIs including N/record, N/search, N/query, N/http, and N/file modules. This card covers all NetSuite editions that include SuiteCloud licensing (required for custom scripts). [src2]

RESTlets are distinct from NetSuite's built-in REST Web Services (record-based CRUD via SuiteTalk REST) and from Suitelets (which can serve HTML pages to browsers). RESTlets are purpose-built for machine-to-machine integration where custom server-side logic is required. [src6]

API Surfaces & Capabilities

RESTlets are one of several integration surfaces available in NetSuite. This table compares all major options so agents can route users to the correct card. [src6]

Rate Limits & Quotas

Per-Request Limits

Account-Level Concurrency Limits

Formula: Total Concurrency = Base Tier Limit + (SuiteCloud Plus Licenses x 10). This pool is shared across ALL web services + RESTlets since 2017.2. [src4, src7]

Governance Unit Costs (Key Operations)

NetSuite tracks governance usage per SuiteScript API call within each RESTlet execution. Exceeding 5,000 units terminates the script immediately. [src1]

Check remaining governance at runtime with script.getRemainingUsage(). [src1]

Authentication

RESTlets always require authentication for external calls. Internal calls (from other SuiteScript) are authenticated automatically. [src2]

Authentication Gotchas

• TBA uses OAuth 1.0 signing (not OAuth 2.0) -- the consumer key, consumer secret, token ID, and token secret must all be present in the Authorization header. Signature base string must include the account ID. [src2]
• OAuth 2.0 for RESTlets requires a separate setup from OAuth 2.0 for REST Web Services -- the integration record must have RESTlet scope enabled with a specific callback URL. [src2]
• NLAuth header format uses email + password + account ID + role ID -- simplest to implement but provides no security for production. NetSuite may block NLAuth in future releases. [src7]
• Session timeout for token-based auth follows the company-wide session timeout setting -- not configurable per RESTlet. [src2]

Constraints

• 5,000 governance units is a hard cap -- no yield, no recovery points, no "continue later" in SuiteScript 2.x. If your operation exceeds 5,000 units, split across multiple RESTlet calls or use Scheduled Script/Map-Reduce. [src1]
• HTTP status codes are NOT controllable -- normal return = 200 OK; thrown error = 400 Bad Request. You cannot return 201, 204, 404, or 422 from a RESTlet. [src3]
• Account-level concurrency is shared between RESTlets AND SOAP web services AND REST Web Services -- high SOAP volume reduces available RESTlet slots. [src4]
• RESTlets cannot render HTML pages or serve files directly -- use Suitelets for browser-facing endpoints. [src6]
• External HTTP callouts from within a RESTlet (N/http module) cost 10 governance units each and are limited to synchronous execution. [src1]
• RESTlets do not support WebSocket or long-polling -- strictly request-response. [src2]
• RESTlet deployment must be set to "Released" status before external callers can access the endpoint. [src5]
• SuiteCloud license required -- not available on all NetSuite tier levels. [src2]

Integration Pattern Decision Tree

START -- User needs to integrate with NetSuite via custom REST endpoints
|-- What's the integration pattern?
|   |-- Real-time (individual records, <1s latency)
|   |   |-- Needs custom business logic?
|   |   |   |-- YES --> RESTlet (this card)
|   |   |   |-- NO --> REST Web Services (standard CRUD)
|   |   |-- Data volume per call?
|   |   |   |-- < 50 records --> Single RESTlet call
|   |   |   |-- 50-500 records --> RESTlet with batched operations (watch governance)
|   |   |   |-- > 500 records --> Split into multiple RESTlet calls or use Map/Reduce
|   |   |-- Need to combine multiple operations atomically?
|   |       |-- YES --> RESTlet (can wrap in single transaction)
|   |       |-- NO --> REST Web Services (simpler, no code to maintain)
|   |-- Batch/Bulk (scheduled, high volume)
|   |   |-- < 500 records per batch?
|   |   |   |-- YES --> RESTlet called on schedule (external scheduler)
|   |   |   |-- NO --> Scheduled Script or Map/Reduce (10,000 units)
|   |   |-- Need external trigger?
|   |       |-- YES --> RESTlet (external system calls on schedule)
|   |       |-- NO --> Scheduled Script (internal NetSuite scheduler)
|   |-- Event-driven
|   |   |-- External system needs to push to NetSuite?
|   |   |   |-- YES --> RESTlet as webhook receiver
|   |   |   |-- NO --> User Event Script (internal triggers)
|   |   |-- NetSuite needs to push to external system?
|   |       |-- YES --> User Event Script + N/http callout
|   |       |-- NO --> N/A
|   |-- File-based (CSV/XML)
|       |-- Use CSV Import or SuiteTalk SOAP (not RESTlet)
|-- Which direction?
|   |-- Inbound (writing to NetSuite) --> RESTlet POST/PUT entry points
|   |-- Outbound (reading from NetSuite) --> RESTlet GET entry point
|   |-- Bidirectional --> Design conflict resolution strategy FIRST
|-- Error tolerance?
    |-- Zero-loss required --> Implement idempotency keys + retry logic in caller
    |-- Best-effort --> Fire-and-forget with exponential backoff retry

Quick Reference

RESTlet Entry Points (SuiteScript 2.x)

RESTlet URL Format

https://{accountId}.restlets.api.netsuite.com/app/site/hosting/restlet.nl?script={scriptId}&deploy={deployId}

The URL is provided on the Script Deployment record after deployment. [src5]

Step-by-Step Integration Guide

1. Create the RESTlet Script File

Upload a SuiteScript 2.x file to the File Cabinet. The script exports entry point functions for each HTTP method. [src2, src5]

/**
 * @NApiVersion 2.x
 * @NScriptType Restlet
 * @NModuleScope SameAccount
 */
define(['N/record', 'N/search', 'N/log'], function(record, search, log) {
    function get(requestParams) {
        log.debug('GET params', JSON.stringify(requestParams));
        var customerId = requestParams.customerId;
        if (!customerId) throw new Error('Missing required parameter: customerId');
        var rec = record.load({ type: record.Type.CUSTOMER, id: customerId });
        return {
            id: rec.id,
            companyName: rec.getValue('companyname'),
            email: rec.getValue('email'),
            phone: rec.getValue('phone')
        };
    }
    function post(requestBody) {
        log.debug('POST body', JSON.stringify(requestBody));
        var rec = record.create({ type: record.Type.CUSTOMER });
        rec.setValue('companyname', requestBody.companyName);
        rec.setValue('email', requestBody.email);
        var id = rec.save();
        return { success: true, id: id };
    }
    return { get: get, post: post };
});

Verify: Upload file to File Cabinet > SuiteScripts folder. Confirm file appears in File Cabinet listing.

2. Create Script Record and Deployment

Navigate to Customization > Scripting > Scripts > New, select the uploaded file, save the Script Record, then create a Deployment with Status = Released. [src5]

Script Record:
  Name:        "Customer RESTlet"
  Script File:  SuiteScripts/customer_restlet.js
  Script ID:    _customer_restlet

Deployment Record:
  Title:        "Customer RESTlet Deployment"
  Deployed:     Yes
  Status:       Released    <-- MUST be Released for external access
  Execute As:   <Integration Role>
  Log Level:    Debug (development) / Error (production)

Verify: After saving the deployment, the External URL field shows the endpoint URL.

3. Set Up Authentication (TBA)

Create an Integration Record and generate token credentials. [src2]

1. Setup > Integration > Manage Integrations > New
   - Name: "My Integration"
   - State: Enabled
   - Token-Based Authentication: checked
   -> Save. Copy Consumer Key + Consumer Secret (shown only once).

2. Setup > Integration > Manage Tokens > New Access Token
   - Application: "My Integration"
   - User: <integration user>
   - Role: <integration role>
   -> Save. Copy Token ID + Token Secret (shown only once).

Verify: Attempt an authenticated GET request (see cURL example below).

4. Call the RESTlet Externally

Use the OAuth 1.0 (TBA) signed request to invoke the RESTlet. [src2]

curl -X GET \
  "https://ACCOUNT_ID.restlets.api.netsuite.com/app/site/hosting/restlet.nl?script=SCRIPT_ID&deploy=DEPLOY_ID&customerId=12345" \
  -H "Authorization: OAuth realm=\"ACCOUNT_ID\",oauth_consumer_key=\"CK\",oauth_token=\"TK\",oauth_signature_method=\"HMAC-SHA256\",oauth_timestamp=\"TS\",oauth_nonce=\"NONCE\",oauth_version=\"1.0\",oauth_signature=\"SIG\"" \
  -H "Content-Type: application/json"

Verify: Response is 200 OK with JSON body containing customer data.

Code Examples

Python: Call a NetSuite RESTlet with TBA Authentication

# Input:  NetSuite account ID, consumer/token credentials, RESTlet script/deploy IDs
# Output: JSON response from RESTlet

import requests
from requests_oauthlib import OAuth1

# Pin: requests==2.31.0, requests-oauthlib==1.3.1
auth = OAuth1(
    client_key="CONSUMER_KEY",
    client_secret="CONSUMER_SECRET",
    resource_owner_key="TOKEN_ID",
    resource_owner_secret="TOKEN_SECRET",
    realm="ACCOUNT_ID",
    signature_method="HMAC-SHA256",
)

url = "https://ACCOUNT_ID.restlets.api.netsuite.com/app/site/hosting/restlet.nl?script=123&deploy=1"
response = requests.get(url + "&customerId=12345", auth=auth,
                        headers={"Content-Type": "application/json"}, timeout=30)
print(response.json())

JavaScript/Node.js: Call a NetSuite RESTlet with OAuth 1.0

// Input:  NetSuite credentials, RESTlet URL
// Output: JSON response from RESTlet
// Pin: [email protected]
const OAuth = require('oauth-1.0a');
const crypto = require('crypto');

const oauth = OAuth({
  consumer: { key: 'CONSUMER_KEY', secret: 'CONSUMER_SECRET' },
  signature_method: 'HMAC-SHA256',
  hash_function(base_string, key) {
    return crypto.createHmac('sha256', key).update(base_string).digest('base64');
  },
});
const token = { key: 'TOKEN_ID', secret: 'TOKEN_SECRET' };
const url = 'https://ACCOUNT_ID.restlets.api.netsuite.com/app/site/hosting/restlet.nl?script=123&deploy=1&customerId=12345';
const authHeader = oauth.toHeader(oauth.authorize({ url, method: 'GET' }, token));
authHeader.Authorization += ', realm="ACCOUNT_ID"';

fetch(url, { headers: { ...authHeader, 'Content-Type': 'application/json' } })
  .then(r => r.json()).then(console.log);

cURL: Quick RESTlet test (OAuth 2.0)

# Input:  OAuth 2.0 client credentials
# Output: RESTlet JSON response

# Step 1: Obtain access token
ACCESS_TOKEN=$(curl -s -X POST \
  "https://ACCOUNT_ID.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token" \
  -d "grant_type=client_credentials&client_id=CLIENT_ID&client_secret=CLIENT_SECRET" \
  | jq -r '.access_token')

# Step 2: Call RESTlet with Bearer token
curl -X GET \
  "https://ACCOUNT_ID.restlets.api.netsuite.com/app/site/hosting/restlet.nl?script=123&deploy=1&customerId=12345" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Data Mapping

RESTlet Input/Output Data Types

Data Type Gotchas

• Date values follow the logged-in user's date format preference, NOT ISO 8601 -- use N/format.parse() to ensure correct parsing. [src2]
• Internal IDs are integers but N/search sometimes returns them as strings -- always parseInt() before passing to record.load(). [src2]
• Currency amounts in NetSuite are stored with the currency's native precision -- JPY has 0 decimal places, USD has 2. Sending 99.999 for USD silently rounds to 100.00. [src7]
• Multi-select fields must send an array of internal IDs, not labels or text values. [src2]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• Governance exhaustion on large operations: Processing >200 transaction records in a single call can exhaust the 5,000 unit budget. Fix: Pre-calculate governance cost; split large batches into multiple RESTlet calls. [src1]
• Silent data truncation near 10 MB: Payloads near the limit may be truncated without error. Fix: Chunk into <5 MB batches with pagination tokens. [src1]
• Concurrency exhaustion under load: All per-user or account-level slots occupied causes queuing and timeouts. Fix: Client-side concurrency throttling; monitor via Web Services Usage Log. [src4]
• Date format mismatches: Integration user's date preference differs from external system. Fix: Always use N/format.parse() and N/format.format(); standardize user preferences. [src2]
• OAuth signature failures after credential changes: Changing integration user's password/role invalidates TBA tokens. Fix: Use dedicated integration user; monitor for 401 errors. [src7]
• Deployment status reverted after bundle update: Bundle installs can revert status to Testing. Fix: After any bundle install, verify all RESTlet deployments are Released. [src5]

Anti-Patterns

Wrong: Returning HTTP status codes for error semantics

// BAD -- you CANNOT control HTTP status codes in RESTlets
function post(requestBody) {
    var rec = record.load({ type: 'customer', id: requestBody.id });
    if (!rec) {
        return { status: 404, message: 'Customer not found' }; // Still returns HTTP 200!
    }
    return rec;
}

Correct: Use structured response body for error handling

// GOOD -- embed error semantics in a consistent response envelope
function post(requestBody) {
    try {
        var rec = record.load({ type: record.Type.CUSTOMER, id: requestBody.id });
        return { success: true, data: { id: rec.id, name: rec.getValue('companyname') } };
    } catch (e) {
        return { success: false, error: { code: e.name, message: e.message } };
    }
}

Wrong: Loading full records when you only need a few fields

// BAD -- record.load() costs 5-10 governance units; 500 records = 2,500-5,000 units
function get(requestParams) {
    var results = [];
    var ids = requestParams.ids.split(',');
    ids.forEach(function(id) {
        var rec = record.load({ type: record.Type.CUSTOMER, id: id }); // 5 units each
        results.push({ id: rec.id, name: rec.getValue('companyname') });
    });
    return results;
}

Correct: Use search.lookupFields or search.create for bulk reads

// GOOD -- search.lookupFields = 1 unit; search.create = 10 units total
function get(requestParams) {
    var ids = requestParams.ids.split(',');
    var s = search.create({
        type: search.Type.CUSTOMER,
        filters: [['internalid', 'anyof', ids]],
        columns: ['companyname', 'email']
    });
    var results = [];
    s.run().each(function(result) {
        results.push({ id: result.id, name: result.getValue('companyname') });
        return true;
    });
    return results; // 10 units total regardless of result count
}

Wrong: Not implementing idempotency for POST operations

// BAD -- duplicate POSTs create duplicate records
function post(requestBody) {
    var rec = record.create({ type: record.Type.SALES_ORDER });
    rec.setValue('entity', requestBody.customerId);
    var id = rec.save(); // Creates NEW record every time
    return { id: id };
}

Correct: Use external ID or idempotency key

// GOOD -- check for existing record using external ID first
function post(requestBody) {
    var externalId = requestBody.externalOrderId;
    var existing = search.lookupFields({
        type: 'salesorder', id: externalId, columns: ['internalid']
    });
    if (existing && existing.internalid) {
        return { success: true, id: existing.internalid, created: false };
    }
    var rec = record.create({ type: record.Type.SALES_ORDER });
    rec.setValue('externalid', externalId);
    rec.setValue('entity', requestBody.customerId);
    var id = rec.save();
    return { success: true, id: id, created: true };
}

Common Pitfalls

• Hardcoding the RESTlet URL domain: NetSuite data centers can change during migrations. Fix: Use the URL from the deployment record's External URL field. Implement 302 redirect following. [src3]
• Ignoring governance unit budget: Loading 100 transaction records (10 units each) = 1,000 units before any processing. Fix: Pre-calculate governance cost. Use search.lookupFields (1 unit) instead of record.load (5-10 units) when you only need a few fields. [src1]
• Testing only in sandbox with low data volume: Operations that use 500 units in sandbox may use 4,500 in production. Fix: Load-test with production-scale data volumes. Use script.getRemainingUsage() to monitor. [src1]
• Not handling the 302 redirect: Many HTTP clients follow redirects but lose the OAuth header. Fix: Disable auto-redirect; re-sign the request with the new URL and retry. [src3]
• Mixing SuiteScript 1.0 and 2.x patterns: Code from 1.0 examples fails silently in 2.x. Fix: Verify @NApiVersion annotation is 2.x. Use N/ module imports only. [src2]
• Forgetting Content-Type header: Omitting it causes 415 or misparse. Fix: Always include Content-Type: application/json. [src3]

Diagnostic Commands

# Check account-level API/RESTlet usage (from within NetSuite)
# Navigate to: Setup > Integration > Web Services Usage Log
# Filters: Script Type = RESTlet, Date range, Status

# Test TBA authentication from command line
curl -v -X GET \
  "https://ACCOUNT_ID.restlets.api.netsuite.com/app/site/hosting/restlet.nl?script=ID&deploy=ID" \
  -H "Authorization: OAuth realm=\"ACCOUNT_ID\",...,oauth_signature=\"SIG\"" \
  -H "Content-Type: application/json"
# Expected: 200 OK (or 401 if credentials wrong)

# Check remaining governance (add to SuiteScript)
# log.debug('Remaining', runtime.getCurrentScript().getRemainingUsage());
# View: Customization > Scripting > Script Execution Log

# Verify deployment status
# Navigate to: Customization > Scripting > Script Deployments
# Filter: Script Type = RESTlet, Status = Released

# Monitor concurrency
# Setup > Integration > Web Services Usage Log > Concurrency tab

# Check NetSuite system status
# https://status.netsuite.com

Version History & Compatibility

Account-level concurrency governance introduced in 2017.2 -- the most significant change affecting RESTlet design patterns. [src4]

Deprecation Policy

Oracle NetSuite supports SuiteScript APIs indefinitely but marks older patterns as "not recommended." SuiteScript 1.0 is still functional but receives no new features. API changes are communicated via quarterly release notes (two releases per year: .1 and .2). Breaking changes are rare and announced 2 releases in advance. [src2]

When to Use / When Not to Use

Important Caveats

• Governance unit costs may change between NetSuite releases -- always verify against the current SuiteScript 2.x API Governance page. [src1]
• Account-level concurrency varies dramatically by NetSuite tier and SuiteCloud Plus licensing -- a base account may have as few as 5 concurrent slots shared across all integration methods. [src4]
• RESTlet performance in sandbox may differ from production due to different hardware allocation and data volumes. [src7]
• OAuth 2.0 support for RESTlets was added relatively recently and may not be available on all account types. [src2]
• SuiteScript 2.1 (ES2019 with async/await) requires the @NApiVersion 2.1 annotation -- 2.0 scripts cannot use ES2019 syntax. [src2]
• The 5,000 governance unit limit is per invocation, not per HTTP request -- internal RESTlet calls from other SuiteScript each get their own 5,000 unit budget. [src1]