n8n-node-netsuite

A comprehensive n8n node for NetSuite integration, providing full access to NetSuite's SuiteTalk REST API with OAuth 2.0 M2M authentication.

npm package: @brokenrubik/n8n-nodes-ns

Features

Secure Authentication

• OAuth 2.0 Machine-to-Machine (M2M) authentication
• JWT token-based authentication with PS256 algorithm
• Automatic token caching and refresh (with 1-minute safety margin)
• Certificate-based security

Operations (15 total)

• List Records: Retrieve multiple records with pagination support
• Get Record: Fetch individual records by ID (with optional sub-resource expansion)
• Get Metadata: Fetch record type metadata in JSON, OpenAPI 3.0, or JSON Schema formats
• Insert Record: Create new records (supports replace for sublist handling)
• Update Record: Modify existing records (supports replace and replaceSelectedFields)
• Upsert Record: Create-or-update a record by external ID
• Remove Record: Delete records
• Batch Insert / Update / Upsert / Remove / Get Records: Process all input items in NetSuite asynchronous batch jobs (up to 100 records per job, one API job instead of one request per item)
• Execute SuiteQL: Run SQL-like queries with automatic offset-based pagination
• Call RESTlet: Call custom RESTlet scripts deployed in NetSuite
• Raw API Request: Direct access to any NetSuite REST endpoint

Reliability

• Automatic Retry: Exponential backoff for rate limit (429) and temporary errors (502, 503, 504)
• Configurable Retries: Default 5 retries, configurable 0-10 via node options
• Backoff Strategy: Starts at 1s, doubles each attempt, max 60s, with ±10% jitter
• Network Error Recovery: Retries on ECONNRESET, ETIMEDOUT, and connection errors
• 500 errors are NOT retried (per NetSuite docs, these require contacting support)

Developer-Friendly

• Modular Architecture: Each operation is a separate module
• Structured Logging: Workflow-aware logging with NetSuiteLogger (workflow ID, node ID, execution ID)
• Comprehensive Error Handling: NetSuite-specific error parsing with o:errorDetails extraction
• TypeScript Support: Full type safety and IntelliSense
• Custom Record Support: Use any custom record type via script ID

Prerequisites

System Requirements

• Node.js >= 20.15 and npm
• n8n installed globally: npm install n8n -g

NetSuite Requirements

• NetSuite account with REST API access
• OAuth 2.0 Application configured in NetSuite
• Certificate and private key for M2M authentication
• Appropriate permissions for the operations you want to perform

Installation

From npm

npm install @brokenrubik/n8n-nodes-ns

For Development

# Clone the repository
git clone https://github.com/BrokenRubik/n8n-netsuite-node
cd n8n-netsuite-node

# Install dependencies
npm install

# Build the project
npm run build

# Link for local development
npm link

# Restart n8n to load the new node: https://docs.n8n.io/integrations/creating-nodes/test/run-node-locally/

Setup Instructions

Step 1: Create NetSuite Integration Record

1. Navigate to Integration Setup:

   • Log into your NetSuite account
   • Go to Setup > Integration > Manage Integrations > New

2. Configure Integration:

   • Enter a Name for your integration (e.g., "n8n NetSuite Integration")
   • Set State to "Enabled"
   • Under Client Credentials (M2M), check "Client Credentials (Machine To Machine) Grant"
   • Leave all other checkboxes unchecked
   • Click Save

3. Copy Integration Client ID:

   • Important: After saving, immediately copy the Integration Client ID
   • This ID will disappear if you close the tab or navigate away
   • Store it securely as you'll need it for the n8n credentials

Step 2: Generate Certificate and Private Key

1. Create Certificate Pair:

   • Open a terminal/command prompt
   • Generate a private key and certificate using OpenSSL:

   openssl req -x509 -newkey rsa:3072 -keyout n8n_key.pem -out n8n_cert.pem -days 365 -nodes
   

2. Alternative: Using NetSuite's Guide:

   • Follow NetSuite's official certificate generation guide: Creating Certificates for OAuth 2.0

Step 3: Upload Certificate to NetSuite

1. Navigate to Certificate Setup:

   • Go to Setup > Integration > Manage Authentication > OAuth 2.0 Client Credentials (M2M) Setup

2. Upload Certificate:

   • Click "New" to create a new certificate entry
   • Enter a Name for the certificate (e.g., "n8n Integration Certificate")
   • Upload the certificate file (n8n_cert.pem) - not the private key
   • Click Save

3. Copy Certificate ID:

   • After saving, copy the generated Certificate ID
   • You'll need this for the n8n credentials

Step 4: Set Up n8n Credentials

1. Open n8n:

   • Navigate to Credentials in n8n
   • Click "Add Credential"
   • Select "NetSuite API"

2. Enter Credential Information:

   • Account ID: Your NetSuite account ID (e.g., "1234567" or "1234567_SB1" for sandbox)
   • Integration Client ID: The ID copied from Step 1
   • Certificate ID (M2M): The ID copied from Step 3
   • PEM Content: Copy and paste the entire content of your private key file (n8n_key.pem)

3. PEM Content Format:

   -----BEGIN PRIVATE KEY-----
   MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC...
   ... (your private key content) ...
   -----END PRIVATE KEY-----
   

Step 5: Test the Connection

1. Create a Test Workflow:
   • Create a new workflow in n8n
   • Add a NetSuite SuiteTalk node
   • Configure it to list a simple record type (e.g., Customer)
   • Execute the workflow to verify the connection

Usage Examples

List Sales Orders

Parameter	Value
Operation	List Records
Record Type	Sales Order
Query	status IS SalesOrd:F
Return All	false
Limit	100

The Query field maps to NetSuite's q filter parameter. NetSuite uses the syntax field OPERATOR value (e.g., status IS SalesOrd:F, email IS "john@example.com").

Get a Record with Sub-Resources

Parameter	Value
Operation	Get Record
Record Type	Sales Order
ID	12345
Expand Sub-Resources	true
Restrict Returned Fields	item,entity

The ID field accepts internal IDs. Prefix with eid: to use external IDs (e.g., eid:MY_EXT_ID).

Create Customer Record

Parameter	Value
Operation	Insert Record
Record Type	Customer

The input data from the previous node is used as the request body:

{
  "companyName": "Acme Corp",
  "email": "contact@acme.com",
  "phone": "+1-555-0123"
}

Returns { success: true, id: "<new-record-id>", location: "<api-url>", recordType: "customer" }.

Execute SuiteQL Query

Parameter	Value
Operation	Execute SuiteQL
Query	SELECT id, companyname, email FROM customer WHERE datecreated >= '2024-01-01'
Return All	true

SuiteQL uses SQL-like syntax with NetSuite's database column names (lowercase). When Return All is enabled, the node automatically paginates through all results using offset-based pagination (up to 1000 rows per page).

Get Metadata Catalog

Parameter	Value
Operation	Get Metadata
Metadata Format	JSON (Record Type List)
Record Types	customer,salesOrder,invoice

Available formats:

• JSON: Lists available record types
• OpenAPI 3.0 (Swagger): Full API specification
• JSON Schema: Record structure descriptions

Leave Record Types empty to return all (can be slow for accounts with many customizations).

Raw API Request

Parameter	Value
Operation	Raw Request
HTTP Method	GET
Path	services/rest/record/v1/customer/123
Full Response	true

The Path is appended to https://<account>.suitetalk.api.netsuite.com/. You can also paste a full URL and the node will extract the path automatically. For methods other than GET/HEAD/OPTIONS, input data from the previous node is sent as the request body.

Call a RESTlet

Parameter	Value
Operation	Call RESTlet
HTTP Method	POST
Script ID	customscript_my_restlet
Deploy ID	1

The input data from the previous node is sent as the request body for POST/PUT/PATCH/DELETE methods. You can also add query parameters via the "Query Parameters" collection. For GET requests, no body is sent.

Batch Operations

Parameter	Value
Operation	Batch Insert Records
Record Type	Customer

Batch operations submit all input items together as NetSuite asynchronous batch jobs instead of one request per item. Inputs larger than 100 items are split into multiple jobs of up to 100.

By default the write batches are fire-and-forget: the node submits the jobs and outputs one item per job — { submitted: true, jobId, location, itemCount } — without polling NetSuite. Enable Wait For Results to poll until each job completes and output one result per input item (linked via pairedItem). You can check a submitted job later with Raw Request: GET services/rest/async/v1/job/{jobId}.

Per operation:

• Batch Insert Records: Each input item's JSON is one record body. With Wait For Results, outputs { success, id, location } per item.
• Batch Update Records / Batch Remove Records / Batch Get Records: The ID (Per Item) field is evaluated once per input item — use an expression like {{ $json.id }} so each item supplies its own ID. Prefix with eid: for external IDs; internal and external IDs can be mixed.
• Batch Upsert Records: The External ID (Per Item) field is evaluated once per input item (e.g. {{ $json.externalId }}) and written into the record body.
• Batch Get Records: Always waits — the results are the whole point of a get. Outputs the record body per item (supports Expand Sub-Resources and Restrict Returned Fields).

When waiting, per-item failures do not fail the node — failed items output { success: false, error } (or { error } for Batch Get), so partial success is visible per item.

Batch Options:

• Parallel Processing: Let NetSuite process items in parallel instead of sequentially. Only for independent records.
• Idempotency Key: Unique key (e.g. a UUID) to guard against duplicate submissions. On a duplicate, the node re-attaches to the previously submitted job. Jobs after the first 100 items reuse the key with -2, -3, ... suffixes.
• Poll Interval (Milliseconds): Delay between job status checks while waiting (default 5000). Increase it for large batches to reduce the request load on NetSuite.
• Timeout (Seconds): Maximum wait per batch job (default 300). Poll Interval and Timeout only apply when waiting for results.

Using Custom Records

Parameter	Value
Operation	List Records
Record Type	Custom Record
Custom Record Script ID	customrecord_my_record
Return All	true

Select Custom Record as the Record Type, then enter the script ID (usually starts with customrecord).

Architecture

Modular Design

• Main Node (NetSuite.node.ts): Orchestrates operations via switch statement (~160 lines)
• SDK (@brokenrubik/netsuite-sdk): OAuth 2.0 M2M auth, token caching, retry-wrapped HTTP requests, error parsing
• Client Factory (utils/client-factory.ts): One SDK client per execution, memoized by retry setting, so all items share the OAuth token cache
• Operation Modules (operations/): One file per operation, consistent INetSuiteOperationOptions interface
• Type System (types/): Auth, response, operation, and logger types
• Utilities (utils/): Client factory, helpers, structured logger

Error Handling

• Follows NetSuite's official error format (o:errorDetails array)
• Extracts error codes, paths, and details from responses
• Provides specific guidance per HTTP status code
• Supports graceful degradation with "Continue on Fail"

SuiteQL Pagination

SuiteQL uses offset-based pagination (not response link-based). Each page requests up to 1000 rows. The loop advances the offset by the number of items returned and stops when fewer items than requested come back. This avoids infinite loops caused by unreliable hasMore/nextUrl fields in SuiteQL POST responses.

Development

Project Structure

nodes/NetSuite/
  types/              # TypeScript type definitions
  utils/              # Client factory, logger, helpers
  operations/         # 15 operation modules (one per operation)
  NetSuite.node.ts    # Main node class (orchestrator)
  NetSuite.node.options.ts # Node UI configuration
credentials/
  NetSuiteApi.credentials.ts # n8n credential definition
test/                 # Vitest suite (operations, node routing, client factory)

Auth, HTTP transport, retries, and error parsing live in
@brokenrubik/netsuite-sdk.

Common Commands

Command	Description
npm run build	Build the project (compiles TypeScript and copies icons)
npm run dev	Watch mode for development
npm test	Run the vitest suite
npm run lint	Run ESLint
npm run lintfix	Auto-fix lint errors
npm run format	Format code with Prettier

Adding New Operations

1. Create operation file in operations/ directory
2. Export function from operations/index.ts
3. Add case to switch statement in NetSuite.node.ts
4. Add UI configuration to NetSuite.node.options.ts

Troubleshooting

Debug Logging

• Legacy debug output: NODE_DEBUG=n8n-nodes-netsuite (uses Node.js util.debuglog)
• Structured logger: NetSuiteLogger outputs structured messages via console.* at all levels (debug, info, warn, audit, error) with workflow context automatically included

Common Issues

• 401 Unauthorized: Check that your Integration Client ID, Certificate ID, and PEM content are correct. Ensure the certificate hasn't expired.
• 403 Forbidden: Verify the role assigned to the integration has permissions for the record type and operation.
• 429 Too Many Requests: The node retries automatically with exponential backoff. If persistent, reduce concurrency or increase retry count.
• 500 Internal Server Error: Not retried. Check NetSuite's audit trail or contact NetSuite support.

License

MIT