> ## Documentation Index
> Fetch the complete documentation index at: https://docs.numeral.com/llms.txt
> Use this file to discover all available pages before exploring further.
# NetSuite
> Connect NetSuite to Numeral for compliance syncing, then install the SuiteTax engine SuiteApp for real-time tax calculation.
The Numeral ↔ NetSuite integration has two separate parts:
1. **The NetSuite connection from Numeral** — a read-only sync that pulls your orders, products, and customers from NetSuite into Numeral. This is what powers nexus monitoring and tax filings, and it should be set up first.
2. **The Numeral SuiteTax Engine** — a SuiteApp that registers Numeral as a tax provider in NetSuite's SuiteTax framework. This is the piece that actually calculates and applies tax in real time: once enabled and configured, NetSuite calls Numeral whenever you preview or save tax on a sales transaction, and the resulting tax detail is recorded back to Numeral.
The SuiteTax Engine SuiteApp requires NetSuite with the **SuiteTax** feature enabled — legacy tax engine accounts are not supported. The connection in step 1 does **not** require SuiteTax and can be set up right away, regardless of where you are in a SuiteTax migration.
## What you'll do
1. Connect NetSuite to Numeral
2. Install the Numeral SuiteApp for tax calculation
3. Verify the **Numeral SuiteTax Engine** plug-in is enabled
4. Configure the **Numeral Credentials** record
5. Configure your NetSuite **Nexuses**, **Tax Codes**, and **Tax Types**
6. Test on a Sales Invoice
***
## 1. Connect NetSuite to Numeral
Do this first, before installing the SuiteApp — the rest of this guide assumes it's already in progress.
Adding NetSuite as a connection authorizes Numeral to read your orders, products, and customers out of NetSuite. This connection is **read-only**: Numeral only pulls data out, it never writes anything back. It's what feeds nexus monitoring and tax filings on the compliance side, and it's entirely separate from tax calculation, which is handled by the SuiteApp in the next step — you don't need SuiteTax or the SuiteApp installed for this connection to work.
1. Log in to your Numeral dashboard and go to **Connections**.
2. Click **Add a Connection** and select **NetSuite**.
3. Follow the prompts to authorize the connection to your NetSuite account. If you're also testing in a sandbox, connect your **production** account in parallel rather than sandbox alone.
Make sure your **production** NetSuite account is connected, not just a sandbox. Numeral uses this connection to import your real sales data for nexus monitoring and filings — a sandbox connection is fine for testing alongside it, but if production is never connected, that data never reaches Numeral, which blocks filings.
Set this connection up as early as possible. It only takes a minute to authorize, but NetSuite's initial data sync can take longer to complete behind the scenes due to rate limiting — your product categories won't be available in Numeral until it finishes, and later steps in this guide (like matching Tax Codes to your products) depend on that data being in place.
***
## 2. Install the SuiteApp (tax calculation)
Numeral will share a private SuiteApp installation link. Install it under **Customization → SuiteBundler → Search & Install Bundles** (legacy) or via **Customization → SuiteApps** (modern).
This is the piece of the integration that handles real-time tax calculation — it's what actually looks up and applies tax rates on your NetSuite transactions. After installation completes, the bundle deploys:
* A SuiteTax plug-in implementation called **Numeral SuiteTax Engine**
* A custom record type called **Numeral Credentials**
* Supporting scripts for transaction events
## 3. Enable the SuiteTax plug-in
Go to **Customization → Plug-ins → Manage Plug-ins** and confirm **Numeral SuiteTax Engine** is checked.
This checkbox is the tax calculation kill switch — unchecking it disables Numeral tax calculation NetSuite-wide without uninstalling the bundle. It has no effect on the read-only connection from step 1.
## 4. Configure Numeral Credentials
Go to **Customization → Lists, Records, and Fields → Record Types** and open the **Numeral Credentials** record type. Click **New Record** and provide:
| Field | Value |
| ---------------- | ------------------------------------------------------------ |
| **API Key** | A `sk_test_*` or `sk_prod_*` key from your Numeral dashboard |
| **API Endpoint** | The Numeral API endpoint Numeral provided |
| **Test Mode** | Enable while validating |
Save the record.
## 5. Configure Nexuses, Tax Codes, and Tax Types
NetSuite requires tax results to map onto the existing Nexus, Tax Code, and Tax Type records on the account. The Numeral SuiteTax Engine matches Numeral's calculated jurisdictions to NetSuite records by **state**, so each US state where you have nexus needs to have:
* A NetSuite **Nexus** (Setup → Tax → Nexuses)
* A **Tax Code** assigned to that Nexus (Setup → Tax → Tax Codes)
* A **Tax Type** assigned to that Nexus (Setup → Tax → Tax Types)
The names you choose for the Tax Code and Tax Type aren't important — Numeral matches by Nexus state, not by name.
If a transaction's shipping state has no matching Nexus + Tax Code + Tax Type, NetSuite will reject the calculation. Add the missing records before testing in that state.
## 6. Test on a Sales Invoice
1. Go to **Transactions → Sales → Create Invoices**
2. Select a customer with a US shipping address
3. Add at least one line item
4. Click **Preview Tax**
NetSuite will call Numeral. The resulting tax appears in the **Tax Total** field, with the Numeral-calculated jurisdiction breakdown surfaced via the SuiteTax detail records.
After saving the invoice, the transaction is recorded in your Numeral dashboard under **Transactions**.
## Supported transactions
| Transaction | Tax calculated | Recorded to Numeral |
| ------------- | -------------- | ------------------- |
| Sales Order | ✓ | (on bill / invoice) |
| Cash Sale | ✓ | ✓ |
| Sales Invoice | ✓ | ✓ |
| Credit Memo | ✓ | ✓ |
| Cash Refund | ✓ | ✓ |
## Troubleshooting
Confirm the **Numeral SuiteTax Engine** plug-in is enabled under **Customization → Plug-ins → Manage Plug-ins**, and that a **Numeral Credentials** record exists with a valid API key.
Add a Nexus for that state (Setup → Tax → Nexuses) along with a Tax Code and Tax Type assigned to that Nexus. Numeral matches by Nexus state.
Confirm the transaction was saved (not just previewed) and that the API key on the **Numeral Credentials** record is for the correct environment. Check **Setup → Integration → Web Services Logs** for HTTP errors from the SuiteApp.
Open the **Numeral Credentials** custom record and update the **API Key** field. No script redeploy required.
Having the SuiteApp installed doesn't mean the NetSuite connection from step 1 is set up — they're independent. Check **Connections** in your Numeral dashboard and confirm your **production** NetSuite account (not a sandbox) is connected.