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

# NetSuite

## Synchronisation scope

| Synchronisation           | Direction          | When it runs                                                   |
| ------------------------- | ------------------ | -------------------------------------------------------------- |
| Invoices and credit notes | Younium → NetSuite | When an invoice is posted in Younium, with invoice posting on  |
| Journals                  | Younium → NetSuite | On demand, when a posted journal is sent to NetSuite           |
| Accounts                  | NetSuite → Younium | On demand from the integration settings, or as a scheduled job |
| Accounts                  | Younium → NetSuite | On demand from the integration settings, or as a scheduled job |
| Exchange rates            | NetSuite → Younium | On demand from the integration settings, or as a scheduled job |
| Products                  | NetSuite → Younium | On demand from the integration settings                        |

Not in scope: payments.

***

## Overview

The NetSuite integration connects Younium to Oracle NetSuite for customer and product master data, exchange rates, journal export, and outbound sales documents. When **Post invoices** is enabled, Younium creates an invoice or credit memo in NetSuite when an invoice is posted in Younium, then stores NetSuite identifiers on the Younium invoice.

The integration uses OAuth 1.0 token-based authentication against NetSuite SuiteTalk REST (`services/rest/record/v1`). Scheduled jobs import accounts and exchange rates and can export Younium accounts to NetSuite. Journal export is triggered on demand for a selected journal, not on invoice post.

***

## Authentication

NetSuite does not offer an approval flow to click through, so you connect it by entering credentials you create in NetSuite yourself. Two pairs are needed: the consumer key and secret from a NetSuite integration record, and the access token and secret from a token-based access record for the user Younium should act as. You also give your NetSuite account id, which tells Younium which NetSuite account to reach.

When you save, Younium immediately calls NetSuite with those credentials to prove they work. If NetSuite accepts them, they are stored and the integration is connected. If it does not, the previous credentials are left untouched — a failed attempt cannot break a working connection.

The connection stays valid until the tokens are revoked in NetSuite. Nothing expires on a schedule, and there is no periodic reauthorisation for an administrator to perform.

***

## Activation and deactivation

A successful credential check is the activation: there is no separate step to switch the integration on afterwards.

Disconnecting removes the stored credentials and stops invoice posting — posting an invoice in Younium no longer creates one in NetSuite. Documents already sent stay in NetSuite untouched.

***

## Save and setup

When settings are saved:

* Ensures integration custom field **Invoice number** on entity **invoice**.
* Turning **Post invoices** on starts sending invoices to NetSuite as they are posted; turning it off stops them.
* If **Post invoices** toggles off: unsubscribes the same subscription.
* Trims `NetsuiteTaxCategoryFieldName` when set.

### Settings

| Setting                                                  | Description                                                                                                                             | Default           |
| -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| `PostInvoices`                                           | Subscribes to automatic post on `InvoicePosted`                                                                                         | Off until enabled |
| `CompanyUrl`                                             | NetSuite subsidiary internal id on invoice payload (`subsidiary.id`)                                                                    | —                 |
| `LocationId`                                             | NetSuite location id on posted invoices                                                                                                 | —                 |
| `ServicePeriodStart` / `ServicePeriodEnd` / `LineNumber` | Optional NetSuite field names added to each line ExpandoObject when configured and dates present                                        | —                 |
| `MapDimensionListKey`                                    | Journal export: dimension list key mapping                                                                                              | —                 |
| `MapJournalLineEntity`                                   | Journal export: links the invoice's customer to both the debit and credit lines of each journal entry. Lines with no amount are skipped | —                 |
| `MapTaxCategoryName`                                     | Journal export: tax category mapping                                                                                                    | —                 |
| `ExportJournalSummary`                                   | Journal export summary path                                                                                                             | —                 |
| **Use custom service** (`UseCustomService`)              | Exports journals through the custom service URL rather than the standard endpoint                                                       | —                 |
| `NetsuiteTaxCategoryFieldName`                           | Tax category field for journal mapping                                                                                                  | —                 |

***

## Custom fields created by the integration

| Entity  | Custom field name | Type | Notes                                                                 |
| ------- | ----------------- | ---- | --------------------------------------------------------------------- |
| Invoice | `Invoice number`  | Text | Populated with NetSuite `tranId` after successful post; do not rename |

Integration custom mappings (configured in Younium) can extend payloads for entities **invoice**, **invoiceline** and **account**.

***

## Custom field mapping

When configuring a custom field mapping for the invoice, invoice line, customer, or journal entry line record types, the list of available NetSuite fields offered while picking a target is read live from NetSuite for that record type, so it reflects the customer's own NetSuite configuration, including their custom fields.

Building this list can take a while for large record types — NetSuite can take over a minute to return the invoice and invoice line schema. Younium waits up to 150 seconds for a response. If NetSuite does not respond within that time, returns an error, or returns something Younium cannot read as a schema, the person configuring the mapping sees a specific message describing what happened rather than the picker failing without explanation, and can try again. A field name can also be typed in directly at any time, without waiting for the NetSuite field list to load.

### Fields offered for mapping

The field list for the invoice, invoice line and customer record types is filtered so that only fields that can safely be mapped are offered:

* Fields that Younium always controls are not offered: `id`, `customerId`, `entity`, `item`, `subsidiary`, `externalId`, `amount`, `rate`, `quantity` and `addressBook`. A mapping to one of these is ignored if it is typed in directly.
* List (array) fields are not offered, because they cannot hold a single mapped value.
* Reference fields (fields that point to another NetSuite record) are offered only with the properties of the referenced record that Younium can fill: internal ID (`id`), name (`refName`) or external ID (`externalId`). A reference field that exposes none of these is not offered.
* Other fields are offered as plain values.

### Mapping settings

| Setting                      | Description                                                                                                                                                             | Default |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| **Custom field resolved as** | For a Younium custom field, how its value is resolved before it is sent: the list item key for list fields, or the external ERP/CRM ID of the account for entity fields | —       |
| **Reference type**           | For a reference field in NetSuite, which property of the referenced record the mapped value identifies: internal ID, name or external ID. Leave empty for plain values  | —       |

A mapping on the `partner` field with no **Reference type** is sent as an internal ID reference. For the customer record type, a mapping to a reference field with no **Reference type** is sent as a name reference.

### How mapped values are applied

* A mapped value fills a field that the integration leaves empty. If the integration already sets a field, a mapping replaces it only for `memo` and `otherRefNum`. For any other field the integration's own value is kept.
* A mapped reference value is sent as a reference to the NetSuite record, using the selected **Reference type**. A mapped plain value is converted to the NetSuite number or date format where the Younium field is a number or date.
* A number or date value that cannot be read is skipped, so NetSuite never receives `0` or `0001-01-01` in its place.
* Mappings are applied to the invoice, invoice line and customer records. For journal exports, mappings of Younium dimensions can target only a NetSuite custom segment (`cseg…`) or the built-in `class`, `department` and `location` fields, each as a reference.

***

## Eligibility and filtering

Posted invoice handler:

* Runs when an invoice is posted in Younium.
* Invoice lines are sorted by order product line number, then filtered with `HideZeroAmountRecurring` and `HideZeroAmountUsageAndMeasurementLines` per invoice settings.
* Credit memo endpoint is used when `Invoice.TotalAmount.Amount < 0`.
* Line amount/rate sign adjustments apply when header total and line subtotal signs differ.

Export NetSuite accounts:

* Skips an account, and records it as a failed export, when the account has no **default payment term**.
* Skips an account, and records it as a failed export, when its **default invoice address** or **default delivery address** has no country set. Both addresses need a country before the account is included in a later export run.

***

## Field mapping — posted invoice (Younium → NetSuite)

Dates use format `yyyy-MM-dd`.

### Invoice header

| Younium field                                                | NetSuite field     |
| ------------------------------------------------------------ | ------------------ |
| `Account.ExternalERPId`                                      | `entity.id`        |
| `Invoice.InvoiceNumber`                                      | `externalId`       |
| `Invoice.InvoiceDate`                                        | `tranDate`         |
| `Invoice.DueDate`                                            | `dueDate`          |
| `Invoice.Notes`                                              | `memo`             |
| `Invoice.YourOrderNumber`                                    | `otherRefNum`      |
| `Currency.Description` (from invoice subtotal currency code) | `currency.refName` |
| `NetsuiteSettings.LocationId`                                | `location.id`      |
| `NetsuiteSettings.CompanyUrl`                                | `subsidiary.id`    |

Custom mappings for entity **invoice** are merged into the header ExpandoObject after the base object is built.

Custom mappings can use the country of the invoice's own **invoice address** or **delivery address** (for example the country name). The values sent are those saved on the invoice when it was billed, not the account's default addresses, which can differ or change after posting. Account-level address fields are not available on the invoice export. The value is always sent to NetSuite as plain text, so a target field that is a list or record type in NetSuite receives the text value rather than a reference.

### Invoice line

| Younium field                                                                                                                         | NetSuite field                        |
| ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| Charge description; if service period present, appended as `yyyy-MM-dd -- yyyy-MM-dd`                                                 | `description`                         |
| `GetPricePerUnitAndQuantity().Quantity`                                                                                               | `quantity`                            |
| Absolute unit price from `GetPricePerUnitAndQuantity()` (sign adjusted for credits)                                                   | `rate`                                |
| `Price.id`                                                                                                                            | Always `"-1"`                         |
| Absolute or signed `InvoiceLine.Subtotal.Amount`                                                                                      | `amount`                              |
| First non-null: `OrderProductCharge.ExternalERPId`, else `Charge.ExternalERPId`, else `OrderProduct.ChargePlan.Product.ExternalERPId` | `item.id`                             |
| `ServicePeriodStartDate` (if setting field name configured)                                                                           | Dynamic key from `ServicePeriodStart` |
| `ServicePeriodEndDate` (if setting field name configured)                                                                             | Dynamic key from `ServicePeriodEnd`   |
| Line sequence (formatted `0.00`)                                                                                                      | Dynamic key from `LineNumber`         |

Custom mappings for entity **invoiceline** are applied per line.

### Write-back (Younium)

| NetSuite field | Younium field                               |
| -------------- | ------------------------------------------- |
| `tranId`       | Integration custom field **Invoice number** |
| `id`           | `Invoice.ExternalERPId`                     |

Retrieval uses GET `invoice/eid:{InvoiceNumber}` or `creditmemo/eid:{InvoiceNumber}` after POST.

***

## Post invoice workflow

**Runs when:** an invoice is posted in Younium.

Behaviour:

1. Load settings and invoice with lines (filtered per invoice settings).
2. Build NetSuite invoice or credit memo JSON (ExpandoObject).
3. POST to `.../record/v1/invoice` or `.../record/v1/creditmemo` under throttle `ThrottledIntegration.NetSuite`.
4. If NetSuite answers the POST or the follow-up retrieval with a "too many requests" (429) or a server error (5xx) response, Younium retries the call up to five times, waiting about 2, 4, 8, 16 and 32 seconds between attempts, plus up to one second of random variation. When NetSuite sends a retry delay that is longer, Younium waits for that delay instead, up to a maximum of 60 seconds. Other error responses are not retried.
5. If the POST times out, Younium does not repeat it. Instead it checks NetSuite for the invoice by external id up to 15 times at 2-minute intervals.
6. On success, set custom field and `ExternalERPId`, log integration success.

> **Note on exhausted retries:** If the POST still fails after the last retry, the invoice is not posted and stays in Draft. If the retrieval still fails after the last retry, the invoice is posted in Younium without the NetSuite identifiers, so **Invoice number** and the NetSuite id are not populated on the Younium invoice.

***

## Import and export jobs

| Job                            | Direction | Purpose                                                      |
| ------------------------------ | --------- | ------------------------------------------------------------ |
| Import NetSuite accounts       | Import    | Customers into Younium accounts                              |
| Export NetSuite accounts       | Export    | Younium accounts to NetSuite customers                       |
| Import NetSuite exchange rates | Import    | Exchange rates                                               |
| Import NetSuite products       | Import    | Products/items, on demand from the integration settings only |

> **One account import at a time:** Only one NetSuite account import runs at a time for each legal entity, whether it starts from the integration settings or from the schedule. A second import started while one is running is rejected with a conflict message ("A NetSuite account import is already running. Please wait for it to finish and try again."), and no data is requested from NetSuite. If Younium cannot confirm that no other import is running, it refuses to start and asks you to try again later. Once the first account has been written, an import that is already running completes even if the browser request times out.

Journal export uses `ExportJournalsHelper` and optional custom service URL; line mapping respects dimension, tax category, and entity settings above.

> **Customer on journal lines:** When the customer-link setting is on, the customer is set on both the debit and the credit line of an invoice-related journal entry (for example deferred revenue on revenue recognition journals). For payment journals, the accounts receivable credit line is linked to the customer, so it reduces that customer's balance in NetSuite. Transactions without an invoice, such as payouts, carry no customer. If the customer has no NetSuite id, the export fails with an error naming the transaction. Postings already synced are not re-sent.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.younium.com/erp-and-accounting-integrations/netsuite.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
