/ /

NetSuite Tax Engine Integration Guide (SuiteTax)

Set up the NetSuite tax engine integration with Kintsugi powered by Vertex, available on Scale and Premium. Get account credentials, role permissions, and sync steps.
Updated 9 days ago

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.


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.

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.


Step 2. Enable Tax Collection in Kintsugi

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

  2. Select Enable Tax Collection.

  1. Review the Vertex Terms and Conditions.

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


Step 3. Install Kintsugi Powered by Vertex in NetSuite

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

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

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

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

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

    1. Go to Setup > Users/Roles > Manage Roles.

    2. Open Vertex Script Role and select Edit.

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

    4. Select Save.

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

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

  2. 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 Permissions 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. While you are there, update two more permissions that Kintsugi needs to set up the Kintsugi Tax Agency.

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

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

  1. Select Save.

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

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

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

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

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

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

https://auth.vertexcloud.com/oauth/token

REST Base URL

https://calcconnect.vertexsmb.com/vertex-ws

Address Service URL

https://calcconnect.vertexsmb.com/vertex-ws/v2/address-lookup

Tax Service URL

https://calcconnect.vertexsmb.com/vertex-ws/v2/supplies

Receivables Account

Your accounts receivable account

Payable Account

Your accounts payable account

  1. 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. Kintsugi Tax Agency (Set Up Automatically)

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.

Check the tax registrations after Step 9

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

  2. On the Tax Registrations tab, confirm each registration shows Kintsugi Tax Agency as its Tax Agency.

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

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

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


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

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


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.

Was this article helpful?