NetSuite Integration Overview

The NetSuite integration gives your Velaro AI agent direct access to 47 AI tools spanning customer intelligence, order management, invoicing, case management, returns/RMA, inventory, sales pipeline (leads and opportunities), quoting, vendors and purchasing, employees, and subsidiaries. The AI agent can look up records, take actions, and surface real-time NetSuite data — all without a human agent.

This guide covers: what each tool does, step-by-step machine-to-machine setup, tips for writing your AI agent instructions, agent sidebar field mapping, prompt tips, escalation rules, and troubleshooting.

Setup — Quick Start

Velaro connects to NetSuite with machine-to-machine (M2M) access. Velaro generates a certificate, a NetSuite Administrator adds it once in your NetSuite account, and Velaro stays connected with no weekly re-login.

Once NetSuite is connected, all 47 tools are available to your AI agent. Add a NetSuite AI node to any workflow and the AI agent calls the right tools based on what the visitor asks. Use the Launch Starter Wizard on the NetSuite integration page to create a pre-built workflow in seconds.

Setup — Machine-to-Machine Guide

A NetSuite Administrator does this once for each NetSuite account. Sandbox and production are separate connections, so set up each one. Have your NetSuite account ID ready: it is shown under Setup → Company → Company Information (for example XXXXXXX for production or XXXXXXX_SB1 for a sandbox).

Step 1 — Enable the Features

In NetSuite go to Setup → Company → Enable Features → SuiteCloud. Check OAuth 2.0 and REST Web Services, then save. Next open the Analytics subtab, check SuiteAnalytics Workbook, and save.

Step 2 — Create a Role

1. Go to Setup → Users/Roles → Manage Roles → New and name it Velaro Integration.

2. Check Web Services Only Role.

3. On the Permissions tab, add the permissions your AI agent needs:

• Setup: Log in using OAuth 2.0 Access Tokens (Full) and REST Web Services (Full)
• Lists: Customers, Contacts, and Cases (Full, if you use support cases)
• Transactions: Sales Orders and Invoices (View or higher), if you use order lookups, invoices, or returns
• Reports: SuiteAnalytics Workbook (Edit)

4. Save. Velaro can only read the record types this role is allowed to view, so add any others your AI agent should use.

Step 3 — Create the User

1. Go to Lists → Employees → Employees → New, enter the name Velaro Integration and an email address.

2. On the Access subtab, check Give Access and add the role from Step 2.

3. If NetSuite asks for a password, assign a long random one. Nobody signs in with this user.

4. Save.

Step 4 — Create the Integration Record

1. Go to Setup → Integration → Manage Integrations → New and name it Velaro M2M Integration.

2. Under OAuth 2.0, uncheck Authorization Code Grant and check Client Credentials (Machine To Machine) Grant.

3. Under Scope, check REST Web Services and RESTlets.

4. Save, then copy the Client ID right away. NetSuite shows it only once. You do not need the Client Secret.

Step 5 — Add the Velaro Certificate in NetSuite

1. In Velaro, go to Integrations → NetSuite, choose Machine-to-machine, and click Generate Velaro certificate. Download the .pem file.

2. In NetSuite go to Setup → Integration → Manage Authentication → OAuth 2.0 Client Credentials (M2M) Setup and click Create New.

3. Choose the user from Step 3, the role from Step 2, and the integration record from Step 4. Upload the .pem file.

4. Save, then copy the Certificate ID that NetSuite shows.

Generating a new certificate in Velaro replaces the previous one, so upload the newest file if you generate it again.

Step 6 — Enter the IDs and Verify

Back in Velaro, enter your account ID, Client ID, and Certificate ID, then click Save and verify. Velaro checks that it can get a token, reach NetSuite, and read a customer. If a check fails, the message tells you what to fix. When all checks pass, click Finish.

Step 7 — Optional: Configure a RESTlet

If you have custom SuiteScript for business-specific logic (warranty checks, contract pricing, multi-step workflows), add the RESTlet URL in the same settings panel. See the RESTlet section below.

Certificate Renewal

NetSuite allows up to 5 active certificates per integration record. Plan a replacement before your certificate expires, and use Rotate certificate on Integrations → NetSuite. The status card shows when your certificate expires.

All 47 AI Skills

Customer Intelligence

netsuite_search_customer — Search for a customer by name, email, or phone number. Use this first in any conversation where the customer's identity isn't yet confirmed. Returns a list of matching records with account IDs so the AI agent can pick the right one.

netsuite_get_customer — Retrieve the full customer profile: billing address, shipping address, account status, assigned sales rep, customer category, and account number. Call after netsuite_search_customer to get the full record.

netsuite_get_customer_contacts — List all contacts associated with a customer account. Useful for B2B accounts where multiple people may be reaching out on behalf of the same company.

netsuite_get_customer_balance — Get the customer's current balance, credit limit, available credit, and overdue amount. Use when a customer asks "do I owe anything?" or "why is my order on hold?"

netsuite_update_customer — Update a customer record fields such as phone, email, billing address, or status. Always confirm the change with the customer before calling this tool.

Order Management

netsuite_search_orders — Search for sales orders by customer name, email, or order number. Returns a list with order numbers, dates, and statuses. Use when the customer doesn't have their exact order number.

netsuite_get_order — Retrieve full order details: line items, quantities, unit prices, totals, shipping method, billing/shipping address, and current status. Use when the customer provides an order number.

netsuite_get_order_history — List all historical orders for a customer account. Useful for "show me all my orders from last year" or recurring order reviews.

netsuite_cancel_order — Cancel a sales order in NetSuite. Always confirm with the customer before calling. Only applicable to orders in Pending Fulfillment or similar pre-shipped status.

netsuite_add_order_note — Add an internal memo to a sales order in NetSuite. Use after every customer interaction that modifies or discusses an order so your team has full context.

netsuite_get_order_fulfillment_status — Check real-time fulfillment/shipment progress on an order — has it been picked, packed, shipped. Use when a customer asks "has my order shipped yet?" before it reaches full "shipped" status.

Invoicing & Payments

netsuite_get_invoice — Retrieve a specific invoice with line items, due date, amount due, and payment status. Use when a customer asks about a specific invoice number.

netsuite_get_open_invoices — List all outstanding unpaid invoices for a customer with amounts and due dates. Use when a customer asks "what do I owe?" or is disputing a statement.

netsuite_get_payment_history — View all payment records applied to a customer's account: amounts, dates, invoice numbers paid, and payment methods. Use for reconciliation questions.

netsuite_get_credit_memos — Retrieve credit memos issued to a customer: amounts, dates, and remaining balance. Use when a customer asks about a credit or expects a refund they haven't seen.

netsuite_get_cash_sale / netsuite_search_cash_sales — Retrieve or search cash sale transactions (point-of-sale style orders with no separate invoice/AR step). Use for retail or storefront-style NetSuite setups where orders are recorded as cash sales rather than invoiced sales orders.

netsuite_get_open_vendor_bills — List outstanding accounts-payable bills owed to a vendor. Use in internal/vendor-facing AI agents, not typically exposed to end customers.

Case Management

netsuite_create_case — Create a new support case in NetSuite directly from the chat conversation. Captures the customer's issue, sets the priority, and assigns it to the right queue. Always confirm the case details before creating.

netsuite_get_cases — Retrieve open and recent cases for a customer account with status, priority, and last activity date. Use when a customer asks "what's the status of my ticket?"

netsuite_update_case — Update an existing case: change status, reassign, adjust priority, or mark as resolved. Use after resolution or when the customer provides new information.

netsuite_close_case — Close and resolve a support case with a resolution note in one action. Adds the resolution summary as a case note, then sets status to Closed. Use at the end of a conversation once the customer confirms their issue is resolved.

netsuite_add_case_note — Add a note to an existing support case. Use to log the conversation summary so your team has full context when reviewing the case.

Returns & RMA

netsuite_get_rma — Retrieve RMA (Return Merchandise Authorization) status and details including items approved for return, return instructions, and expected credit. Use when a customer asks "where's my return?"

netsuite_create_rma — Create a new RMA from the chat conversation. Captures the reason for return, line items, and quantities. Always confirm with the customer before submitting. Only create an RMA if the order is within the return window.

Inventory & Products

netsuite_search_items — Search the NetSuite item catalog by name, SKU, or category. Returns item name, description, base price, and availability indicator.

netsuite_check_stock — Check real-time inventory levels for an item. Returns quantity on hand, quantity committed, and quantity available. Adds urgency messaging when stock is low.

netsuite_get_item_pricing — Get pricing for an item, including customer-specific price levels (wholesale, distributor, VIP). Accounts for the customer's assigned price level in NetSuite.

netsuite_restlet — Call a custom NetSuite RESTlet script. Use for any business-specific operation not covered by the standard tool set — your team can expose any NetSuite logic via a RESTlet and the AI agent can call it.

Opportunities & Quoting (Sales)

netsuite_search_opportunities — Search open opportunities/deals by customer name, stage, or minimum probability. Use in sales AI agents to surface existing pipeline before creating new records. Parameters: customer_name, stage, probability_min.

netsuite_get_opportunity — Retrieve full opportunity record by ID: amount, expected close date, stage, sales rep, and linked customer. Call after netsuite_search_opportunities to get the full record.

netsuite_update_opportunity — Update an existing opportunity: change stage (Prospect → Closed Won / Closed Lost), adjust the expected close date, update the deal amount, or add notes. Requires opportunity_id. Common use: mark deals won or lost at the end of a sales conversation.

netsuite_create_quote — Create a NetSuite estimate (quote) record directly from a chat conversation. AI Agent collects items, quantities, and desired pricing, then creates the record. Parameters: customer_id, items (array of item_id + quantity + price), memo, close_date.

netsuite_get_estimate — Retrieve a specific quote/estimate by its NetSuite ID. Returns line items, totals, expiry date, and status. Use when a customer references an existing quote and wants to review or confirm it.

Lead Pipeline

netsuite_create_lead — Record a new prospect in NetSuite from a chat conversation. Captures company name, email, phone, and lead source. The Contact Creation setting on your NetSuite configuration page controls whether the record becomes a Lead (default) or goes directly into your Customers list — and each workflow can override that choice in its NetSuite AI node. Always check with netsuite_search_leads before creating to avoid duplicates.

netsuite_search_leads — Search the NetSuite leads pipeline by email, company name, or lead source. Use before creating a new lead to check for duplicates. Also useful in sales AI agents where a rep wants to review the prospect pipeline.

netsuite_update_lead — Update an existing lead record: contact info, lead source, or status. Use after netsuite_search_leads finds a matching lead instead of creating a duplicate.

Vendors & Purchasing

netsuite_get_vendor / netsuite_search_vendor — Retrieve or search vendor records by name or ID. Use in AP/procurement AI agents handling vendor inquiries rather than customer-facing chat.

netsuite_get_purchase_order / netsuite_search_purchase_orders — Retrieve or search purchase orders. Use for procurement teams tracking outbound POs to suppliers.

netsuite_get_purchase_order_receipt_status — Check whether inventory from a purchase order has been received. Use when a vendor or internal team asks "did that shipment arrive?"

Employees

netsuite_get_employee / netsuite_search_employees — Retrieve or search employee records. Use only in internal, employee-facing AI agents — never expose employee lookups to external/customer conversations.

Subsidiaries & Locations (OneWorld only)

netsuite_get_subsidiaries — List active subsidiaries or business units in the customer's NetSuite account. Use when a caller asks which location or region handles their account, or when routing a case to the right entity. This is the only skill gated to NetSuite OneWorld (multi-subsidiary) accounts — every other skill in this guide works on any standard NetSuite edition.

Credits (Detailed)

netsuite_get_credit_memo — Retrieve a single specific credit memo by ID, including line-item breakdown, remaining balance, and expiry date. Use when the customer provides a specific credit memo number and wants the full breakdown.

HTTP POST vs Skills — When to Use Each

This is the most common architecture question for NetSuite integrations.

Situation	Use	Reason
Customer asks about order status, balance, cases	Skills	AI Agent reads data real-time and responds naturally in the conversation
AI Agent needs to CREATE a record (case, RMA, quote)	Skills	Record created immediately; AI agent confirms to the customer
You have custom SuiteScript already deployed	RESTlet skill	Reuses your existing code
Multi-step workflows (create + notify + assign)	RESTlet skill	SuiteScript handles the sequence atomically in one call
You need data pushed to NetSuite after a chat ends	Zapier/Make webhook	Post-chat background automation
You want to trigger a Velaro action from NetSuite	NetSuite outbound webhook → Velaro API	Outside the scope of chat skills

Simple rule: If the customer is waiting for an answer during the chat → use Skills. If it can happen in the background after the chat ends → use Zapier or a webhook.

RESTlet Integration — Advanced Business Logic

RESTlets are custom server-side SuiteScript functions that you deploy in NetSuite. The netsuite_restlet skill can call them, enabling any business logic your team has built — without changes to Velaro.

Common RESTlet use cases:

• Warranty status check (query custom warranty records)
• Contract pricing lookup (apply customer-specific price matrices)
• Approval workflows (create + route + notify in one atomic call)
• Custom return eligibility rules
• Entitlement verification ("is this customer on our support plan?")

How to set up a RESTlet:

1. In NetSuite: Setup → SuiteCloud → SuiteScript → Script Records → New

2. Script type: RESTlet

3. Write your GET/POST handler in SuiteScript 2.x

4. Deploy the script, note the Script ID and Deploy ID

5. In Velaro: Admin → Integrations → NetSuite → RESTlet URL

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

In your AI agent system prompt, document the RESTlet's operation types:

RESTlet operations available:
- type: "warranty_check" — params: serial_number
- type: "contract_pricing" — params: customer_id, item_id, quantity
- type: "return_eligibility" — params: order_id, item_id

The AI agent will call the right operation type based on what the customer asks.

Writing Instructions for Your AI Agent

Your AI agent works best with short, plain instructions. You do not need a long script. Cover these points and let the connected NetSuite skills do the rest:

• Role — say who the AI agent is and what it helps with, such as order status, billing questions, returns, or product availability.
• What it can look up — name the areas it should use, such as orders, invoices, cases, or inventory.
• When to hand off — decide when a person should take over, such as a dispute, a request for a manager, or two attempts without a resolution.
• What it should never do — for example, sharing payment details or promising refunds, discounts, or price changes.
• Tone and channel — keep replies short and friendly, and shorter still for text messages or phone calls.

Start simple, test it in the simulator, and add detail only where you see a gap.

Field Mapping for Agent Sidebar

Configure which NetSuite fields appear in the agent sidebar during live conversations so agents have full customer context without switching systems.

Recommended sidebar fields:

Field	NetSuite Source	Why It's Useful
Account Name	customer.companyName	Confirm who you're talking to
Account Number	customer.accountNumber	For quick NetSuite lookup
Account Status	customer.status	Know if account is on hold
Current Balance	customer.balance	Catch billing issues early
Credit Limit	customer.creditLimit	Avoid fulfillment holds
Assigned Rep	customer.salesRep	Route to the right person
Account Type	customer.category	Tailor response to B2B/B2C
Open Cases	via netsuite_get_cases	Know if there's an active issue

To configure: Go to Integrations → NetSuite → Sidebar Fields tab. Select fields from the discovered list and click Save. Changes appear in the agent sidebar immediately.

Prompt Tips & Best Practices

Version History Is Built In

Every time you edit a workflow or AI Config system prompt, Velaro automatically saves a new version. You can see all versions and roll back to any previous version at any time.

To view version history: Open the workflow or AI Config → click the version number or history icon in the top bar → select any version to preview or restore.

Build Prompts Additively

When you want to add a new capability to your AI agent, start with the existing prompt and ADD to it. Do not rewrite the whole prompt.

Example: Your Order Status AI Agent is working well, and you want it to also handle invoice questions.

• Open the AI Config
• Find the TOOLS AVAILABLE line and add: netsuite_get_invoice, netsuite_get_open_invoices
• Add a new WORKFLOW section at the bottom for invoice handling
• Save → new version is created automatically → test it → roll back if anything breaks

Use the Copilot to Refine Prompts

The Velaro copilot (the ? bubble in the bottom right) can help you improve your prompts. Just say:

• "I need the AI agent to also handle invoice disputes"
• "The AI agent keeps escalating too early for order questions — how do I fix that?"
• "Write a prompt snippet for handling out-of-stock situations"

The copilot knows your current prompt and can suggest targeted additions rather than full rewrites.

Test Before Going Live

Use the Live Test tab (Bots → select AI agent → Live Test) to chat with your AI agent and watch which tools it calls in real time. This shows you exactly what NetSuite data it's pulling and whether the routing logic is working correctly.

Escalation & Transfer Rules

Set up escalation so the AI agent hands off smoothly when it can't resolve an issue.

Recommended escalation triggers to add to your system prompt:

• Customer requests a human agent explicitly
• Customer mentions legal action or a formal complaint
• The AI agent cannot find a customer record after 2 attempts
• The issue involves a disputed amount over your defined threshold
• Order cancellation request for an already-shipped order
• RMA request for an item outside the return window

How to configure escalation in the workflow:

1. Add a Transfer to Agent node after the NetSuite AI node in your workflow

2. Connect the AI node's "Escalate" exit to the Transfer node

3. In the Transfer node, set the target team or agent skill (e.g., "Billing Team", "Returns Team")

4. Optionally add a pre-transfer message: "Let me connect you with a specialist."

Tip: In your system prompt, tell the AI agent exactly what phrase triggers the escalation exit, e.g., "When you decide to escalate, say: 'I'm connecting you with a specialist now.' and then call the escalation tool."

Click-to-Dial (CTI)

NetSuite has its own built-in Telephony Integration feature (Setup → Company → Enable Features → SuiteCloud → "Telephony Integration"). When an admin pastes a CTI URL into their NetSuite preferences, clicking any hyperlinked phone number on a NetSuite record dials out through your connected Velaro voice provider (Twilio today; other providers are recognized but not yet wired for outbound dialing).

This is different from every other Velaro telephony integration — see the Telephony & CTI Overview guide for why. NetSuite navigates the agent's browser to a Velaro URL; nothing calls Velaro's servers directly.

Setup (self-serve, no support ticket needed):

1. Go to Integrations → NetSuite → Click-to-Dial tab

2. Click Generate URL — this creates a per-site secret URL and shows it ready to copy

3. In NetSuite: Home → Set Preferences → Telephony → CTI URL — paste the generated URL

4. Confirm a voice provider (e.g. Twilio) is already connected on Integrations → Voice Channel — click-to-dial has nothing to bridge the call to otherwise

Rotating the URL: clicking Regenerate URL immediately invalidates the old URL — update NetSuite's Telephony preference with the new value right away, or click-to-dial will start returning errors.

Screen-pop URL: the same tab also shows an optional screen-pop URL. This is NOT confirmed by NetSuite's own documentation to fire automatically on inbound calls — it's provided for customers whose own NetSuite workflow/customization navigates there. Don't promise automatic inbound screen-pop from this URL alone; NetSuite's documented behavior only covers the outbound click-to-dial case above.

Ask the AI agent: "Is click-to-dial set up for NetSuite?" or "What's our NetSuite CTI URL?" — the netsuite_cti_setup_info skill reports current status and setup steps without exposing the raw secret token in chat.

Troubleshooting

AI Agent says it cannot access NetSuite data

→ Check that the NetSuite integration is connected and the connection is healthy. Go to Integrations → NetSuite and click Test connection. The status card shows the last successful sign-in and when your certificate expires. If it has expired or the role is missing permissions, rotate the certificate or update the role in NetSuite (Step 2).

AI Agent cannot find a customer who definitely exists

→ Try searching by email vs. company name — some accounts may have the contact email stored under a child contact record rather than the main customer. Use netsuite_get_customer_contacts after finding the company.

AI Agent creates duplicate cases

→ Add a check to your prompt: "Before creating a case, call netsuite_get_cases to verify there is not already an open case for the same issue." If one exists, update it with netsuite_update_case instead.

netsuite_restlet returns an error

→ Verify your RESTlet is deployed and set to External access in NetSuite. Confirm the script ID and deploy ID in the integration config. The RESTlet must return a JSON response.

AI Agent ignores the return window rule

→ Make the return policy conditions explicit and numerical in your prompt ("within 30 days of ship date"). Avoid relative language like "recently" — the AI agent cannot infer what "recently" means.

Agent sidebar shows blank fields

→ Check that the field names in Sidebar Fields match the exact API field names from NetSuite. Use the Discover Properties button to get the correct field names rather than typing them manually.

AI Config not using the right NetSuite tools

→ Verify the tool names in your system prompt exactly match the available tools listed under Bots → AI Training → Skills. Mismatched names cause the AI to skip the tool entirely.