NetSuite Tax Engine Integration Guide (SuiteTax)

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.

Step 1. Complete the Read-Only Setup First

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.

1. Work through the NetSuite Read-Only Integration Guide from start to finish.

2. 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.

3. 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.

Step 2. Enable Tax Collection in Kintsugi

1. In Kintsugi, go to Data Sources and find the NetSuite tile.

2. Select Enable Tax Collection.

3. Review the Vertex Terms and Conditions.

4. 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.

Step 3. Install Kintsugi Powered by Vertex in NetSuite

1. In Kintsugi, select Install Vertex on NetSuite. This opens the NetSuite SuiteApp marketplace.

2. 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).

3. Click Install to proceed in installing the plugin for Kintsugi Powered by Vertex for NetSuite (SuiteTax).

4. 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 — note the version number shown alongside it.

5. 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.

6. Once every subsidiary is on Vertex, enable the plug-in.

   1. Go to Vertex > Configuration > Enable Vertex Plugin
      

   2. Select VertexTaxEngine2.0, then select Save.
      
      

Step 4. Add the Post-Install Permission and Validate the Product Class List

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.

1. Go to Setup > Users/Roles > Manage Roles, then edit your Kintsugi role.

2. On the Permissions tab, open 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 NetSuire Read-Only Integration Guide (SuiteTax).
   

3. Select Save.

4. Go to Customization > Lists, Records & Fields > Lists and confirm the VT Product Class list is present and unlocked.

Step 5. Create the Vertex Client ID and Vertex Client Secret

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.

1. Go to Setup > Company > API Secrets and select New.

2. Create the Vertex Client ID:

   1. On the Details section, complete with the following fields:
      

      1. Name: a recognizable name, for example Kintsugi Client New.

      2. ID: a unique script ID, for example custsecretkintsugi_new_id.

      3. Password and Confirm Password.
         Paste the Client ID you copied from Kintsugi in Step 2.
         

      4. Select Save.
         

   2. On the Restrictions section, complete the following fields:
      

      1. Owners

      2. SuiteApp ID:

         com.vertexinc.vertexsuitetaxplugin

      3. Select the checkbox:

         • ALLOW FOR ALL SCRIPTS

         • ALLOW FOR ALL DOMAINS

      4. Click Update.

3. Create the Vertex Client Secret the same way:

   1. On the Details section, complete with the following fields:
      

      1. Name: for example Kintsugi Client Secret New.

      2. ID: a unique script ID, for example custsecretkintsugi_secret_new.

      3. Password and Confirm Password.
         Paste the Secret Key you copied from Kintsugi in Step 2.
         

      4. Select Save.
         

   2. On the Restrictions section, complete the following fields:
      

      1. Owners

      2. SuiteApp ID:

         com.vertexinc.vertexsuitetaxplugin

      3. Select the checkbox:

         • ALLOW FOR ALL SCRIPTS

         • ALLOW FOR ALL DOMAINS

      4. Click Update.
         

4. Both secrets now appear in the API Secrets list.

Note their two ID values. You will enter them in the next step.

Step 6. Configure Vertex Fields in NetSuite

1. In NetSuite, go to Vertex > Configuration > Company General Preferences > Custom Preferences.

2. Populate the following fields.

3. Select Save.

   Make a note of the Receivables and Payable accounts you selected, since Step 7 uses the same two values.

Step 7. Enable Tax Type and Tax Code Sync (One-Time Setup)

RESTLET:

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

SCRIPT MANUAL STEP ( IF ABOVE FAILS ):

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

Step 8. Set Up the Kintsugi Tax Agency

A tax agency is a subsidiary-level field, so you need one for every subsidiary, and each subsidiary's tax registrations must point to it. Always name it exactly “Kintsugi Tax Agency”.

8.1 Create the Kintsugi Tax Agency

1. Go to Lists > Relationships > Vendors > New.

2. Fill in the required details.

   1. Set the Name to Kintsugi Tax Agency

   2. Set the Category to Tax Agency.

   3. Select Save.

   4. Repeat for each subsidiary.

8.2 Assign the tax agency to each subsidiary tax registration

1. Go to Setup > Company > Subsidiaries and open a subsidiary.

2. On the Tax Registrations tab, for every nexus listed, set Tax Agency to Kintsugi Tax Agency.

3. While you are here, 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.

4. Select Save. Repeat for every subsidiary.
   

Step 9. Mark Vertex as Installed in Kintsugi

Now that NetSuite is fully configured, finish the activation in Kintsugi.

1. Return to Kintsugi and go to Data Sources.

2. On the NetSuite tile, select Mark as Installed.

3. Kintsugi begins syncing your existing nexuses, registrations, and products to Vertex.

Step 10. Approve Your Products in Kintsugi

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.

1. In Kintsugi, go to Products.

2. Make sure every product has a category and subcategory. Classification is what drives taxability, so unclassified products may be taxed incorrectly.

3. 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.

Step 11. Test the Connection

After activation, you can calculate tax directly on NetSuite invoices via Vertex.

1. In your NetSuite account, go to Transactions > Create Invoice.

2. Add a sample customer. A customer with a taxable ship-to address works best.

3. Add one or more line items. Use products you approved in Step 10.

4. Select Preview Tax to trigger Vertex. Tax lines display under Tax Details.

5. Select Accept Payment to complete the invoice.

6. Return to Kintsugi and go to Transactions.

7. Confirm the sample invoice appears in your transactions list. This shows the sync is working correctly.

Important Notes

• 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.2).
  

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.