Kintsugi (powered by Vertex) supports a tax engine integration with NetSuite. Once enabled, Vertex calculates sales tax directly on your NetSuite documents, and Kintsugi keeps your nexuses, registrations, and product classifications in sync with the engine. This currently supports NetSuite accounts running SuiteTax. Legacy Tax support is coming soon.
Start Here: Read-Only Comes First
The tax engine integration builds on the read-only NetSuite connection. It uses the same role, user, integration record, and access token, then adds the Kintsugi Powered by Vertex SuiteApp on top. If you have not connected NetSuite yet, complete the NetSuite Read-Only Integration Guide first, then return here.
Scale or Premium Plan Required
The NetSuite Tax Engine Integration (Kintsugi Powered by Vertex) is only available on the Scale and Premium plans. Accounts on the Starter plan will not see the Enable Tax Collection option and cannot activate the Vertex integration. Make sure the account is upgraded to Scale or Premium before you begin.
Do not create a separate role, user, integration record, or access token for the tax engine. Everything below uses the ones from the read-only connection.
Work through the NetSuite Read-Only Integration Guide from start to finish.
When you set role permissions, add every permission in that guide's lists. Pay particular attention to Customers – Full and Perform Search – View under Lists; these are the most commonly missed, and without them the sync will not work.
Confirm your NetSuite tile in Data Sources shows a status of Read-Only before continuing. This confirms your credentials work and the initial sync has finished.
Already connected as read-only?
You do not need to reconnect. Go to Setup > Users/Roles > Manage Roles and confirm your existing Kintsugi role has every permission in the read-only guide. Then go to Setup > Integration > Manage Integrations, open your integration record, and add RESTlets to the OAuth 2.0 scope. In Step 4 you will also add Vendors at Full and raise Accounting Lists from View to Full on this same role.
Already have Kintsugi Powered by Vertex installed?
If the SuiteApp is already in your NetSuite account from an earlier setup, upgrade it to the latest version (1.0.24 or later) before you start the steps below.
Go to Customization > SuiteBundler > Search & Install Bundles > List, find Kintsugi Powered by Vertex for NetSuite (SuiteTax), and select Upgrade if one is available. Running the setup on an outdated bundle causes configuration steps to fail. After you upgrade, add the subsidiary permissions to the two Vertex roles again (Step 3, item 5), since an upgrade can reset them.
In Kintsugi, go to Data Sources and find the NetSuite tile.
Select Enable Tax Collection.
Review the Vertex Terms and Conditions.
Your Company Code, Client ID, and Secret Key are generated.
Copy all three now. You will need them in Steps 5 and 6, and you can return to this window at any time to copy them again.
⚠️ Do not click “Mark as Installed” yet. The Kintsugi Powered by Vertex window includes a Mark as Installed button. Leave this window as it is and finish the NetSuite configuration in Steps 3 to 7 first. Selecting it before NetSuite is fully configured triggers sync errors. You will come back and complete this in Step 9.
In Kintsugi, select Install Vertex on NetSuite. This opens the NetSuite SuiteApp marketplace.
NetSuite does not provide a direct link to the Kintsugi Powered by Vertex plugin, so you need to search for it.
In the marketplace search bar, type Kintsugi and open Kintsugi Powered by Vertex for NetSuite (SuiteTax).
Click Install to proceed in installing the plugin for Kintsugi Powered by Vertex for NetSuite (SuiteTax).
To check installation progress, in NetSuite go to Customization > SuiteCloud Development > Deployment Audit Trail and confirm the install completed.
The Deployment Audit Trail is NetSuite's installation progress page. Find the most recent entry for Kintsugi Powered by Vertex. When its Status shows Complete, the install is finished. Check the version number shown next to it. It should be 1.0.24 or later. If it is lower, upgrade the SuiteApp before you continue.
Add subsidiary permissions to the two Vertex roles. Installing the SuiteApp creates two roles that run its scripts: Vertex Script Role and Vertex Tax Engine. Both roles need access to your subsidiary records, and the install does not add this access for you. Do this right after the install finishes, before you switch your subsidiaries to Vertex.
Go to Setup > Users/Roles > Manage Roles.
Open Vertex Script Role and select Edit.
On the Permissions tab, open Lists and add the two permissions in the table below. If either one is already listed at a lower level, raise it to the level shown.
Select Save.
Repeat for Vertex Tax Engine.
Lists permission (add to both Vertex roles) | Level |
|---|---|
Subsidiaries | Full |
Entity-Subsidiary Relationship | View |
Upgrading the SuiteApp later?
An upgrade can reset both Vertex roles. After every upgrade, open Vertex Script Roleand Vertex Tax Engine and confirm the two Lists permissions above are still there. Add them back if they are missing.
If NetSuite does not let you save either role, reach out to us using the chat bubble before you continue, and we will help you finish the setup.
Switch each subsidiary's tax engine to Vertex. Go to Setup > Company > Subsidiaries, open each subsidiary, and on the Tax Registrations tab change the tax engine from SuiteTax to Vertex for every registration listed. Save, and repeat for every subsidiary. The Vertex plug-in cannot be enabled while any subsidiary is still on SuiteTax.
Once every subsidiary is on Vertex, enable the plug-in.
Go to Vertex > Configuration > Enable Vertex Plugin
Select VertexTaxEngine2.0, then select Save.
The Vertex Product Class Inbound Request custom record does not exist in your account until the SuiteApp is installed, which is why the read-only guide could not include it. Now that the install is complete, go back to your Kintsugi role and add it. While you are there, update two more permissions that Kintsugi needs to set up the Kintsugi Tax Agency.
Go to Setup > Users/Roles > Manage Roles, then edit your Kintsugi role.
On the Permissions tab, set each permission in the table below. If one is already listed at a lower level, raise it to the level shown.
Under Custom Record, you should now see two records. Add Vertex Product Class Inbound Request and set its level to Full. Leave STE Item Tax Exemption at View, as set in the read-only guide.
Under Lists, add Vendors at Full.
Under Setup, change Accounting Lists from View to Full.
Tab | Permission | Level |
|---|---|---|
Custom Record | Vertex Product Class Inbound Request | Full |
Custom Record | STE Item Tax Exemption | View (no change) |
Lists | Vendors | Full (new) |
Setup | Accounting Lists | Full (was View) |
Why Vendors and Accounting Lists?
When Kintsugi attaches your tax registrations, it makes sure each subsidiary's registrations point to a Kintsugi Tax Agency vendor (Step 8). If a subsidiary has no such vendor, Kintsugi creates one. If the vendor is inactive, Kintsugi reactivates it. Vendors at Full lets Kintsugi create and update the vendor. Accounting Lists at Full lets Kintsugi create the "Tax Agency" vendor category if your account does not have one. Without these, the registrations are not attached and Preview Tax returns no tax.
Select Save.
Go to Customization > Lists, Records & Fields > Lists and confirm the VT Product Class list is present and unlocked.
NetSuite stores credentials as API Secrets. You will create two: one holding the Client ID and one holding the Secret Key you copied from Kintsugi in Step 2. The Vertex configuration in Step 6 references these secrets by their IDs.
5.1. Go to Setup > Company > API Secrets and select New.
5.2. Create the Vertex Client ID:
On the Details section, complete with the following fields:
Name: a recognizable name, for example Kintsugi Client New.
ID: a unique script ID, for example custsecretkintsugi_new_id.
Password and Confirm Password.
Paste the Client ID you copied from Kintsugi in Step 2.
Select Save.
On the Restrictions section, complete the following fields:
Owners
SuiteApp ID:
com.vertexinc.vertexsuitetaxpluginSelect the checkbox:
ALLOW FOR ALL SCRIPTS
ALLOW FOR ALL DOMAINS
Click Update.
5.3. Create the Vertex Client Secret the same way:
On the Details section, complete with the following fields:
Name: for example Kintsugi Client Secret New.
ID: a unique script ID, for example custsecretkintsugi_secret_new.
Password and Confirm Password.
Paste the Secret Key you copied from Kintsugi in Step 2.
Select Save.
On the Restrictions section, complete the following fields:
Owners
SuiteApp ID:
com.vertexinc.vertexsuitetaxpluginSelect the checkbox:
ALLOW FOR ALL SCRIPTS
ALLOW FOR ALL DOMAINS
Click Update.
5.4. Both secrets now appear in the API Secrets list.
Note their two ID values. You will enter them in the next step.
In NetSuite, go to Vertex > Configuration > Company General Preferences > Custom Preferences.
Populate the following fields.
Field | Value |
|---|---|
Company Code | The Company Code from your Kintsugi account (Step 2) |
Client ID | The ID of the Vertex Client ID in Step 5 (for example, custsecretkintsugi_client_id) |
Client Secret | The ID of the Vertex Client Secret in Step 5 (for example, custsecretkintsugi_secret_new) |
Use Token | Checked |
Use REST | Checked |
Token URL | |
REST Base URL | |
Address Service URL | https://calcconnect.vertexsmb.com/vertex-ws/v2/address-lookup |
Tax Service URL | |
Receivables Account | Your accounts receivable account |
Payable Account | Your accounts payable account |
Select Save.
Make a note of the Receivables and Payable accounts you selected, since Step 7 uses the same two values.
Go to Customizations → Scripting → Script Deployments → Filter in Type Option → RESTLET. Edit the Script
Script Name: Vertex RT Ensure Tax Types Codes
Script_Id: customdeploy_ensure_taxtype_code_vt
Under Parameters Section, add the following two values for Account Receivables and Account Payable. They should be the same as defined in the above ( Non OneWorld Licence only ). OneWorld Licence Installation instruction would be different.
RECEIVABLES ACCOUNT: according to customer -> same as above
PAYABLE ACCOUNT: according to customer → same as above
Go to Customizations → Scripting → Script Deployments → Filter in Type Option → Scheduled
Search for a Deployment with these values
DeploymentID: customdeploy_taxtype_taxcode_sche_vt_2
Deployment Name: Vtx Sales Taxtypes Taxcodes Sche 2.0
Script Name: ( Visible once you open the deployment ): Vertex Sales Taxtypes Taxcodes Sche 2.0
Status: Not Scheduled
Click on Edit → Parameters → Add Receivables and Payables
RECEIVABLES ACCOUNT: according to customer -> same as above during the installation
PAYABLE ACCOUNT: according to customer → same as above during the installation
https://tstdrv2107702.app.netsuite.com/app/common/scripting/script.nl?id=348
Re-Running Manually - In case automation Fails:
Go to Customizations → Scripting → Script Deployments → Edit → Save and Execute
Save and Execute always runs the script directly after, this sets up tax code and tax groups in the nexuses
Preview Tax needs every tax registration to point to a tax agency. NetSuite allows a tax agency vendor to belong to only one subsidiary, so each subsidiary needs its own. You do not need to create these vendors yourself. When Kintsugi attaches your tax registrations after Step 9, it does this for you:
It looks for an existing vendor named Kintsugi Tax Agency with the category Tax Agency on each subsidiary, and uses it.
If a subsidiary has no such vendor, Kintsugi creates one with the company name Kintsugi Tax Agency. In accounts with subsidiaries, the vendor's name ends with the subsidiary's internal ID, for example Kintsugi Tax Agency - 3.
If the vendor is inactive, Kintsugi reactivates it.
Kintsugi sets Tax Agency on the registration if it is blank. It never replaces a tax agency you already set.
Kintsugi needs the Vendors and Accounting Lists permissions from Step 4 to do this.
Already created a Kintsugi Tax Agency vendor yourself?
Kintsugi reuses it, as long as it is named Kintsugi Tax Agency, its category is Tax Agency, and its subsidiary matches. If a vendor with that name has a different category, Kintsugi does not change it or create a second one. The registration is not attached until you set that vendor's category to Tax Agency.
Go to Setup > Company > Subsidiaries and open a subsidiary.
On the Tax Registrations tab, confirm each registration shows Kintsugi Tax Agency as its Tax Agency.
Check each registration's Effective From date. It must be on or before the date of the first transaction you want Vertex to tax. A registration dated in the future, or after your transactions, will not calculate tax. When Kintsugi adds a registration, it uses today's date unless Kintsugi has a different start date for that registration.
Repeat for every subsidiary.
Now that NetSuite is fully configured, finish the activation in Kintsugi.
Return to Kintsugi and go to Data Sources.
On the NetSuite tile, select Mark as Installed.
Kintsugi begins syncing your existing nexuses, registrations, and products to Vertex. As it attaches each registration, it also sets up the Kintsugi Tax Agency (Step 8).
Vertex only calculates tax for products that are approved in Kintsugi. Until a product is approved, invoices containing it will return no tax, even if everything in NetSuite is configured correctly.
In Kintsugi, go to Products.
Make sure every product has a category and subcategory. Classification is what drives taxability, so unclassified products may be taxed incorrectly.
Approve each product. Products synced from NetSuite are not approved automatically.
💡 New products added in NetSuite after setup will also need to be classified and approved in Kintsugi before tax is calculated on them.
After activation, you can calculate tax directly on NetSuite invoices via Vertex.
In your NetSuite account, go to Transactions > Create Invoice.
Add a sample customer. A customer with a taxable ship-to address works best.
Add one or more line items. Use products you approved in Step 10.
Select Preview Tax to trigger Vertex. Tax lines display under Tax Details.
Select Accept Payment to complete the invoice.
Return to Kintsugi and go to Transactions.
Confirm the sample invoice appears in your transactions list. This shows the sync is working correctly.
Adding or changing line items clears the tax calculation. You must select Preview Tax again.
Items and addresses determine which nexus applies.
Saving the invoice sends the transaction to Kintsugi on the next 15-minute sync cycle.
If Preview Tax returns no tax, check that the product is approved in Kintsugi (Step 10) and that the subsidiary's tax registration has the Kintsugi Tax Agency assigned with a valid effective date (Step 8).
If tax registrations fail to attach with a "Permission Violation: You need a higher level of the 'Lists -> Vendors' permission" error, make sure your Kintsugi role has Vendors at Full and Accounting Lists at Full (Step 4).
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.