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

# NetSuite (SOAP)

> Sync business-critical data from your data warehouse to Netsuite with Hightouch

> [!NOTE]
>
> Netsuite is a [premium destination](https://docs.hightouch.com/pricing/ss-pricing.md#premium-destinations) and is only available on [Business tier plans](https://hightouch.com/pricing).

> [!TIP]
>
> Check out our
> [playbook](https://hightouch.com/playbooks/automating-usage-based-billing) and
> [blog post](https://hightouch.com/blog/automated-billing) to learn how to
> automate usage-based billing to streamline your finance operations.

## Supported syncing

| Type | Description | Supported Sync Modes | API Reference |
| - | - | - | - |
| [**Entities**](#syncing-entities) | Sync data from any source to entities in NetSuite, for example, Customers, Invoices, Sales Orders, and Journal Entries | Upsert, Update, Insert | [Browse entity schemas ↗](https://system.netsuite.com/help/helpcenter/en_US/srbrowser/Browser2026_1/schema/record/account.html) |

For more information about sync modes, refer to the [sync modes](https://docs.hightouch.com/syncs/types-and-modes.md#sync-modes) docs.

## REST vs SOAP

The Hightouch NetSuite REST destination offers a few advantages over the SOAP destination:

* The NetSuite REST API uses JSON for web service requests and responses, which is easier to read and debug in the [live debugger](https://docs.hightouch.com/syncs/debugger.md) compared to XML.
* Hightouch prioritizes supporting the latest REST API features and versions.
* The [NetSuite REST](https://docs.hightouch.com/destinations/netsuite-rest.md#field-mapping) destination supports the [inline mapper](https://docs.hightouch.com/syncs/mapping-data.md#inline-mapping) to build objects and arrays

Unless you have a particular entity that's only supported by the SOAP API, we recommend using the REST NetSuite destination.

## Setup in NetSuite

Before you can use Hightouch to sync data to NetSuite, you need to create and and configure a NetSuite integration. Then, to grant access to Hightouch to synchronize data between your source and NetSuite, you need to create a role, a user, and an authentication token for the integration.

> [!NOTE]
>
> Depending on your NetSuite account's setup, you may need an **admin** role to
> complete setup in NetSuite. Netsuite permission changes to a role or user
> don't occur immediately. These changes can take a few minutes or hours to go
> into effect.

### Create an integration

1. Go to **Setup → Integration → Manage Integrations** or use the global search to find and go to the **Manage Integrations** page.

![Global search in NetSuite](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-netsuite-manage-integrations.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=8b16230df5d298f0613f5aa382853419)

This page shows a list of enabled integrations for your account.

![Integrations page in NetSuite](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-netsuite-integrations-page.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=5a639e41072ed1c43e01f352697342fe)

2. Click **New** to create a new integration with the following properties:

* A **Name** that can easily be associated with Hightouch, for example, "Hightouch Integration"
* Set **State** to **Enabled**
* Check **Token-Based Authentication**
* Uncheck **TBA:Authorization flow**
* Uncheck **Authorization Code Grant**
* Leave other authentication options unchanged.

![Integration creation in NetSuite](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-netsuite-new-integration.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=6f5f6b9c55ffa7510ad46ee0531e1ccd)

3. Scroll to the bottom of the page and click **Save**.
4. Scroll to **Client credentials** and Copy and store the **Consumer Key / Client ID** and **Consumer Secret / Client secret** in a secure location. You'll need them to connect to Hightouch.

![Integration credentials in NetSuite](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-netsuite-integration-credentials.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=1ddf12716f0bc0110e4f6782656a88ba)

### Create a role

1. Go to **Setup → Users/Roles → Manage Roles** and click **New** or use the global search to find and go to the **New Role** page.

![Global search in NetSuite](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-netsuite-new-role.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=e5f2046eb8d5522bd343921e4bdb1bee)

2. Create a role with the following properites:

* A descriptive **Name**, for example, "Hightouch Role."
* Check **Do not restrict employee fields**
* For multi-subsidiary NetSuite users, check **All** under **Accessible subsidiaries**
* Under **Authentication**, check **Web Services only Role**.

![New role in NetSuite](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-netsuite-new-role-2.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=28e94e05aa7fe03404c57e5801d8b165)

3. Add the following permissions under **Permissions → Setup**
   * Access Token Management: Full
   * Custom Body Fields: Full
   * Custom Column Fields: Full
   * Custom Entity Fields: Full
   * Custom Fields: Full
   * Custom Item Fields: Full
   * SOAP Web Services: Full
   * User Access Tokens: Full

![Role permissions](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-netsuite-role-permissions.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=9da92e161fe44ee4abbe5160a445d998)

4. Under **Permissions → Lists** and **Permissions → Transactions**, provide **Full** permissions for the NetSuite entities you plan on syncing to. For example, if you want to update sales orders, you need to go to the **Transactions** tab and select **Sales Order** from the list. If you want to update accounts, you need to go to **Lists** and select **Accounts** from the list.

![Role permissions](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-netsuite-accounts-permissions.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=17ad2884a68359d5c2dccd05ae160daf)

### Create a user

Now you can create a new user that uses this role.

1. Go to the **Manage Users** page. Create a new user or select the user you will be using Hightouch with.
2. For new users: fill the **Employee** form with all required fields.
3. On the **Access** tab, check **Manually assign or change password** and assign a secure password.
4. Under **Roles** Assign the role, for example, "Hightouch Role," you previously created.
5. Click **Save**.

![New user](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-netsuite-new-user.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=9c2a0276a72bdf6dcbab9538ca962ca6)

### Create an access token

1. Go to the **Setup → Users/Roles → Access Tokens** page, or use the global search to find it.
2. Click **New Access Token**.

![New access token](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-netsuite-new-access-token.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=0d9a08495ac1629bfd44a1dfefa8cf63)

3. Select the integration, user, and role you previously configured.

![New access token](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-netsuite-new-access-token-2.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=b74d8df493e571ae895ab304a8e540cd)

4. When you click **Save**, NetSuite displays a **Token ID** and a **Token Secret**. Copy and store them in a secure location. You'll need them to connect to Hightouch.

![New access token](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-netsuite-new-access-token-3.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=e3581996f678b2ecf5d3c2b9aee70c7f)

### Enable SOAP web services

Finally, go to **Setup → Company → Enable Features → SuiteCloud → SuiteTalk (Web Services)** and enable **SOAP Web Services**. Once you check this box, NetSuite prompts you to agree to terms of service.

On the same page, under **Manage Authentication**, enable **Token Based Authentication**. It should look similar to the screenshot below.

![Enable SOAP Web services and Token-based authentication](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-netsuite-soap-webservices.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=a78ade37f63f1290af0659a58f74e233)

## Connect to NetSuite

You're now ready to create a NetSuite destination in Hightouch. Go to the [**Destinations** overview page](https://app.hightouch.com/destinations?from=docs) and click the **Add destination** button. Select **NetSuite** and click **Continue**.

You can then authenticate Hightouch to NetSuite by entering the following required fields into Hightouch:

* **Account ID**: You can find this on your **Company information** page in NetSuite.
* **Consumer Key**: From your new integration
* **Consumer Secret**: From your new integration
* **Token Key**: From your new access token
* **Token Secret**: From your new access token

If your account is a Sandbox account, you need to include the suffix `_SB<number>` as part of the **Account ID**:

* `SB` should be in uppercase.
* The Sandbox suffix should be included with an underscore (`_`).

For example, if the Account ID in your sandbox is `1234567-sb1`, then you need to set your Account ID as `1234567_SB1` in your sync configuration.

## Sync configuration

Once you've set up your NetSuite destination and have a [model](https://docs.hightouch.com/getting-started/concepts.md#models) to pull data from, you can set up your sync configuration to begin syncing data. Go to the [**Syncs** overview page](https://app.hightouch.com/syncs?from=docs) and click the **Add sync** button to begin. Then, select the relevant model and the NetSuite destination you want to sync to.

### Syncing entities

The Hightouch NetSuite destination allows you to sync data to supported NetSuite entities, for example, customers, invoices, vendors, etc. Hightouch also supports syncing custom records types—all custom records are part of the
**CustomRecords** namespace.

The specific entities you can sync to depend on your NetSuite implementation. You can view your available entities in the dropdown. Because of the large catalog size, it's best to search for the entities you're interested in.

![Available entities in the Hightouch UI](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-netsuite-soap-available-entities.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=8685d07d003cab5585df6f4388b68533)

#### Related records

If you like, you can choose to initialize the entity with a related record. For example, an invoice can be created from a sales order. If you enable this, you then need to select the base record.

![Related records in the Hightouch UI](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-netsuite-soap-related-records.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=47a1fbbaf22028fb3c38c3617c807c1a)

#### Record matching

To match source rows to entities in Netsuite, you need to select a source column and corresponding Netsuite field.
Depending on the sync mode you select, you can match on the following Netsuite fields:

* **External ID**
* **Internal ID**

**Update** mode supports both, whereas **Upsert** mode only supports **External ID**.

![Record matching in the Hightouch UI](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-netsuite-soap-record-matching.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=86aa3ac6a6c787785f0b38540cbdcc70)

Refer to the [record matching docs](https://docs.hightouch.com/syncs/record-matching.md) for more information.

> [!NOTE]
>
> In **Insert** mode, NetSuite automatically generates an identifier for every
> new record synced, so there is no need to match an existing record.

#### Field mapping

You can sync columns from your model to NetSuite default and custom fields.

Mappings mirror the NetSuite SOAP schema.
That means some of your model columns might need to be JSON objects.

NetSuite generally expects JSON objects when an entity references another entity. For example, in an [invoice](https://system.netsuite.com/help/helpcenter/en_US/srbrowser/Browser2026_1/schema/record/invoice.html), the `entity` field can reference a customer, partner, vendor, employee, contact, etc. by their ID. If you select a numerical model column with external or internal IDs, Hightouch automatically converts this to the JSON object NetSuite expects.

![Field mapping in Hightouch](https://mintcdn.com/hightouch-3c037897/L_vQfA0JQEpeGUUo/images/destinations/destination-netsuite-soap-reference-id.png?fit=max\&auto=format\&n=L_vQfA0JQEpeGUUo\&q=85\&s=ac17c3db4902cd35d60c6c3a170ddb04)

For other JSON objects, such as nested objects or arrays, you need to ensure your model columns match NetSuite's schema expectations.

> [!TIP]
>
> The [NetSuite REST](https://docs.hightouch.com/destinations/netsuite-rest.md#field-mapping) destination
> supports the [inline mapper](https://docs.hightouch.com/syncs/mapping-data.md#inline-mapping), which can
> help you build objects and arrays.

NetSuite arrays are often wrapped in a JSON object.
For example, an invoice supports an `item` field that expects an array of items:

```json theme={null}
{
  "items": [
    { "item": { "id": "8" }, "line": 1, "amount": 1, "price": { "id": "-1" } }
  ]
}
```

To see the schema that NetSuite expects for different entities's fields, go to the [SOAP browser](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N3639052.html).

#### Delete behavior

The [delete behavior](https://docs.hightouch.com/syncs/overview.md#delete-behavior) you select dictates what to do when a row no longer appears in your model's query results. You have the following options:

| Behavior | Description |
| - | - |
| **Do nothing** | Keep the record in NetSuite with all its synced fields |
| **Delete** | Delete the synced record from your NetSuite instance |

## Tips and troubleshooting

To see the exact API requests and responses from each sync run, use the [live debugger](https://docs.hightouch.com/syncs/debugger.md). To get notified by Slack, PagerDuty, SMS, or email when a sync fails, set up [sync alerts](https://docs.hightouch.com/syncs/alerting.md). If you run into an issue this page doesn't cover, [contact support](#pylon-chat).

> [!NOTE]
>
> For Hightouch platform error codes related to destinations, see [Error
> codes](https://docs.hightouch.com/developer-tools/error-codes.md#other-destinations).

### Validate your setup

After your first sync completes, verify the results in NetSuite:

1. Search for the synced record in NetSuite using the identifier you mapped (External ID or Internal ID).
2. Confirm the mapped fields contain the expected values.
3. For nested fields (address books, line items), verify the JSON structure rendered correctly in NetSuite's record view.
4. If the sync shows errors, check the sync run log in Hightouch for specific SOAP or REST API error messages.

### Constructing nested JSON objects in SQL

Many NetSuite fields require nested JSON objects — for example, addresses, line items, or sublists. If your warehouse stores these values in flat columns, you can use SQL JSON functions to build the required structure in your model.

The following PostgreSQL example constructs a nested address book entry:

```sql theme={null}
SELECT
  external_id,
  json_build_object(
    'addressbookAddress',
    json_build_object(
      'addr1', street,
      'city', city,
      'state', state,
      'zip', zip,
      'country', country_code
    ),
    'defaultShipping', true,
    'defaultBilling', false
  ) AS addressbook_entry
FROM customers
```

To build an array of nested objects (for example, multiple address book entries), wrap individual objects with `json_agg`:

```sql theme={null}
SELECT
  external_id,
  json_build_object(
    'addressbook',
    json_agg(
      json_build_object(
        'addressbookAddress',
        json_build_object('addr1', street, 'city', city, 'state', state, 'zip', zip),
        'defaultShipping', is_default_shipping
      )
    )
  ) AS addressbook
FROM customer_addresses
GROUP BY external_id
```

For Snowflake, use `OBJECT_CONSTRUCT` and `ARRAY_AGG` instead. For BigQuery, use `TO_JSON` with `STRUCT` and `ARRAY_AGG`.

Cast the resulting column to **Object/Array** in your model. Check the [NetSuite SOAP browser](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_N3639052.html) for the exact schema each entity expects.