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

# NetSuite

> Learn how to push your invoicing data in your accounting tool

[NetSuite](https://www.netsuite.com) is Oracle's cloud-based ERP and accounting software, with multi-subsidiary (OneWorld) support.

## Prerequisites

You need a [NetSuite account](https://www.netsuite.com) with the **SuiteTalk REST Web Services** and **Token-Based Authentication** features enabled, and admin rights on Hyperline.

You also need to create a NetSuite **Integration record** with `Token-Based Authentication` enabled, and issue an **access token** for the user/role used by Hyperline. The role must have permissions on customers, invoices, credit memos, customer payments, items, accounts, tax items, subsidiaries, and SuiteQL (REST Web Services + Log in using Access Tokens).

### Enable Token-Based Authentication

In NetSuite, go to **Setup > Company > Enable Features > SuiteCloud** and enable:

* **Token-Based Authentication**
* **SuiteTalk (REST Web Services)** — if not already enabled

### Create an Integration record

This generates the **Consumer Key** and **Consumer Secret** used by Hyperline.

In NetSuite, go to **Setup > Integrations > Manage Integrations > New** and fill:

* **Name**: e.g. `Hyperline`
* **State**: `Enabled`
* Enable **Token-Based Authentication**

Save the record. NetSuite displays the **Consumer Key** and **Consumer Secret** only once — copy both values immediately and store them securely.

### Generate an access token

This generates the **Token ID** and **Token Secret** used by Hyperline.

In NetSuite, go to **Setup > Users/Roles > Access Tokens > New** and choose:

* **Application Name**: the integration record created above
* **User**: the NetSuite user dedicated to Hyperline
* **Role**: the role granted to that user (with the permissions listed above)

Save the record. NetSuite displays the **Token ID** and **Token Secret** only once — copy both values immediately and store them securely.

## Setup

<Steps>
  <Step title="In Hyperline, navigate to the Settings > Integrations page" />

  <Step title="Click Connect on the NetSuite card" />

  <Step title="Enter your Token-Based Authentication credentials">
    Provide the five values issued by NetSuite:

    * **Account ID** (your NetSuite realm, e.g. `1234567` or `1234567_SB1` for sandboxes)
    * **Consumer Key**
    * **Consumer Secret**
    * **Token ID**
    * **Token Secret**

    <Note>
      Hyperline does not use OAuth 2.0. All API calls are signed with OAuth 1.0a (HMAC-SHA256) using your TBA credentials.
    </Note>
  </Step>

  <Step title="Map your invoicing entities to NetSuite subsidiaries">
    On the **Settings > Integrations > NetSuite** page, link each Hyperline invoicing entity to a NetSuite subsidiary. The subsidiary drives currency, country, and the available accounts/tax codes/items shown in the rest of the configuration.
  </Step>

  <Step title="Configure mappings">
    Map your products, accounting rules, tax codes and any customer or line-item field mappings. See [Mapping](#mapping) below.
  </Step>

  <Step title="That's it!">
    Your Hyperline account is ready to send invoices, credit notes and payments to NetSuite.
  </Step>
</Steps>

## Mapping

### Subsidiaries

NetSuite requires a subsidiary on every customer and transaction. Each Hyperline **invoicing entity** must be mapped to one NetSuite subsidiary on the integration settings page. OneWorld accounts are supported — accounts, items and tax codes are automatically filtered to the selected subsidiary.

### Customers

To link an existing NetSuite customer to a Hyperline customer, open the Hyperline customer page, click **Edit** in the **Integrations** section, and paste the NetSuite customer **internal ID**.

For bulk linking during initial onboarding, contact our support team or use [this API endpoint](../api-reference/endpoints/customers/bulk-update-providerscustomers-mapping.mdx).

If a Hyperline customer is not linked to any NetSuite customer, the behavior depends on the **Customer sync mode** configured in Settings:

* **no synchronization** — the customer must be linked manually before any invoice can be pushed; otherwise the invoice push fails.
* **from Hyperline to NetSuite** — the customer is automatically created in NetSuite the first time it is needed (typically on the first invoice push).

Before creating a new customer in NetSuite, Hyperline looks up the NetSuite **External ID** field for a record matching the Hyperline customer ID, to avoid duplicates.

The following customer fields are pushed to NetSuite: company name, billing email, tax number, subsidiary and the default billing address (line 1, city, zip, state, country).

#### Custom field mappings

Any NetSuite **entity-level custom field** (`fieldtype = ENTITY`) can be mapped from the **Field mappings** section of the integration settings. The source can be either a built-in Hyperline customer field or a [Hyperline custom property](../docs/properties/overview) defined on the customer entity.

For NetSuite fields that reference another record (Location, Department, etc.), the mapped value should be the NetSuite **internal ID** of the referenced record. **Location** fields are an exception: Hyperline automatically resolves a location name to its NetSuite ID, so you can map a custom property containing the location name directly.

### Products (items / SKU)

Every invoice line item must be mapped to a NetSuite item. For each Hyperline product, go to the **Accounting** section of the product page and pick the corresponding NetSuite item from the dedicated selector — Hyperline fetches the list of items directly from your NetSuite account.

<Note>
  Only items of type `Service`, `Non-Inventory Part` and `Inventory Part` are exposed by Hyperline. Inactive items are filtered out.
</Note>

If a line item is missing a product mapping, the invoice push fails with a clear error so you can fix the mapping and retry.

### Accounts (invoice + transaction)

NetSuite requires an **income account** on every invoice line and a **bank/AR account** on customer payments.

* **Per-line invoice account**: resolved through your [accounting rules](../docs/accounting/rules) for each line item. If no rule resolves to an account, the invoice push fails so you can fix the rule and retry — no silent default is applied.
* **Payment account**: resolved through accounting rules. If no rule resolves to an account, the payment push fails so you can fix the rule and retry.
* Non-posting and statistical accounts are filtered out — only postable GL accounts are available for selection.

### Tax codes

Tax codes are configured **at the invoicing entity level** — set up tax codes with automatic computation in the tax settings of the invoicing entity. Tax codes are then resolved according to what is configured in Hyperline and pushed to NetSuite on each line item.

Both `salestaxitem` and `taxgroup` records are exposed, filtered by subsidiary.

### Invoice line item fields

Any NetSuite **column-level custom field** (`fieldtype = COLUMN`) on the invoice line sublist can be mapped from the **Field mappings** section. Two built-in line-item fields are available:

* **Period start** — the start of the line item billing period
* **Period end** — the end of the line item billing period

This is typically used to feed NetSuite's revenue recognition or custom reporting columns.

### Linking back to Hyperline

Hyperline can populate two **opt-in** custom fields with a clickable URL back to the matching record in the Hyperline app. Create either field on the relevant NetSuite record type and Hyperline will fill it on every push — no extra mapping required.

| NetSuite field id          | Record type | Field type     | Value pushed                                  |
| -------------------------- | ----------- | -------------- | --------------------------------------------- |
| `custentity_hyperline_url` | Customer    | Free-Form Text | `https://app.hyperline.co/app/customers/{id}` |
| `custbody_hyperline_url`   | Transaction | Free-Form Text | `https://app.hyperline.co/app/invoices/{id}`  |

If the field doesn't exist on your account, Hyperline simply skips it — no error.

## Synchronization

When you connect your NetSuite account, Hyperline **automatically sends invoices, credit notes, customers and payments** with their complete details.

<Note>
  By default, only data created after the connection date is synced. To push older data, please contact our support team.
</Note>

Synchronization is **one-way: Hyperline → NetSuite**. NetSuite is queried read-only to fetch metadata (subsidiaries, items, accounts, tax codes, custom fields).

### Customer synchronization

Hyperline supports 2 modes for customers:

* **no synchronization**: customers are not automatically created by Hyperline — they must be linked manually before any invoice can be pushed.
* **from Hyperline to NetSuite**: customers created in Hyperline are automatically created in NetSuite with their details. Updates are propagated.

### Invoice and credit note synchronization

Invoices and credit notes are pushed as native NetSuite **Invoice** and **Credit Memo** records. When a credit note is linked to an existing invoice in Hyperline, the NetSuite credit memo is automatically **applied** to that invoice for the corresponding amount.

Updates made to an invoice in Hyperline are propagated to the matching NetSuite record automatically.

### Payment synchronization

Payments use a **per-payment-method sync mode** (card, SEPA / ACH / BACS direct debit, bank transfer, Apple Pay, Google Pay, Stripe Link, external, other). Each can be set independently to:

* **no synchronization**: payments are not synchronized.
* **from Hyperline to NetSuite**: payments settled in Hyperline are pushed as NetSuite Customer Payments and applied to the corresponding invoice.

When a payment is updated or refunded in Hyperline, the existing NetSuite Customer Payment is deleted and recreated to keep both systems consistent.

The synchronization delay is 5 minutes maximum.