> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/saas-applications/netsuite.md).

# NetSuite

This guide walks you through setting up Token-Based Authentication (TBA) in NetSuite so Harmony can securely read your vendor, contract, and procurement data.

> **What you'll do:** Create a dedicated role with minimal permissions, generate authentication tokens, and collect the 5 values needed to complete the Harmony integration setup.

***

#### 1. Prerequisites - Enable Features

**Navigation:** Setup › Company › Setup Tasks › Enable Features › SuiteCloud tab

Check both:

* ✅ **REST Web Services**
* ✅ **Token-Based Authentication**

Accept the SuiteCloud Terms of Service if prompted. Save.

***

#### 2. Create the Role

**Navigation:** Setup › Users/Roles › Manage Roles › New

**General settings:**

| Field                   | Value                                                                   |
| ----------------------- | ----------------------------------------------------------------------- |
| Name                    | Harmony Integration Role (or any descriptive name)                      |
| Subsidiary Restrictions | All (so the token sees vendors/purchase orders across all subsidiaries) |
| Authentication          | Leave all unchecked (Two-Factor: Not required)                          |

**Permissions - Minimal Required Set**

Add the following permissions to the role. These are the minimum permissions required for Harmony to read your vendor, contract, and procurement data.

*Setup tab:*

| Permission                 | Level | Notes                                                   |
| -------------------------- | ----- | ------------------------------------------------------- |
| Log in using Access Tokens | Full  |                                                         |
| REST Web Services          | Full  |                                                         |
| View Login Audit Trail     | View  | Only required for the **Native App Integration**\* flow |

*Reports tab:*

| Permission              | Level | Why                                         |
| ----------------------- | ----- | ------------------------------------------- |
| SuiteAnalytics Workbook | Edit  | Unlocks SuiteQL query execution             |
| Transaction Detail      | View  | Enables transaction table access in SuiteQL |

*Lists tab:*

| Permission                          | Level | Notes                                                   |
| ----------------------------------- | ----- | ------------------------------------------------------- |
| Contacts                            | View  |                                                         |
| Employees                           | View  |                                                         |
| Employee Record                     | View  | Only required for the **Native App Integration**\* flow |
| Items                               | View  |                                                         |
| System Notes for Analytics and REST | View  |                                                         |
| Vendors                             | View  |                                                         |

*Transactions tab:*

| Permission       | Level |
| ---------------- | ----- |
| Bills            | View  |
| Find Transaction | View  |
| Purchase Order   | View  |

> \* **Native App Integration** is the flow where Harmony surfaces per-user NetSuite activity (last-login, seat usage) alongside vendor and contract data - treating NetSuite itself as a SaaS app in your inventory. It reads employee records and the login audit trail to identify active users. If you only need vendor/contract/spend sync, you can skip these two permissions.

***

#### 3. Assign the Role to a User

**Navigation:** Lists › Employees › Employees (find the user who will own the integration)

We recommend using a dedicated service account rather than a personal employee account, so the integration is not affected if the employee leaves.

1. Open the employee/user record
2. Go to the **Access** subtab
3. In the **Roles** section, click **Add**
4. Select the role you created (e.g. Harmony Integration Role)
5. Save

> **Tip:** If you cannot see the user in the Access Token dropdown later, it means this step was not completed - the role is not assigned to the user, or the role is missing the "Log in using Access Tokens" permission.

***

#### 4. Create the Integration Record

**Navigation:** Setup › Integration › Manage Integrations › New

| Field                      | Value                                         |
| -------------------------- | --------------------------------------------- |
| Name                       | Harmony Integration (or any descriptive name) |
| State                      | Enabled                                       |
| Token-based Authentication | ✅ Checked                                     |
| TBA: issuetoken Endpoint   | ⬜ Unchecked                                   |
| TBA: Authorization Flow    | ⬜ Unchecked                                   |
| OAuth 2.0 section          | Leave all unchecked                           |

Click **Save**.

> ⚠️ **IMMEDIATELY** copy the two values shown - they appear **only once** and cannot be retrieved later:
>
> * **Consumer Key**
> * **Consumer Secret**
>
> These may be labeled as *Client ID* and *Client Secret* in other documentation.

***

#### 5. Create the Access Token

**Navigation:** Setup › Users/Roles › Access Tokens › New

| Field            | Value                                  |
| ---------------- | -------------------------------------- |
| Application Name | Select your integration record         |
| User             | Select the user with the role assigned |
| Role             | Select the role you created            |

Click **Save**.

> ⚠️ **IMMEDIATELY** copy the two values - shown **only once**:
>
> * **Token ID**
> * **Token Secret**

***

#### 6. The 5 Values You Need

Once you have completed the steps above, enter these 5 values in the Harmony integration setup screen to complete the connection:

| # | Value               | Where to find it                                                                       |
| - | ------------------- | -------------------------------------------------------------------------------------- |
| 1 | **Account ID**      | Setup › Company › Company Information (format: `1234567` or `1234567_SB1` for sandbox) |
| 2 | **Consumer Key**    | From Step 4 (Integration Record save)                                                  |
| 3 | **Consumer Secret** | From Step 4 (Integration Record save)                                                  |
| 4 | **Token ID**        | From Step 5 (Access Token save)                                                        |
| 5 | **Token Secret**    | From Step 5 (Access Token save)                                                        |

> **Note:** When you open the NetSuite integration setup form in Harmony, a "For more details, visit our documentation" link at the top of the form brings you directly back to this guide if you need a reference while filling in your credentials.

***

#### 7. Choose Which Transaction Types to Sync

After entering your credentials, you can control which NetSuite transaction types Harmony pulls in as part of your contracts integration. Two toggles are available in your NetSuite integration settings:

| Toggle                   | Default                   | When to use it                                                                                             |
| ------------------------ | ------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Sync Purchase Orders** | On (enabled by default)   | Standard purchasing workflow - most organizations use this                                                 |
| **Sync Vendor Bills**    | Off (disabled by default) | Enable this if your team books vendor contracts directly as Vendor Bills with no associated Purchase Order |

Both toggles can be enabled at the same time if your organization records spend through both transaction types. Existing NetSuite tenants retain their current behavior - Sync Purchase Orders remains on and Sync Vendor Bills remains off unless you explicitly enable it.

***

#### 8. Optional (Strongly Recommended) - Service Start / End Date Columns

NetSuite does not have a single, standard "contract start date" or "contract end date" field. Instead, most customers track the service period on **transaction lines** (the individual lines of a Bill or Purchase Order) using **custom transaction column fields**

* typically named something like `custcol_service_start_date` and `custcol_service_end_date`.

Harmony uses these two columns to populate the **contract start date** and **contract end date** for each vendor contract it derives from your NetSuite data. Without them, those fields will be left `NULL` in Harmony, which significantly reduces the value of renewal tracking, expiring-contract alerts, and spend-by-period reporting.

> ✅ **We strongly recommend providing these two column IDs.** If your organization tracks service periods on transaction lines under different field names, use those instead - the important thing is that the field is a **transaction line column** holding a **date**.

**8.1 Supported column types**

The `service_start_date_column` and `service_end_date_column` fields accept either of the following:

* **A custom column ID** - any `custcol_*` field of type Date that your organization uses to record service periods (e.g. `custcol_service_start_date`).
* **A NetSuite native amortization column** - if your organization uses NetSuite's built-in amortization schedule instead of custom fields, you can enter one of these two reserved values:

| Value                 | What it maps to                                  |
| --------------------- | ------------------------------------------------ |
| `amortizstartdate`    | NetSuite's native amortization start date column |
| `amortizationenddate` | NetSuite's native amortization end date column   |

This is an explicit, per-credential choice. There is no automatic fallback - Harmony uses exactly the column ID you provide.

**8.2 Where these fields live in NetSuite**

* **Transaction Line Fields** (a.k.a. transaction column fields) - custom fields that appear on each line of a transaction (Bill, Purchase Order, Invoice, etc.), not on the transaction header.
* Their **internal ID** is what Harmony needs. Internal IDs almost always start with the prefix `custcol_` (for example `custcol_service_start_date`).

**8.3 How to find the exact column IDs**

**Option A - Browse the Transaction Line Fields list (recommended)**

1. In NetSuite, go to **Customization › Lists, Records, & Fields › Transaction Line Fields**.
2. In the list, look for fields whose **Label** describes a service period, contract period, subscription term, or similar - common names include:
   * *Service Start Date* / *Service End Date*
   * *Contract Start* / *Contract End*
   * *Coverage Start* / *Coverage End*
   * *Subscription Start* / *Subscription End*
3. Confirm the **Type** column shows **Date** (not Free-Form Text, List/Record, etc.).
4. Copy the value from the **ID** column - this is the internal ID you enter in Harmony (for example `custcol_service_start_date`). If the ID column is not visible, click the field name to open it - the ID is shown at the top of the record.

**Option B - Inspect a real transaction**

If you're not sure which custom fields your organization actually populates, open a representative Bill or Purchase Order that has the service period filled in:

1. Open the transaction and go to the **Items** subtab (line items).
2. Click a line to edit it, or expand the line detail.
3. Hover the label of the start-date / end-date field - most browsers will show the underlying field ID in a tooltip. You can also right-click and choose **Inspect** - the field's HTML `id` attribute contains the internal ID (look for `custcol_<something>`).

**Option C - Ask your NetSuite administrator**

If you don't have permission to access **Customization**, your NetSuite admin can tell you the internal IDs of the service-period fields your organization uses.

**8.4 Enter the IDs in Harmony**

Paste the internal IDs (including the `custcol_` prefix, or the native amortization column name) into the last two fields of the Harmony NetSuite setup screen:

| Field                         | Example values                                      |
| ----------------------------- | --------------------------------------------------- |
| **Service start date column** | `custcol_service_start_date` or `amortizstartdate`  |
| **Service end date column**   | `custcol_service_end_date` or `amortizationenddate` |

Leave either field blank to skip it - the corresponding contract date will remain `NULL` in Harmony.

> ⚠️ **Common pitfalls**
>
> * The value must be the **internal ID** (e.g. `custcol_service_start_date`), **not** the display label ("Service Start Date") - unless you are using one of the two native amortization column names listed above.
> * Custom fields must be **Transaction Line Fields**, not Transaction Body Fields or Item Fields.
> * Custom fields must be of type **Date**. Free-form text fields containing dates as strings are not supported.
> * The role you created in Step 2 must have **View** access to the transactions (Bills, Purchase Orders) whose lines carry these fields - the minimal permissions listed above already cover this.
> * Harmony validates your configured column IDs against your NetSuite instance at connection time. If a column ID contains a typo, references a non-date field, or points to the wrong table, you will receive a clear error message immediately so you can correct it before your first sync runs.

***

#### 9. Native App Integration - User and License Insights

In addition to contract and spend sync, you can connect NetSuite as a **native application integration** in Harmony. This gives IT admins direct visibility into NetSuite user activity, roles, and license utilization from the Applications page - treating NetSuite itself as a managed SaaS app in your inventory.

Once connected, Harmony syncs your NetSuite data daily, with a manual refresh option available. The same Token-Based Authentication credentials used for contract sync power this integration.

**What Harmony surfaces:**

* **User inventory** - active employees synced with name, email, role, status, and license class (Full User, Employee Center, Retail User, External Center, and others)
* **Last activity** - last login date per user, derived from the NetSuite login audit trail
* **License utilization** - a breakdown of license slots in use versus available, helping you identify unused or over-provisioned licenses
* **Role visibility** - the NetSuite roles assigned to each user, useful for access reviews and offboarding checks

To enable this flow, make sure the role you created in Step 2 includes the two additional permissions noted in that section:

* **View Login Audit Trail** (Setup tab) - required to read last-login data
* **Employee Record** (Lists tab) - required to read employee details


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.harmony.io/integrations/saas-applications/netsuite.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.