Setup & Troubleshooting Guide

This guide walks a NetSuite administrator through everything needed to connect NetSuite to SmartHub, and how to fix the most common connection problems. Follow the sections in order. Most setups take about 15–20 minutes.

You will need Administrator access in NetSuite to complete the setup.

What you'll set up

1. Enable the required NetSuite features

2. Install the SyncSmart bundle

3. Assign the SyncSmart integration role to a user

4. Create an access token (gets you a token ID & secret)

5. Enter three values into SmartHub and validate

SmartHub already supplies the integration's consumer key behind the scenes, so you do not need to create your own Integration record or handle a consumer key/secret. The bundle also ships a ready-made role with all required permissions, so there's nothing to configure permission-by-permission — you just assign that role.

Keep a scratch document open as you go. You'll enter just three things into SmartHub at the end, and NetSuite shows the token secret only once:

• Account ID

• Token ID

• Token Secret

Part 1 — Enable the required NetSuite features

Go to Setup → Company → Enable Features → SuiteCloud tab, and make sure the following are checked. Enabling any of these may prompt you to accept the SuiteCloud Terms of Service — that's a normal one-time acceptance, at no additional cost.

Note: You do not need to enable OAuth 2.0 — SmartHub uses Token-Based Authentication (a different mechanism). Leaving OAuth 2.0 off is fine.

Click Save after checking the boxes.

Important: enable these in the production account where SmartHub will connect. Enabling them only in a sandbox will not unblock a production connection.

Part 2 — Install the SyncSmart bundle

1. Customization → SuiteBundler → Search & Install Bundles.

2. Search for the SyncSmart bundle (or use the bundle ID provided by your SyncSmart contact).

3. Click Install and wait for the status to show Installed.

4. The bundle installs two things you'll use next: the SyncSmart integration record (the “Application” you'll select when creating your token) and the SyncSmart Integration Role (e.g., SyncSmart Integration Role v3.0), which already contains every permission the connection needs.

Part 3 — Create the Access Token

This produces the Token ID and Token Secret.

1. Setup → Users/Roles → Access Tokens → New (or type “Page: Access Tokens” in the global search box, then New).

2. Set: Application (the SyncSmart integration installed by the bundle in Part 2), User (the admin user you assigned the role to in Part 3), and Role (the SyncSmart Integration Role v3.0).

3. Click Save.

4. NetSuite displays the Token ID and Token Secret — copy both immediately. They are shown only once and cannot be retrieved later.

Note: The token, the user, and the role are locked together. If you need a different role or user later, you must create a new token.

Part 4 — Enter credentials in SmartHub and validate

In SmartHub, open the NetSuite connection and enter the three items:

• Account ID — find it under Setup → Company → Company Information (field: Account ID).

• Token ID (from Part 4).

• Token Secret (from Part 4).

Run the connection validation. A successful validation confirms both that authentication works and that the SyncSmart bundle is installed.

Troubleshooting

First: a note on error messages

SmartHub may report an authentication or “invalid credentials” style error when the real cause is a disabled feature, not a bad token. So if you're confident the values are correct, don't stop at the token — work through the checklist below. A quick way to confirm the token itself is fine is that the same token often works once the feature gap is closed.

The connection won't authenticate (403 / “Forbidden” / “Invalid credentials”)

Work through these in order — they're listed most-likely-first based on real setups:

1. REST Web Services is not enabled. This is the #1 cause. Re-check Setup → Company → Enable Features → SuiteCloud → REST Web Services is checked and saved. A missing feature is rejected before your credentials are even evaluated — which is why it can fail even with an administrator-level token.

2. Token-Based Authentication is not enabled. Confirm the account feature is on (Part 1). The SyncSmart integration itself already has TBA enabled, so you don't need to touch it — but the account-level feature must be on.

3. The token isn't using the SyncSmart Integration Role. The bundle role already has every permission needed, so a permission-level 403 almost always means the token was bound to a different role. Check Setup → Users/Roles → Access Tokens — the token's Role should be the SyncSmart Integration Role and its Application should be the SyncSmart integration. If not, create a fresh token (Part 4) with the right pairing.

4. The role isn't assigned to the user, or the user lacks privileges. Confirm the user on the token has the SyncSmart Integration Role assigned (Part 3) and is an Administrator-privileged user.

5. Wrong account / environment. Tokens and integration records do not transfer between accounts. A token created in a sandbox will not work against production (and vice versa). After a sandbox refresh or Release Preview, tokens must be regenerated. Confirm the Account ID in SmartHub matches the account where you enabled the features and installed the bundle.

6. IP address restrictions. If your NetSuite account restricts API access by IP address (Setup → Integration → Web Services Preferences, or IP rules on the company/integration), calls from SmartHub's servers will be blocked with a 403 regardless of role. If your security team enforces an IP allowlist, they'll need to allow SmartHub's outbound addresses — ask your SyncSmart contact for the current list.

“Bundle not installed” message

Authentication succeeded, but SmartHub can't find the SyncSmart custom records. Re-check Part 2 — the bundle install shows Installed under Customization → SuiteBundler → List of Installed Bundles. If a previous install failed partway, uninstall and reinstall.

Still stuck — how to isolate the problem

• Confirm REST Web Services is on first. If the connection fails even though the token is freshly created with the SyncSmart role and an admin user, the cause is almost certainly a disabled feature (Part 1) or an account-level block like IP restrictions — not the role or the token.

• Capture the exact error. Note the status code and message SmartHub returns. A 403 with a feature/permission message points to Part 1; an authentication-signature error points to a mistyped credential or an account-ID mismatch.

• Double-check the Account ID for typos, including any environment suffix for sandbox accounts.

Quick reference checklist

Features (Setup → Company → Enable Features → SuiteCloud):

☐  REST Web Services

☐  Token-Based Authentication

☐  Client SuiteScript

☐  Server SuiteScript

Bundle (Customization → SuiteBundler):

☐  SyncSmart bundle shows Installed

Role (Setup → Users/Roles → Manage Users):

☐  SyncSmart Integration Role assigned to an Administrator-privileged user

Access token (Setup → Users/Roles → Access Tokens):

☐  Application = SyncSmart integration

☐  User = the admin user, Role = SyncSmart Integration Role

☐  Token ID & Secret saved

☐  State = Active

SmartHub:

☐  Account ID, Token ID, Token Secret entered

☐  Validation passes