NetSuite

​

Table of Contents

1. Overview
2. Pre-Connection Checklist
3. Step-by-Step Setup Guide
4. Permissions Reference
5. Custom Fields & Records
6. Post-Setup in Core8
7. Troubleshooting
8. Additional Resources

​

Overview

This guide provides comprehensive instructions for setting up NetSuite integration with Core8. Follow each section carefully to ensure successful integration.

​

Quick Links

Resource	Description
OAuth 2.0 Docs	NetSuite OAuth 2.0 setup guide
REST Web Services	REST API configuration
SuiteQL Docs	Query language documentation
Roles Guide	Permissions configuration

​

Pre-Connection Checklist

Before starting, ensure you have administrative access to NetSuite. Use this checklist to track your progress:

​

Essential Requirements

• REST Web Services enabled
• OAuth 2.0 enabled
• SuiteAnalytics Workbook enabled
• Integration record created
• Client ID and Client Secret saved
• Account ID noted

​

Configuration Requirements

• Role with required permissions created
• At least one subsidiary exists
• Payment terms configured
• Custom fields created (if using)

​

Step-by-Step Setup Guide

​

Phase 1: Enable Core Features

​

Step 1: Enable Required Features

Navigation: Setup > Company > Enable Features

Tab	Feature	Required	Purpose
SuiteCloud	REST Web Services	✅ Yes	Enables API communication
SuiteCloud	OAuth 2.0	✅ Yes	Secure authentication
Analytics	SuiteAnalytics Workbook	✅ Yes	Required for SuiteQL queries*

*Platform Note: While the integration code doesn’t validate the SuiteAnalytics Workbook feature, NetSuite requires it for the SuiteQL API endpoint to function. You must enable this feature or SuiteQL queries will fail.

​

Step 2: Create Integration Record

Navigation: Setup > Integration > Manage Integrations > New

Field	Value	Notes
Name	Core8 Integration	Or your preferred name
State	Enabled ✅	Must be enabled
Authorization Code Grant	✅ Checked	Required for OAuth flow
REST Web Services	✅ Checked	Required for API access
Scope	rest_webservices	OAuth 2.0 scope (auto-configured)

⚠️ IMPORTANT: After saving, immediately copy:

• Consumer Key/Client ID
• Consumer Secret/Client Secret

These credentials are shown only once!

​

Step 3: Configure OAuth Redirect

In the same integration record:

Field	Value Example
Redirect URI	https://staging.core8.co/api/auth/netsuite-oauth-callback

Replace staging.core8.co with your Core8 instance URL.

​

Step 4: Note Account Information

Navigation: Setup > Company > Company Information

Information	Example	Where to Find
Account ID	1234567 or 1234567_SB2	Company Information page

​

Phase 2: Configure Role & Permissions

​

Step 5: Create/Edit Integration Role

Navigation: Setup > Users/Roles > Manage Roles Choose one approach:

• Option A: Find existing role → Click Customize
• Option B: Click New to create from scratch
• Option C: Find custom role → Click Edit

Role Settings:

Setting	Value
Name	Core8 Integration Role
Center Type	Classic Center

Then configure permissions as detailed in the Permissions Reference section below.

​

Phase 3: Required Configuration

​

Step 6: Configure Subsidiaries

Navigation: Setup > Company > Subsidiaries

Requirement	Details
Minimum	At least one active subsidiary
Status	Must be Active
Required Fields	Name, Country, Currency
Order	Create parent subsidiaries first

​

Step 7: Configure Payment Terms

Navigation: Billing > Setup > Payment Terms > New

Term Type	Use Case	Configuration
Standard	Net 30, Net 60, etc.	Set Days Till Net Due
Date Driven	Due on specific date	Set specific due date rules

​

Step 8: Multi-Currency Setup (Optional)

Navigation: Setup > Company > Enable Features > Company tab

Setting	Notes
Multiple Currencies	Check if needed
Base Currency	Set immediately (cannot change later)
Currency List	Configure at Lists > Accounting > Currencies

​

Step 9: Deal Stages Configuration

Navigation: Setup > Sales > Customer Statuses > New

Stage	Suggested Probability	Type
In Progress	10-25%	Prospect
In Discussion	25-40%	Prospect
Identified Decision Makers	40-60%	Prospect
In Negotiation	60-80%	Prospect
Proposal	75-90%	Prospect
Purchasing	90-95%	Prospect
Closed - Won	100%	Prospect
Closed - Lost	0%	Prospect

​

Permissions Reference

Navigate to the role’s Permissions tab and configure:

​

Setup Tab

Permission	Level	Purpose
REST Web Services	Full	API communication
Log in using Access Tokens	Full	OAuth authentication
Access Token Management	Full	Token lifecycle
SuiteAnalytics Workbook	Full	SuiteQL queries

​

Transactions Tab

Permission	Level	Purpose
Invoice	Full	Create/update invoices
Opportunity	Full	Manage deals
Find Transaction	Full	Search records

​

Reports Tab

Permission	Level	Purpose
SuiteAnalytics Workbook	Full	Execute queries

​

Lists Tab

Permission	Level	Purpose
Customers	Full	Create/update customers
Contacts	Full	Manage contacts
Items	Full	Reference products, create discount items
Subsidiaries	View	Required for customers
Terms	View	Payment terms
Currency	View	Multi-currency
Billing Schedules	View	Billing frequencies
Customer Categories	View	Customer tiers

​

Custom Record Tab

Permission	Level	Purpose
Custom Record - il_supp_langs	View	PDF languages
Custom List - esc_industries	View	Industry list

Note: These appear only after creating custom records.

​

Custom Fields & Records

​

Part A: Create Custom Lists

​

1. Industry List

Navigation: Customization > Lists, Records, & Fields > Lists > New

Field	Value
Name	ESC Industries
ID	esc_industries
Values	Technology, Healthcare, Manufacturing, Retail, etc.

​

2. PDF Language Record Type

Navigation: Customization > Lists, Records, & Fields > Record Types > New

Field	Value
Name	IL Supported Languages
ID	il_supp_langs
Type	Custom Record Type (not List)
Fields	Add language code and description fields

​

Part B: Create Entity Fields

Navigation: Customization > Lists, Records, & Fields > Entity Fields > New

Field	Label	ID (auto-prefixed)	Type	List/Record	Applies To
PDF Language	PDF Language	custentity_il_pdf_lang	List/Record	IL Supported Languages	Customer ✅
Industry	Industry	custentity_esc_industry	List/Record	ESC Industries	Customer ✅
Tax ID	Taxpayer ID	custentity_il_taxpayer_id	Text	-	Customer ✅

Important: NetSuite automatically adds the “custentity_” prefix to entity field IDs.

​

API Configuration

​

OAuth Details

Configuration	Value
OAuth Scope	rest_webservices
Grant Type	authorization_code
Token Refresh	refresh_token grant with Basic auth

​

Required Headers

The integration sends these headers with all API requests:

• Authorization: Bearer {accessToken}
• Accept: application/json
• Content-Type: application/json
• Prefer: transient

​

Endpoints Used

The integration uses these REST API endpoints:

Endpoint	Purpose
/services/rest/record/v1/*	CRUD operations
/services/rest/query/v1/suiteql	Data queries
/services/rest/auth/oauth2/v1/token	Token refresh
/services/rest/record/v1/metadata-catalog	Field metadata

​

Rate Limiting

Core8 automatically handles NetSuite’s rate limits:

Error Type	Strategy	Max Retries	Delays
429 Rate Limit	Exponential backoff	3	5s, 10s, 20s (max 30s)
401/403 Auth	Token refresh + retry	3	1s, 2s, 4s (max 5s)
Network Errors	Exponential backoff	3	1s, 2s, 4s

​

Concurrency Limits

Limit Type	Default	Notes
Per User (RESTlets)	5 concurrent	Standard limit
Integration Total	Varies	Based on licenses
Monitoring	Setup > Integration > Integration Governance	Optional admin tool

Platform Note: The integration handles limits reactively without client-side concurrency control. It relies on NetSuite’s server-side rate limiting. Monitoring is an optional administrative task.

​

Data Access

The configured permissions provide access to these NetSuite tables via SuiteQL: Note: Custom tables appear with prefixes like customrecord_ and customlist_ in queries.

Table	Purpose	Operations
customer	Customer records	Full CRUD
contact	Contact management	Full CRUD
item	Product catalog	Read only
transaction	Invoices & opportunities	Full CRUD
subsidiary	Organization structure	Read only
term	Payment terms	Read only
currency	Currency settings	Read only
billingSchedule	Billing schedules	Read only
entitystatus	Deal stages	Read only
customercategory	Customer tiers	Read only

​

Post-Setup in Core8

​

Step 1: Connect to NetSuite

1. Navigate to Core8 integrations
2. Select NetSuite
3. Enter Client ID and Client Secret
4. Complete OAuth authorization

​

Step 2: Configure Integration

In the Configuration tab:

Setting	Purpose
Default Subsidiary	Required for new customers
Default Payment Terms	Required for new customers
Default PDF Language	Customer communication preference
Field Mappings	Map NetSuite fields to Core8

​

Sync Options per Object Type:

• Always - Full bidirectional sync
• Read-Only - Import from NetSuite only
• Never - No sync for this object type

Note: Products in NetSuite are always read-only in Core8.

​

Troubleshooting

​

Common Connection Issues

Error	Check Location	Solution
”Invalid Grant”	Integration Record	Re-authenticate via OAuth
”429 Too Many Requests”	N/A	Wait for retry (automatic)
“401/403 Unauthorized”	Token validity	Token refresh (automatic)
“Token refresh failed”	Client credentials	Verify Client ID/Secret
”No subsidiary selected”	Configuration	Select default subsidiary
”No term selected”	Configuration	Select payment terms
”No language selected”	Configuration	Select PDF language

​

Common Configuration Issues

Issue	Check Location	Solution
Empty subsidiary list	Subsidiaries setup	Create at least one
Missing custom fields	Custom Fields	Create required fields
No payment terms	Payment Terms	Add standard terms
SuiteQL errors	Enable Features	Enable SuiteAnalytics Workbook
Product sync errors	Products	Sync products before using in deals/invoices
Network timeout	Connection	Check network/firewall settings

​

Testing Your Setup

​

Optional Test Data

If you want to test with sample data:

Record Type	Navigation	Required Fields
Customer	Lists > Relationships > Customers > New	Company Name, Subsidiary, Terms
Product	Lists > Accounting > Items > New	Type: Non-inventory or Service
Opportunity	Transactions > Sales > Create Opportunity	Link to test customer

​

Verify Permissions

1. Log in as integration user (or use “Login As”)
2. Try accessing each record type
3. Verify you can view required lists

​

Additional Resources

​

Documentation

• NetSuite Help Center
• SuiteAnswers (Login Required)
• API Concurrency Docs

​

Support Contacts

Support	Contact	Include in Request
Core8	support@core8.com	NetSuite Account ID, Screenshots, Error messages
NetSuite	Via NetSuite UI: Support > Contact Support	Reference REST Web Services and OAuth 2.0

​

Visual References

Look for these key elements in NetSuite:

1. Enable Features Page - Checkboxes for required features
2. Integration Record - Client ID and Secret display
3. Manage Roles Page - Edit/Customize buttons
4. Permissions Tab - 5 sub-tabs for different permissions
5. Custom Field Creation - Entity field forms

---

Document Version: 2.1 | Last Updated: January 2025 | Validated against Core8 codebase