> ## Documentation Index
> Fetch the complete documentation index at: https://zenskar.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# NetSuite

NetSuite is an accounting ERP. The connection is one way, from Zenskar to NetSuite only. A connection binds to exactly one NetSuite subsidiary. An organization with multiple subsidiaries needs one connection per subsidiary.

## Prerequisites

Zenskar uses token-based authentication (TBA) to connect to a NetSuite account. Enable a few features in NetSuite before you connect Zenskar to NetSuite.

### Enable features

1. On the NetSuite dashboard, go to **Setup > Company > Enable Features**.
2. On the horizontal menu, go to **SuiteCloud**. Go to the **SuiteTalk (Web Services)** subsection. Select **REST WEB SERVICES**. See NetSuite's [Prerequisites and Setup for REST Web Services](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_5085602973.html).
3. Go to the **Manage Authentication** subsection. Select **TOKEN-BASED AUTHENTICATION**.
4. Save the changes.

### Create an integration record

1. Create a new integration to handle all requests from Zenskar. To create it, go to **Setup > Integration > Manage Integrations > New**. See NetSuite's [Creating an Integration Record](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_4393879073.html).
2. Give the integration a name. Leave its state as Enabled. Enable **Token-Based Authentication** on it.
3. Save the integration. NetSuite displays the **Consumer Key** and **Consumer Secret** once, at creation time. Copy both immediately.

> [!NOTE]
>
> NetSuite only shows the Consumer Secret and Token Secret at creation time. If either is lost, re-issue the integration or the token rather than searching for it.

### Grant permissions

Before you issue an access token, confirm the user's role has Web Services access. Also confirm the role has the permissions below. See NetSuite's [Roles and Permission Considerations for APIs](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_0320025211.html).

Grant the role used for this connection the following permissions:

| Area | Permission | Level |
| :- | :- | :- |
| Transactions | Invoice, Credit Memo, Customer Payment, Customer Refund, Make Journal Entry | Full |
| Transactions | Find Transaction | View |
| Lists | Tax Records, Customers, Items | Full |
| Lists | Accounts, Tax Schedules, Vendors, Currency, Subsidiaries | View |
| Setup | User Access Tokens | Full |

> [!NOTE]
>
> Set Accounts to Full only if Zenskar should auto-create ledger accounts during journal entry sync. Otherwise View is enough.

### Issue an access token

1. From the NetSuite homepage, go to **Settings > Manage Access Tokens**. Choose the integration you created, the user, and a token name. NetSuite displays the **Token ID** and **Token Secret** once. Copy both immediately. See NetSuite's [User Access Token, Create a TBA Token](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/bridgehead_4254083671.html).
2. Note the **Account ID** and **Company URL**, both under **Setup > Company > Company Information**. The Company URL is under the **Company URLs** subtab. Use the entry for **SUITETALK (SOAP AND REST WEB SERVICES)**.

## Connect NetSuite

1. Go to **More > Integrations > ERP**, find the **NetSuite** card, and click **Connect**.

   ![Integrations page, ERP category, NetSuite card with the Connect button](https://assets.zenskar.com/20240301/erps-netsuite-connector-card.png)

2. On the NetSuite page, click **Connect to NetSuite**.

   ![NetSuite overview page in Zenskar, with the Connect to NetSuite button](https://assets.zenskar.com/20240301/erps-netsuite-connector-overview.png)

3. In the dialog, enter the six values gathered in Prerequisites. Click **Connect**:

   | Field | Where it comes from |
   | :- | :- |
   | **Account ID** | Setup > Company > Company Information |
   | **Company URL** | Same page, Company URLs subtab, the SuiteTalk (SOAP and REST Web Services) entry |
   | **Consumer Key** | The integration record created in Prerequisites |
   | **Consumer Secret** | The integration record created in Prerequisites |
   | **Token ID** | The access token created in Prerequisites |
   | **Token Secret** | The access token created in Prerequisites |

   ![Connect dialog with the six credential fields](https://assets.zenskar.com/20240301/erps-netsuite-connect-form.png)

   Zenskar sends a live request to NetSuite using these values. NetSuite can reject this request for several reasons, including a Company URL whose account ID does not match the Account ID field. Zenskar does not distinguish between these causes. The connection fails with the same generic error regardless of the cause.

   > [!WARNING]
   >
   > Zenskar does not check beforehand that the Company URL's account ID matches the Account ID field. A mismatch still fails the connection. NetSuite returns the same generic rejection, not a specific error naming the mismatch. Double-check this match yourself before you connect. This check matters most for a sandbox account ID, such as `1234567_SB1`. In the URL, this account ID becomes `1234567-sb1.suitetalk.api.netsuite.com`.

4. Zenskar redirects you to the **Configuration** screen.

## Configure the connection

1. Under **Entity Sync Mapping**, select the subsidiary from the **NetSuite Entity** dropdown. Map it to the corresponding **Zenskar Entity**. Both fields are required.

   > [!WARNING]
   >
   > This mapping cannot be changed once saved. To point the connection at a different subsidiary or entity, delete the connection. Then create a new one.

2. Under **Data Sync Setup**, choose a sync mode. Only one mode can be active per connection:

   | Mode | What it does |
   | :- | :- |
   | **Object Sync** | Syncs Customers, Invoices, Payments, and Credit Notes directly with NetSuite. Journal entries are left to NetSuite's own accounting. |
   | **Journal Entries Sync** | Syncs Customers. Also pushes journal entries, for example revenue recognition postings, directly to NetSuite. Use this instead of syncing individual objects. |

   > [!NOTE]
   >
   > Switching from one mode to the other clears the configuration already set under the mode you are leaving.

### If you choose Object Sync

![Object Sync selected, with Customers, Invoices, Credit Notes, and Payments modules configured](https://assets.zenskar.com/20240301/erps-netsuite-object-sync.png)

#### Customers

Turn on **Customers**. Then choose a **Sync Direction**.

Below Sync Direction, a **Duplicate Customer Check** card appears. Before exporting a customer, Zenskar matches it against the selected field to find an existing NetSuite record. This avoids creating duplicate customers. This matching is always on. You cannot disable it. The connector always applies a default match field, even if you do not pick one.

Pick a field from **Match By > Select Field**. Zenskar pre-fills this with your saved choice. If you have no saved choice, it uses NetSuite's default match field, Email. If Email is unavailable, it uses the first available option. If you leave this field untouched, Zenskar still relies on NetSuite's default behavior.

> [!NOTE]
>
> If you select Email as the match field, deduplication automatically falls back to matching by customer name for any customer without an email address.

#### Invoices

Turn on **Invoices**. Choose a **Sync Direction**. Configure the invoice field mapping:

| Setting | What it does |
| :- | :- |
| **Sales Account for Invoices** | Required. No default value. |
| **Discount Account for Invoices** | Required. No default value. |
| **Tax Schedule** | Applied to products Zenskar creates in NetSuite for invoice line items. Required whenever the dropdown is present. Zenskar blocks saving until you select one. |
| **Sync invoice note** | When enabled, the invoice note is written to NetSuite's invoice note. If empty, the invoice number is used instead. |

> [!NOTE]
>
> Zenskar does not restrict these fields to a particular NetSuite account type. Any active account for the subsidiary is selectable. As general guidance, map **Sales Account for Invoices** to an Income account, and **Discount Account for Invoices** to an Income or contra-revenue account used for discounts. Confirm the right type with your NetSuite administrator.

> [!NOTE]
>
> The Tax Schedule dropdown only appears for connectors whose Zenskar integration supports tax schedules. Zenskar shows a loading state while it fetches the available schedules from NetSuite. If NetSuite has no tax schedules configured, Zenskar asks you to create one in NetSuite and refresh the page. If the fetch fails, Zenskar shows an error with an option to retry. If NetSuite later removes a previously selected schedule, Zenskar clears the saved selection. Zenskar then prompts you to re-select one.

Two separate tax mapping sections also appear under Invoices. You can use both together:

| Section | What it does |
| :- | :- |
| **Tax Code Mappings** | Map a Zenskar tax code to a NetSuite tax type. The Zenskar side is a typed key, for example `GST_10`. You also enter its rate. The NetSuite side is a dropdown of the account's active tax types. Use this for a bounded, stable tax model. |
| **Nexus Mappings** | Map a jurisdiction to a NetSuite Nexus, Tax Type, and Tax Agency. A jurisdiction is defined by country, region (US or Canada only), and tax type. Choose each NetSuite value from a live dropdown. Zenskar builds the matching tax item automatically at sync time. Use this when an upstream engine, for example Avalara, computes tax. The jurisdiction set is dynamic in that case, so you cannot map it by hand. |

> [!WARNING]
>
> In Nexus Mappings, every jurisdiction that appears on an invoice must have a mapping. A missing mapping fails the sync. The error names exactly what to add.

Under **Custom fields**, map Zenskar values into NetSuite custom fields. A separate card appears per NetSuite record type: Customer, Invoice body, Line items, and Contract. Click **Add Custom Field**. Search for and select a NetSuite custom field. Then configure:

| Field | What it does |
| :- | :- |
| **Source value** | Where this field's value comes from in Zenskar. |
| **Attribute key** | Shown only when the source is a custom attribute. Links to a specific Zenskar custom attribute. |
| **Default value** | A static fallback used when the source resolves empty. |
| **Required for sync** | When on, the sync fails if the source resolves empty. Zenskar does not fall back to another value. |
| **Match by column** | Shown for fields backed by a NetSuite list, such as Location, Department, or Class. Picks the NetSuite column used to match this value. |

> [!NOTE]
>
> NetSuite segments like Location, Department, and Class are configured as ordinary custom fields. There is no separate section for them. Custom fields are available today at the invoice header level. Line-level custom fields are not yet available.

#### Credit Notes

Turn on **Credit Notes**. Choose a **Sync Direction**. Map a **Sales Account for Credit Notes**. This account is required. Credit notes must carry line items. A lump-sum credit note is rejected.

> [!NOTE]
>
> Map **Sales Account for Credit Notes** to the same account, or the same account type, as **Sales Account for Invoices**. NetSuite does not enforce this, but a mismatch can misstate revenue in your reports.

#### Payments

Turn on **Payments**. Then turn on **Export Payments**. At least one payment source must be enabled. Otherwise, Zenskar blocks saving:

| Source | Account mapping |
| :- | :- |
| **Bank Payments** | Payment Account, required. |
| **Stripe Payments** | Payment Account and Processing Fees Account, both required. A Payout Configuration account is optional. |

### If you choose Journal Entries Sync

![Journal Entries Sync selected, with Journal Accounts Mapping showing Zenskar accounts mapped to NetSuite accounts](https://assets.zenskar.com/20240301/erps-netsuite-journal-entries-sync.png)

Turn on **Journal Entries**. Choose a **Sync Direction**. Map each account under **Journal Accounts Mapping** to a NetSuite account. NetSuite filters the account options to the connection's subsidiary.

> [!NOTE]
>
> The accounts listed on the Zenskar side come from your own **Settings > Accounting > Chart of Accounts**. They do not come from NetSuite. Add, rename, or remove an account there to change what appears here. None of these have a default NetSuite account mapped to them.

> [!NOTE]
>
> If a journal entry line references a NetSuite account that does not exist yet, Zenskar can create it automatically. Zenskar only creates accounts within a fixed set of types that NetSuite allows, for example Bank, Income, Expense, Deferred Revenue, Accounts Receivable, and Accounts Payable. The connector enforces this restriction. Zenskar has no setting to view or change the allowed types.

Click **Save Configuration**. The connection shows as **Configured** on the NetSuite **Connections** tab.

![NetSuite Connections tab showing the Account ID, Connected Entity, and Configured status](https://assets.zenskar.com/20240301/erps-netsuite-connection-configured.png)

## Features

| Feature | What it does |
| :- | :- |
| **Invoices and journal entries are de-duplicated** | Re-syncing the same invoice or journal entry updates the existing NetSuite record instead of creating a duplicate. |
| **Payments and refunds are not de-duplicated** | Re-syncing the same payment or refund can create a second record in NetSuite. Trigger each one only once. |
| **Product and item mapping** | Zenskar reuses a mapped NetSuite item for a product if one exists. Otherwise it creates one. Items are matched by mapping, never by name. |
| **Discounts post as their own line** | Zenskar adds a discount or entitlement credit to the invoice as a separate line, using a discount item. It does not reduce another line's amount. |

## Reference

### Known limitations

* A journal entry referencing a missing NetSuite account can only auto-create that account if its type is in NetSuite's allowed set. Any other account type must already exist in NetSuite.
* A credit note syncs to NetSuite as a Credit Memo. It must carry line items. A lump-sum credit note is rejected.
* Payments and refunds are not de-duplicated. Re-running a payment or refund sync can create a duplicate record in NetSuite.
* A customer's transacting currency must already be enabled on the NetSuite customer record. Otherwise, invoice creation fails.
* NetSuite has no standalone address or contact record. Address and contact details are embedded on the customer only.
* Line-level custom fields are not available. Custom field mapping applies at the invoice header level only.
* By default, Zenskar writes NetSuite's system Transaction ID as the invoice number. To write the human-facing Document Number instead, enable NetSuite's "Allow Override" setting for auto-generated numbers. Without this setting, the sync is rejected.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.