NetSuite Read-Only Integration Guide (SuiteTax)
Set up the NetSuite read-only integration with Kintsugi powered by Vertex. Get your account ID, create a role with required permissions, and sync transactions.Updated 2 seconds ago
Kintsugi (powered by Vertex) now supports a read-only integration with NetSuite. This integration syncs your NetSuite transaction data into Kintsugi, supporting SuiteTax environments.
Start Here: Read-Only Comes First
The read-only connection is the foundation for both NetSuite integration types. Complete this guide first, even if your goal is real-time tax calculation in NetSuite.
The tax engine integration does not replace this connection and does not use a separate one. It builds on the same role, user, integration record, and access token you create here, then adds the Kintsugi Powered by Vertex SuiteApp on top. Your NetSuite tile in Data Sources must show a status of Read-Only before you can enable tax collection.
Planning to use the tax engine? Add every permission listed below, and check RESTlets under the OAuth 2.0 scope when you create your integration record. Setting both up in one pass saves you from editing the role and the integration record again later.
Once this guide is complete, continue with the NetSuite Tax Engine Integration Guide. The tax engine integration requires the Premium plan.
⚠️ SuiteTax Required
Kintsugi currently supports NetSuite accounts running SuiteTax. Legacy Tax support is coming soon.
Step 1. Get Credentials from your NetSuite Account
1. Log in to your NetSuite Administrator account.
2. Get your Account ID.
2.1 Go to Setup > Company > Company Information.
2.2. On your Company Information page, scroll down until you see your Account ID.
2.3. Copy the Account ID.
3. Set Up Role Permission
To grant access to the NetSuite, you need to create a user role to get Access Tokens using Token-Based Authentication.
3.1. Go to Setup > Users/Roles > Manage Roles > New.
3.2. Give the role a name (e.g. Kintsugi Role).
3.3. Under the 'Permissions' tab, select the appropriate permissions for the role. The role needs the necessary permissions to perform the integration tasks.
3.4. Add every permission listed below. The same set is required whether you use the read-only integration only or go on to enable tax calculation in NetSuite.
Transactions Permission
Cash Sale – Full
Cash Sales Refund – Full
Credit Memo – Full
Find Transaction – Full
Invoice – Full
Invoice Sales Orders – Full
Sales Order – Full
Lists Permission
Accounts – Full
Companies – Full
Contacts – Full
Currency – Full
Customer Profile – Full
Customers – Full
Employees – Full
Items – Full
Locations – Full
Perform Search – View
Subsidiaries – Full
Subsidiary Tax Registrations Tab – Full
Tax Detail Tab – Full
Tax Records – Full
⚠️ Double-check Customers and Perform Search. These two Lists permissions are the ones most often missed. Without Customers – Full, every sync except products fails. Without Perform Search – View, the connection cannot run at all.
Setup Permission
Access Token Management – Full
Accounting Lists – View
Custom Lists – Full
Log in using Access Tokens – Full
REST Web Services – Full
SOAP Web Services – Full
Set up Company – Full
SuiteScript – Full
Custom Records Permission
STE Item Tax Exemption – View
Vertex Product Class Inbound Request – Full (tax engine only; not available yet — see note below)
🔎 Important Note (for tax engine setups only)
The Vertex Product Class Inbound Request custom record must be added at Full level, but you cannot add it now.
The record does not exist in your account until the Kintsugi Powered by Vertex SuiteApp is installed, so it will not appear in the Custom Record list yet. Only STE Item Tax Exemption shows at this stage, as in the screenshot above. After you install the SuiteApp, come back to this role and add it. The NetSuite Tax Engine Integration Guide walks you through this at the right point (on its Step 4).
Reports Permission
SuiteAnalytics Workbook – Edit
4. Create the Kintsugi User and Assign the Role
The access token you create later must be tied to a user that holds the role you just built.
4.1. Go to Setup > Users/Roles > Manage Users > New, then complete the user record (for example, Kintsugi User). Save the record.
4.2. Open the user record, then select Edit.
4.3. Go to the Access tab and add the role you created in the previous step.
4.4. Select Save.
5. Get the Consumer Key & Consumer Secret
5.1. Go to Setup > Integration > Manage Integrations > New.
5.2. Complete the Integration information.
a. Name: Enter a proper name (for example, Kintsugi App).
b. Authentication: Under the 'Authentication' section,
Select Token-Based Authentication.
Keep TBA: Authorization Flow checked, and set https://unify.apideck.com/vault/callback as the callback URL.
Leave TBA: Issue Token Endpoint unchecked. It is not needed.
c. OAuth 2.0: Under the 'OAuth 2.0' section,
Check Authorization Code Grant.
Under Scope, check REST Web Services.
Also check RESTlets if you plan to enable the tax engine. RESTlets carries the product class sync that Kintsugi Powered by Vertex uses. Checking it now is harmless for a read-only connection and saves you from editing this record later.
d. Select 'Save'.
Once saved, the Consumer Key and Consumer Secret will be generated.
💡 TIP: Copy the "Consumer Key" and the "Consumer Secret". You can't access this information once you exit the screen.
6. Get Access Token ID & Access Token Secret
6.1. Go to Setup > Users/Roles > Access Tokens > New.
6.2. Complete the form.
Select the "Application Name" that you have created in the previous step (e.g. Kintsugi App).
Select the "User", which we created in the previous steps (e.g. Kintsugi User).
Give the token a recognizable "token name" (e.g. Kintsugi Token).
Click the 'Save' button to save the changes.
6.3. Once saved, the Access Token ID and Access Token Secret will be generated.
💡 TIP: Copy the "Token ID" and the "Token Secret". You can't access this information once you exit the screen.
Step 2. Integrate NetSuite to Kintsugi
1. Log in to your Kintsugi account.
2. Connect NetSuite
2.1. Go to Data Sources.
2.2. Click Browse Integration.
2.3. Look for NetSuite and click the Connect button.
2.4. Enter NetSuite Credentials.
Account ID
⚠️ IMPORTANT: The NetSuite Account/Company ID must use an underscore (e.g., 1234567_SB1). Using a hyphen will cause the connection to fail with the error "Cannot connect to NetSuite."
From the items you copied in the earlier steps, paste each of the entries into its matching field.
Consumer Key
Consumer Secret
Access Token ID
Access Token Secret
SuiteTax Enabled (Yes/No)
Click Save, then refresh your Kintsugi page.
3. Wait for the Initial Sync to Complete
Kintsugi will immediately begin syncing your data from NetSuite:
Invoices
Customers
Orders
During the initial sync, the integration status will show Syncing.
This gives Kintsugi the data it needs to start tracking your economic nexus exposure across every state.
Once the sync is complete, the status will update to Read-Only, confirming that the import is done and your NetSuite data is live in Kintsugi.
Step 3. Test the Connection
In your NetSuite account, go to Transactions > Create Invoice.
Add a sample customer and add one or more items.
Click Accept Payment to complete the invoice.
Return to Kintsugi > Transactions.
Confirm the sample invoice appears in your transactions list—showing that the sync is working correctly.
Looking to Enable Tax Calculation?
This read-only integration supports data sync and reporting only. It does not return calculated tax to NetSuite.
To calculate tax on NetSuite documents, keep this connection in place and continue with the NetSuite Tax Engine Integration Guide. That guide starts from the point this one ends and covers the Kintsugi Powered by Vertex SuiteApp install and configuration. The tax engine integration requires the Premium plan.
Need Help?
For further concerns, we're always here to help. If you can't find the answer you're looking for, please reach out to us using the chat bubble in the bottom right corner.