> ## 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

> SuiteTax engine SuiteApp for tax calculation on NetSuite sales transactions.

The Numeral SuiteTax Engine is a SuiteApp that registers Numeral as a tax provider in NetSuite's SuiteTax framework. 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.

<Note>
  This integration requires NetSuite with the **SuiteTax** feature enabled. Legacy tax engine accounts are not supported.
</Note>

## What you'll do

1. Install the Numeral SuiteApp
2. Verify the **Numeral SuiteTax Engine** plug-in is enabled
3. Configure the **Numeral Credentials** record
4. Configure your NetSuite **Nexuses**, **Tax Codes**, and **Tax Types**
5. Test on a Sales Invoice

***

## 1. Install the SuiteApp

Numeral will share a private SuiteApp installation link. Install it under **Customization → SuiteBundler → Search & Install Bundles** (legacy) or via **Customization → SuiteApps** (modern).

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

## 2. Enable the SuiteTax plug-in

Go to **Customization → Plug-ins → Manage Plug-ins** and confirm **Numeral SuiteTax Engine** is checked.

<Note>
  This checkbox is the integration's kill switch — unchecking it disables Numeral tax calculation NetSuite-wide without uninstalling the bundle.
</Note>

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

<img src="https://mintcdn.com/numeralhq/3yCz09jOh2VOCEJG/images/integrations/netsuite/01-numeral-credentials.png?fit=max&auto=format&n=3yCz09jOh2VOCEJG&q=85&s=2641281bd4cbd9cfbe65cafaec03e2fa" alt="Numeral Credentials record" width="2468" height="478" data-path="images/integrations/netsuite/01-numeral-credentials.png" />

Save the record.

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

<Warning>
  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.
</Warning>

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

<AccordionGroup>
  <Accordion title="Preview Tax returns 'No tax engine available'">
    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.
  </Accordion>

  <Accordion title="NetSuite errors that no Tax Code is found for a state">
    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.
  </Accordion>

  <Accordion title="Tax calculates but doesn't appear in Numeral">
    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.
  </Accordion>

  <Accordion title="API key rotated">
    Open the **Numeral Credentials** custom record and update the **API Key** field. No script redeploy required.
  </Accordion>
</AccordionGroup>