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 (8 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
• Update Record: Modify existing records (supports replace and replaceSelectedFields)
• Remove Record: Delete records
• Execute SuiteQL: Run SQL-like queries with automatic offset-based pagination
• 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.

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 8 operations via switch statement (~150 lines)
• Service Layer (NetSuite.service.ts): OAuth 2.0 M2M auth, token caching, retry-wrapped HTTP requests
• Operation Modules (operations/): One file per operation, consistent INetSuiteOperationOptions interface
• Type System (types/): Auth, request, response, operation, and logger types
• Utilities (utils/): Response handler, helpers, retry handler, 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/              # Response handler, logger, retry handler, helpers
  operations/         # 8 operation modules (one per operation)
  NetSuite.node.ts    # Main node class (orchestrator)
  NetSuite.service.ts # Service layer (auth + API communication)
  NetSuite.node.options.ts # Node UI configuration
credentials/
  NetSuiteApi.credentials.ts # n8n credential definition

Common Commands

Command	Description
npm run build	Build the project (compiles TypeScript and copies icons)
npm run dev	Watch mode for development
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: DEBUG=n8n-nodes-netsuite
• Structured logger: Set N8N_LOG_LEVEL=debug for verbose NetSuiteLogger output
• Both can be enabled simultaneously

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