NetSuite Connector Guide

Overview

The NetSuite integration connects Velaro to your NetSuite account, enabling agents to look up customers, create records (leads, cases, RMAs), and search orders — all from the chat window. Workflows can also create NetSuite records automatically using the NetSuite Connector node.

Supported record types (20): Customer, Contact (via a customer's linked contacts), Lead, Opportunity, Estimate, SalesOrder, Invoice, CreditMemo, CashSale, CustomerPayment, SupportCase, ReturnAuthorization, Vendor, VendorBill, PurchaseOrder, ItemReceipt, ItemFulfillment, Item, Employee, Subsidiary. All work on any standard NetSuite account except Subsidiary, which requires OneWorld (multi-subsidiary NetSuite accounts).

Prerequisites

Before setting up the integration, you need:

1. NetSuite Account Access — Administrator or Integration Manager role, with permission to create integration records.

2. For OAuth 2.0 (recommended for new connections) — your NetSuite Account ID, plus a Client ID and Client Secret from a new NetSuite integration record with OAuth 2.0 enabled. See the setup steps below.

3. For Token-Based Auth (existing connections only) — Account ID, Consumer Key, Consumer Secret, Token, and Token Secret. NetSuite is retiring the ability to create new TBA integrations in the 2027.1 release; existing TBA connections keep working indefinitely.

Connecting with OAuth 2.0 (recommended for new connections)

NetSuite is retiring the creation of new Token-Based Authentication (OAuth 1.0a) integrations as of the 2027.1 release. Existing TBA connections keep working, but new connections should use OAuth 2.0. Velaro supports both — pick OAuth 2.0 for any new setup.

With OAuth 2.0 you don't copy tokens by hand: you approve Velaro once in NetSuite and Velaro stores and auto-refreshes the access token for you.

One-time setup in NetSuite (administrator)

1. Enable the features. Setup → Company → Enable Features → SuiteCloud tab. Check REST Web Services and OAuth 2.0. Save.

2. Create the integration record. Setup → Integration → Manage Integrations → New. Name it “Velaro”. Under Authentication check OAuth 2.0 and the REST Web Services scope. Uncheck Token-Based Authentication.

3. Set the Redirect URI to exactly the value shown in Velaro on the NetSuite page (it is https://<your Velaro admin host>/netsuite/oauth2callback). The Redirect URI must match exactly.

4. Save. NetSuite displays the Client ID (Consumer Key) and Client Secret (Consumer Secret) once — copy both. If you miss them, use Reset Credentials on the integration record to get a new pair.

5. Account ID: find it under Setup → Company → Company Information → Account ID (e.g. 1234567, or 1234567_SB1 for a sandbox).

Connect in Velaro

1. Go to Integrations → NetSuite.

2. In the Connect with OAuth 2.0 card, enter a connection name, your Account ID, Client ID, and Client Secret.

3. Click Connect with OAuth 2.0. You'll be sent to NetSuite to approve access, then returned to Velaro automatically.

4. The connection is now active and shows as OAuth 2.0. Access tokens refresh automatically — nothing else to maintain.

> Token-Based Auth (OAuth 1.0a) is still fully supported for existing connections — see the steps below.

Initial Setup (Token-Based Auth / OAuth 1.0a — existing connections)

1. Log into Velaro Admin and go to Integrations from the main menu.

2. Select NetSuite from the available integrations.

3. Click Add Account to open the setup wizard.

Configuration Steps

The setup wizard has 4 steps:

Step 1 — Authentication: Enter a display name, your NetSuite Account ID (e.g. TSTDRV123456), Consumer Key, Consumer Secret, Token, Token Secret, and RESTlet URL. Click Next to validate.

Step 2 — Connection Success: If credentials are valid, choose Finish Later to save now, or Set up Integration to proceed to field mapping.

Step 3 — Field Mapping: Select record types and map NetSuite fields to Velaro data. See the Field Mapping section below.

Step 4 — Completion: Click Go to Dashboard to return to integrations, or View Configuration to manage settings.

Field Mapping

Field mapping connects Velaro data to NetSuite record fields. For each mapped field, configure:

• NetSuite Field — the field in NetSuite (populated from your account).
• Input Type — Text, TextArea, List, Date, DateTime, or Checkbox.
• Default Value — optional fallback value.
• Create — include this field when creating new records.
• Used For Searching — use this field to search for existing records (e.g. email, customer ID).
• Show When Selected — display this field when an agent views a selected record.
• Show In Search — display this field in search result lists.

Best practices: Always map key identifiers (email, customer ID) with "Used For Searching" enabled to prevent duplicate records. Enable "Create" for all fields required by NetSuite's record validation.

NetSuite Connector Workflow Node

The NetSuite Connector node creates NetSuite records deterministically from a workflow — no AI required. Use it when record fields are known ahead of time (e.g. creating a support case after a form submission, or an RMA after an order lookup).

To add a Connector node:

1. In the workflow editor, add a NetSuite Connector action node.

2. Select the NetSuite integration (your configured account).

3. Choose the record type (e.g. SupportCase, Lead, ReturnAuthorization).

4. Map workflow variables to NetSuite field values using the visual field mapper.

5. Optionally save the created record's internal ID to a workflow variable for use in later nodes.

Transcript History

Transcript push is an automatic feature — not something the AI selects — controlled by a toggle on the NetSuite integration (PushTranscripts). When enabled, Velaro pushes the chat transcript to the matched customer record every time a conversation resolves, no matter how it was resolved (agent, workflow, or the IVR bot ending a call). The customer is matched by the email captured on the conversation first; if the conversation has no email (common for phone/IVR calls, which are identified by number rather than an email form), Velaro falls back to matching by the caller's phone number.

There are two modes:

Field mode (default) — overwrites a custom text field (custentity_transcript by default, configurable) on the Customer record with the latest transcript. Simple, zero setup beyond the toggle, but each new conversation overwrites the last one — there is no history, just the most recent transcript.

Note via RESTlet mode — posts the transcript to a RESTlet URL you deploy in NetSuite, which creates a distinct Note record per conversation. This preserves full transcript history across every conversation, the same way Dynamics 365, HubSpot, and Salesforce integrations do.

This mode exists because NetSuite's native REST API cannot create Note records — the note record type was present in the REST API in 2023.1 and was silently removed in NetSuite's 2024.1 release. The only REST-documented way to reach Note data today is reading it via SuiteQL, not creating it. A customer-deployed RESTlet is the supported workaround.

To set up Note via RESTlet mode:

1. In NetSuite, go to your existing Velaro integration record (Setup → Integration → Manage Integrations) and check the RESTlets scope box alongside the existing REST Web Services checkbox. No new connection or re-authorization is required — RESTlets use the same OAuth 2.0 bearer token as the rest of the integration.

2. Deploy the sample RESTlet script Velaro provides (Customization → Scripting → Scripts → New, Script type: RESTlet). Set External Access to true on the deployment.

3. Copy the deployment URL.

4. In Velaro, go to Integrations → NetSuite → Transcript push → Note via RESTlet and paste the URL.

Once configured, every conversation resolve creates a new Note on the customer record instead of overwriting a field.

Managing Accounts

The Accounts section shows all configured NetSuite connections for the current team.

• Edit display name: Hover over an account and click the pencil icon.
• Switch accounts: Click the account dropdown and select a different account.
• Delete account: Hover over the account in the dropdown, click the trash icon, and confirm. This removes all associated field mappings and cannot be undone.

Monitoring and Logs

Go to the Logs tab to view integration activity. Each log entry shows a timestamp, event description, and additional detail for troubleshooting. Sort by column headers, adjust items per page (20/40/60), and paginate through entries.

Common log messages: "Record created successfully", "Record updated successfully", "Authentication failed", "Field validation error", "Record not found".

Troubleshooting

OAuth 2.0 connection failed / "Token exchange failed"

• Verify the Redirect URI on your NetSuite integration record exactly matches https://<your Velaro admin host>/netsuite/oauth2callback.
• Ensure the integration record has OAuth 2.0 checked and REST Web Services scope enabled.
• Check that REST Web Services and OAuth 2.0 are enabled under Setup → Company → Enable Features → SuiteCloud.
• If the Client Secret was not copied when NetSuite first showed it, use Reset Credentials on the integration record to generate a new pair.

Authentication failed (Token-Based Auth)

• Verify Token and Token Secret are correct.
• Ensure Token-Based Authentication (TBA) is enabled in NetSuite.
• Check the integration record status in your NetSuite account.

Invalid Company ID

• Use the format TSTDRV123456 (your account ID, no spaces).

Fields not appearing in the field mapping dropdown

• Verify the RESTlet URL is correct and the script is deployed and active in NetSuite.

Field validation error

• Check that all required NetSuite fields are mapped and that field types match (text, list, date, etc.).

Duplicate records created

• Enable "Used For Searching" on email or customer ID fields to match existing records before creating new ones.

NetSuite Connector node — "No integration selected"

• Open the node editor and select a NetSuite config in Step 1.

NetSuite Connector node — record creation fails

• Check the Activity Log (Integrations → NetSuite → Logs) for the error detail. Common causes: invalid field values for select/list fields, or missing NetSuite permissions for the record type.

Stale field definitions in Connector node

• Click Refresh fields in Step 3 of the node editor to reload the field list from NetSuite (cached for 24 hours).

To verify a fix: Run the workflow in a test conversation and check Integrations → NetSuite → Logs for a success entry showing the created record ID.