> 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 ## 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: include invoice account on lines | — | | `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** and **invoiceline**. *** ## 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. *** ## 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. ### 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. On timeout error message containing “timed out”, poll GET by external id up to 15 times at 2-minute intervals. 5. On success, set custom field and `ExternalERPId`, log integration success. *** ## 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 | Journal export uses `ExportJournalsHelper` and optional custom service URL; line mapping respects dimension, tax category, and entity settings above. --- # 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.younium.com/erp-and-accounting-integrations/netsuite.md?ask=&goal= ``` `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.