> ## 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 advanced integration details
> Reference for the NetSuite integration architecture, object mappings, role prerequisites, error recovery, and reconciliation guidance.
This page is intended for implementation consultants, finance systems owners, and technical administrators who need to understand how the NetSuite integration behaves as a system.
For the standard setup flow, see [NetSuite](./netsuite).
## Role prerequisites
Use a dedicated custom role for the integration. See [NetSuite role and permissions](./netsuite#netsuite-role-and-permissions) for the base API permissions, record access levels, metadata limitation, and validation checklist. Use the actual integration token role for these checks in both Sandbox and Live.
### Metadata and query access
Connection validation executes `SELECT 1 AS test`. This confirms credentials and basic SuiteQL access, not access to the records below. Validate the resources required by your configured flows using the **same token and role** that Hyperline uses.
| Operation | NetSuite resources used | Access to validate |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Customer resolution | `customer` through SuiteQL and REST | Look up linked customers and read or write the customer as configured. |
| Transaction lookup and reconciliation | `transaction`, `transactionline`, `nextTransactionLink`; REST `invoice`, `creditMemo`, `customerPayment`, `customerRefund` | Read the relevant transaction types, subsidiaries, lines, and applications; validate writes and deletions separately. |
| Subsidiary and currency mapping | `subsidiary`, `currency` | Read active subsidiaries, their parents, and transaction currencies. |
| Product and account mapping | `item`, `itemsubsidiarymap`, `account`, `accountsubsidiarymap` | Read the records and their subsidiary associations. |
| Tax-code mapping | `salestaxitem`, `taxgroup` | Read both catalogs and their subsidiary availability. |
| Posting-period selection | `accountingperiod` | Read dates, posting status, and closed/A/R-locked/fully-locked flags. |
| Refund payment-method resolution | REST metadata for `customerRefund`, `paymentmethod`, and the original payment or existing refund | Discover refund fields and resolve a valid payment method when required. |
| Field discovery and optional-field checks | `customfield`; REST metadata for `customer` is also used for tax-registration detection | Read custom-field definitions, independently of access to field values on customer or transaction records. |
| Mapped reference values | `customfield`, `customlist`, `customrecordtype`, `scriptrecordtype`, then the referenced list or record | Read definition lookups and the referenced values. This can include `location`, `department`, `classification`, or a custom record. |
| Revenue recognition rule mapping | `revrecrule`, then `revrectemplate`, then `item.revenueRecognitionRule` as fallback catalogs | At least one supported catalog must be readable and contain the intended rules. |
| Write-off creation and cleanup | `transaction` journal lookup; REST `journalEntry` and `customerPayment` | Read, create, and, for cleanup, delete the journal and payment application. Confirm journal approval and posting-period restrictions. |
`CustomField` is a standard NetSuite metadata record describing custom fields, not a table that the customer must create. Oracle documents its use in [SuiteQL metadata queries](https://blogs.oracle.com/developers/extracting-netsuite-records-metadata). The exact additional permission needed to expose it to a restricted role is not yet verified by Hyperline. The [main setup guide](./netsuite#custom-fields-and-metadata-access) describes the known limitation.
REST record metadata and SuiteQL metadata are separate access checks. Successfully reading a customer's REST schema does not prove the role can query `customfield`, and successful discovery does not prove the role can write a field. Do not sign off the integration based on only one of these checks.
To investigate an unavailable record, a NetSuite administrator can use **Setup > Records Catalog**, enable **Show Unavailable Items**, and inspect the required permissions and features for the record. The role permission **Permissions > Setup > Records Catalog**, at **View** level, provides access to this diagnostic UI; it does not grant access to all records shown there. See [Oracle's Records Catalog instructions](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/article_159367848537.html).
If a known field is missing from Hyperline, record the account/environment, token role, entity category, field script ID, and NetSuite error. Contact Hyperline through the in-app chat with these details; do not send token or consumer secrets. An unavailable metadata table is different from an account having no matching fields.
## Architecture summary
The NetSuite integration is a one-way synchronization from Hyperline to NetSuite.
* Hyperline is the source of truth for billing documents, payments, customers created in Hyperline, and wallet activity.
* NetSuite is the accounting destination for synchronized customers, invoices, credit memos, customer payments, customer refunds for refunds and chargebacks, and payment applications.
* Hyperline reads NetSuite metadata such as subsidiaries, items, accounts, tax codes, accounting periods, revenue recognition rules, and custom fields so users can configure mappings in Hyperline.
* Hyperline does not import NetSuite accounting changes back into Hyperline through this integration.
The synchronization is asynchronous and event-driven. Eligible customer, invoice, credit note, payment, refund, chargeback, wallet, and update events schedule synchronization work automatically. Manual **Resync** schedules synchronization work for existing records after configuration changes, fixes, or reconnection.
Completion depends on queue backlog, NetSuite rate limits, and retries; five minutes is not a guaranteed maximum.
## End-to-end data flow
The flow below describes how an invoice, credit note, payment, refund, chargeback, or wallet movement moves from Hyperline to NetSuite.
```mermaid placement="top-right" actions={true} theme={null}
flowchart TD
event["Eligible Hyperline event"]
scope["Scope and status checks"]
customer["Resolve NetSuite customer"]
mappings["Resolve subsidiary, currency, item, account, tax, and field mappings"]
period["Resolve NetSuite posting period"]
transform["Build NetSuite payload"]
push["Create or update NetSuite record"]
link["Store NetSuite record link"]
issue["Record integration issue"]
retry["Fix issue, then retry or resync"]
event --> scope
scope --> customer
customer --> mappings
mappings --> period
period --> transform
transform --> push
push --> link
scope --> issue
customer --> issue
mappings --> issue
period --> issue
push --> issue
issue --> retry
retry --> event
```
| Step | What happens | Main checks |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1. Trigger | A Hyperline record becomes eligible, for example an invoice is issued, a credit note is created, a payment or refund settles, a chargeback is recorded, a linked customer changes, a wallet top-up is paid or reverted, or a user runs **Resync**. | The integration must be connected and the record must be in scope for the selected synchronization mode. |
| 2. Scope and status checks | Hyperline checks whether the record should be synchronized. | Invoice status, connection date or resync window, customer synchronization mode, payment method synchronization mode, chargeback amount, and wallet movement type. |
| 3. Customer resolution | Hyperline finds the linked NetSuite customer or creates one when customer synchronization is set to **From Hyperline to NetSuite**. | Existing NetSuite customer link, NetSuite `externalId`, required customer fields, and subsidiary mapping. |
| 4. Mapping resolution | Hyperline resolves the NetSuite subsidiary, currency, item, account, tax code, revenue recognition rule, rounding item, and custom fields needed for the record. | Invoicing entity mapping, invoice currency, product item mapping, sync rules, tax settings, rounding product setting, required custom fields, and field reference values. |
| 5. Posting period resolution | Before creating or updating transactions, Hyperline checks the NetSuite accounting period for the transaction date. If the period is closed, fully locked, or A/R locked, Hyperline keeps the transaction date and posts the record to the nearest open NetSuite posting period. Customer Payment deletions check the payment's NetSuite transaction date and stop with an integration issue when that period is closed, fully locked, or A/R locked. | NetSuite accounting periods, the closest open posting period, and payment deletion period status. |
| 6. Transformation | Hyperline builds the NetSuite record payload from the Hyperline source record and resolved mappings. | Record type, dates, amounts, memo, external ID, line items, taxability, current payment or credit note applications, and optional Hyperline URL fields. |
| 7. Push to NetSuite | Hyperline creates or updates the NetSuite record and applies related records where needed. | Customer before transaction, invoice or credit memo before payment, current transaction allocations, credit memo applications, and wallet funding allocations. |
| 8. Store result | Hyperline stores the NetSuite record link or records an integration issue. | NetSuite record ID, error message, retry or resync path, and user-visible issue. |
## Object mapping summary
| Hyperline object | NetSuite record | Conditions and exceptions |
| ------------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Invoicing entity | Subsidiary | Required for each Hyperline invoicing entity that issues synchronized transactions. OneWorld accounts are supported. |
| Customer | Customer | Can be linked manually or created automatically when customer synchronization is set to **From Hyperline to NetSuite**. Hyperline checks NetSuite `externalId` for the Hyperline customer ID before creating a new customer. |
| Customer custom properties and built-in customer fields | Customer entity fields | Optional field mappings can populate NetSuite entity-level custom fields. Required mapped fields must have a Hyperline value. |
| Invoice | Invoice | Created or updated for eligible Hyperline invoices. Draft, open, charged on parent, pending parent concatenation, closed, and archived invoices are not pushed. |
| Credit note | Credit Memo | Created for Hyperline credit notes. If the credit note is linked to an invoice, the NetSuite Credit Memo is applied to the matching NetSuite Invoice. |
| Credit note refunded to wallet | Credit Memo and Customer Payment application update | The Credit Memo is applied to the original NetSuite Invoice. If the invoice is already closed, Hyperline first opens the needed invoice balance by updating Hyperline-managed Customer Payment applications. Wallet top-up payments are reconciled through wallet allocation; non-wallet payments are reduced only for the remaining amount. |
| Invoice write-off | Journal Entry and zero-amount Customer Payment | The journal debits the mapped bad debt expense account and credits invoice A/R for the outstanding balance. The payment applies that journal credit to the invoice. Journal approval is required before application when enabled in NetSuite. |
| Invoice or credit note currency | Currency and exchange rate | The NetSuite currency is resolved from the Hyperline document currency. The exchange rate is sent when a Hyperline conversion rate is available. |
| Invoice line | Invoice or Credit Memo item line | Requires a mapped NetSuite item. The account comes from Hyperline sync rules, and tax code comes from Hyperline tax settings when the line is taxable. |
| Coupon discount allocation | Invoice or Credit Memo item line | Created when a coupon applies to an invoice or credit note line. Uses the same item, account, tax code, and revenue recognition rule as the impacted product line. |
| Rounding adjustment | Invoice or Credit Memo item line | Optional non-taxable **Round Off** line added when NetSuite recalculates the total with a one-minor-unit difference and a rounding product is configured. |
| Product | Item | Products are mapped to existing NetSuite items from the Hyperline product **Accounting** section. Hyperline does not create NetSuite items. |
| Product revenue recognition setting | Revenue recognition rule | Optional, available when revenue recognition rules exist in NetSuite. |
| Hyperline sync rule result | Account | Used to set invoice line accounts and payment accounts. Non-posting and statistical accounts are filtered out. |
| Invoicing entity tax setting | Sales tax item or tax group | Sent on taxable invoice lines only. Records are filtered by subsidiary. |
| Settled payment transaction | Customer Payment | Created when the payment method is configured to synchronize. Its applications mirror the transaction's current allocations across NetSuite Invoices. An unallocated amount remains unapplied. |
| Settled refund transaction | Customer Refund | Created when the refund payment method is configured to synchronize. Its allocation determines which Customer Payment or Credit Memo applications Hyperline adjusts before applying the refund. |
| Chargeback | Customer Refund | Created when the chargeback's payment method is configured to synchronize. Hyperline applies it to the original Customer Payment and keeps that payment's remaining invoice applications aligned with current allocations. |
| Cleared or deleted chargeback | Customer Refund deletion and payment application restore | If a previously synchronized chargeback is cleared or the related transaction is deleted, Hyperline deletes the matching NetSuite Customer Refund and restores the original Customer Payment application. |
| Deleted transaction | Customer Payment deletion | Hyperline deletes the matching NetSuite Customer Payment by `externalId` when a synchronized Hyperline transaction is deleted. If the Customer Payment belongs to a closed, fully locked, or A/R locked period, Hyperline records an integration issue instead of deleting it. If a chargeback Customer Refund exists for the transaction, Hyperline removes it first. |
| Paid wallet top-up | Customer Payment | No invoice, receipt, or payment advance document is created for the top-up. The backing paid transaction is pushed as a Customer Payment when eligible. |
| Wallet debit | Customer Payment application | Wallet debits are allocated to paid top-ups using FIFO logic, then applied to NetSuite invoices paid with wallet balance. |
| Credit note wallet refund | Customer Payment application adjustment | When a credit note refunds value to the wallet, Hyperline treats the wallet credit as a reversal of the original invoice wallet debit where possible. Any remaining wallet credit stays available in the customer's wallet. |
| Reverted paid wallet top-up | Customer Refund | Created only when the original wallet top-up was synchronized as a Customer Payment. |
| Hyperline record URL | Optional custom field | `custentity_hyperline_url` for customers and `custbody_hyperline_url` for invoices and credit memos are populated only when the optional NetSuite fields exist. |
| Hyperline invoice line reference | Optional transaction line field | `custcol_hyperline_line_item_id` groups each product line with its related coupon discount lines. |
## Prerequisites checklist
### NetSuite
Before synchronization begins, confirm the following in NetSuite:
* **SuiteTalk REST Web Services** is enabled.
* **Token-Based Authentication** and **SuiteAnalytics Workbook** are enabled.
* A NetSuite **Integration record** exists for Hyperline and is set to `Enabled`.
* The Integration record has **Token-Based Authentication** enabled.
* You copied the **Consumer Key** and **Consumer Secret** when NetSuite displayed them.
* An access token exists for the Hyperline integration record, user, and role.
* You copied the **Token ID** and **Token Secret** when NetSuite displayed them.
* The actual token role satisfies the [record access checklist](./netsuite#record-access), including write-off journals when used, and the [metadata and query checks](#metadata-and-query-access).
* Subsidiaries exist and are active for each Hyperline invoicing entity.
* Currency records exist in NetSuite for every invoice and credit note currency you plan to synchronize.
* Sale or resale items exist for every Hyperline product that can appear on synchronized invoice lines.
* The items are active and available to the relevant subsidiaries.
* Postable GL accounts exist for invoice line income accounts and payment accounts.
* Tax items or tax groups exist for the tax treatments used by the synchronized invoicing entities.
* Accounting periods are configured so Hyperline can resolve each transaction date and use the nearest open posting period when a source period is closed, fully locked, or A/R locked.
* Optional revenue recognition rules exist if you plan to attach them to invoice lines.
* Optional custom fields exist if you plan to map Hyperline values to NetSuite fields, and their access settings allow the integration role to populate them. Definition lookups must succeed even when optional Hyperline fields do not exist.
* Optional Hyperline URL fields exist if you want NetSuite records to link back to Hyperline.
* The optional Hyperline line item field exists if you want to group related product and coupon discount lines reliably.
### Hyperline
Before synchronization begins, confirm the following in Hyperline:
* NetSuite is connected from **Settings > Integrations** with the correct Account ID and token-based authentication credentials.
* Each Hyperline invoicing entity that issues synchronized documents is mapped to a NetSuite subsidiary.
* Customer synchronization mode is selected.
* Existing NetSuite customers are linked to Hyperline customers when automatic customer creation should not be used.
* Products are mapped to NetSuite items from the product **Accounting** section.
* A rounding product is selected in the integration settings when one-minor-unit NetSuite rounding differences should be reconciled automatically.
* Revenue recognition rules are mapped on products when needed.
* Sync rules resolve invoice line, invoice write-off, payment, refund, and chargeback accounts.
* Tax codes are configured in Hyperline tax settings for each invoicing entity.
* Payment, refund, and chargeback synchronization mode is selected for each payment method.
* Customer, invoice, and line-item custom properties are created before field mappings are configured.
* The initial resync scope and date range are defined if historical records need to be sent.
## Detailed field mappings
### Customers
When Hyperline creates or updates a NetSuite customer, it sends the following standard fields.
| NetSuite field | Hyperline source |
| -------------------------- | -------------------------------------------------------------------- |
| `externalId` | Hyperline customer ID |
| `entityId` | Hyperline customer ID |
| `companyName` | Customer name |
| `email` | Billing email |
| `subsidiary` | NetSuite subsidiary mapped from the Hyperline invoicing entity |
| `vatRegNumber` | Customer tax ID |
| `taxRegistration` | Customer tax ID and billing country, when both are available |
| `taxable` | Customer taxability, when set in Hyperline |
| Default billing address | Billing address line 1, city, zip, state, and country |
| `custentity_hyperline_url` | Hyperline customer URL, only when the optional NetSuite field exists |
When a linked customer is updated in Hyperline, Hyperline updates the corresponding NetSuite customer. If a Hyperline customer has not yet been linked or created in NetSuite, customer updates are ignored until the customer is needed by a synchronized document or payment.
Any NetSuite entity-level custom field can be mapped from the **Field mappings** section of the integration settings. The Hyperline source can be a built-in customer field or a customer [custom property](../docs/properties/overview).
Built-in customer sources include:
* Customer name
* Billing email
* Tax ID
* Local tax number
* Billing address name
* Billing address line 1 and line 2
* Billing city, zip, country, and state
For NetSuite fields that reference another record:
* If the Hyperline source is a `select` custom property, Hyperline resolves the selected value by name to the NetSuite internal ID. This works for standard references such as Location, Department, and Class, and for custom-list or custom-record references.
* If the Hyperline source is not a `select` custom property, Hyperline sends the value as-is. Use the NetSuite internal ID when the target field expects a record reference.
If a mapped field is marked as required and the Hyperline value is empty, synchronization fails so you can complete the data and retry.
### Invoices and credit notes
Hyperline invoices are pushed as NetSuite **Invoice** records. Hyperline credit notes are pushed as NetSuite **Credit Memo** records.
| NetSuite field | Hyperline source |
| ------------------------ | ----------------------------------------------------------------------------- |
| `entity` | Linked NetSuite customer internal ID |
| `currency` | NetSuite currency resolved from the Hyperline invoice or credit note currency |
| `exchangeRate` | Hyperline conversion rate, when available |
| `tranDate` | Invoice or credit note emission date |
| `dueDate` | Due date |
| `tranId` | Hyperline invoice or credit note number |
| `memo` | Invoice custom note |
| `externalId` | Hyperline invoice or credit note ID |
| `isTaxable` | Based on the Hyperline tax scheme |
| `custbody_hyperline_url` | Hyperline invoice URL, only when the optional NetSuite field exists |
| `item.items` | Line items built from Hyperline invoice lines |
If Hyperline does not yet have a stored NetSuite link for an invoice or credit note, it checks NetSuite before creating a new record. Hyperline looks for a matching NetSuite transaction using either:
* the Hyperline invoice or credit note ID in NetSuite `externalId`
* the Hyperline invoice or credit note number in NetSuite `tranId`
When exactly one matching record is found for the same customer and currency, Hyperline updates that record instead of creating a duplicate. If multiple records match, or if the matching record belongs to a different customer or currency, synchronization stops with an integration issue so the records can be reviewed before retrying.
When a credit note is linked to an existing invoice in Hyperline, the NetSuite Credit Memo is automatically applied to the matching NetSuite Invoice for the credited amount.
When that linked credit note is refunded to the customer's wallet, the Credit Memo is still applied to the original NetSuite Invoice. A wallet refund does not create a NetSuite Customer Refund, because the customer receives wallet balance rather than a cash refund.
Before applying the Credit Memo, Hyperline checks whether the original NetSuite Invoice has enough open balance:
* If the invoice was paid with wallet balance, wallet payment synchronization reduces or removes the wallet top-up Customer Payment application first.
* If the invoice was paid by a synchronized non-wallet payment, such as card, direct debit, bank transfer, or an offline payment, Hyperline reduces the matching Hyperline-managed Customer Payment application by the amount needed for the Credit Memo.
* If the invoice was paid by both wallet and another payment method, Hyperline opens the wallet-paid amount first, then reduces the non-wallet Customer Payment only for the remaining shortfall.
Hyperline preserves other applications on the same Customer Payment and does not mutate manual or unknown NetSuite payments. If the invoice cannot be opened using Hyperline-managed payment applications, synchronization stops with an integration issue instead of applying the Credit Memo to the wrong balance.
Hyperline sends positive regular product line amounts on NetSuite Credit Memo records. The NetSuite record type carries the reversal. Coupon discount lines remain negative because they offset the gross product line amount.
When an invoice is marked `uncollectible` and uncollectible invoice synchronization is enabled, Hyperline keeps the NetSuite Invoice in sync and creates a separate write-off Journal Entry. The journal uses the configured write-off date and outstanding balance, debits **Bad Debt Expense** from the matching invoice sync rule, and credits the invoice's A/R account. A zero-amount Customer Payment applies the journal credit to the original invoice. If approval is required, approve the journal in NetSuite before retrying. Existing journals and applications are checked for consistency; a mismatch requires review rather than being overwritten. Cleanup removes the payment application before the journal, provided their posting periods permit deletion. These accounting records do not refund or reverse a settled payment through the payment provider.
Invoice and credit note lines are mapped as follows:
| NetSuite line field | Hyperline source |
| -------------------------------- | -------------------------------------------------------------------------------- |
| `item` | NetSuite item selected on the Hyperline product |
| `description` | Hyperline line item name |
| `quantity` | Hyperline unit count, or `1` when no unit count is available |
| `rate` | Line amount excluding tax divided by quantity |
| `amount` | Absolute line amount excluding tax |
| `account` | NetSuite account resolved from Hyperline sync rules |
| `revenueRecognitionRule` | Revenue recognition rule selected on the Hyperline product |
| `isTaxable` | Based on the Hyperline invoice tax scheme |
| `taxCode` | NetSuite tax code resolved from Hyperline tax settings, when the line is taxable |
| `custcol_hyperline_line_item_id` | Hyperline invoice line item ID, when the optional NetSuite field exists |
| Custom column fields | Supported invoice line item field mappings, such as period start and period end |
Lines with no units and a zero amount are skipped.
When a coupon applies to an invoice or credit note line, Hyperline grosses up the impacted product line by the allocated discount amount, then adds a separate coupon discount line. Coupon discount lines are mapped as follows:
| NetSuite line field | Hyperline source |
| -------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `item` | Same NetSuite item as the impacted product line |
| `description` | Coupon name, product name, and service period when available |
| `quantity` | `1` |
| `rate` and `amount` | Negative allocated coupon amount |
| `account` | Same NetSuite account as the impacted product line |
| `revenueRecognitionRule` | Same revenue recognition rule as the impacted product line |
| `isTaxable` and `taxCode` | Same tax treatment as the impacted product line |
| `custcol_hyperline_line_item_id` | Same Hyperline invoice line item ID as the impacted product line, when the optional NetSuite field exists |
| Custom column fields | Same supported invoice line item field mappings as the impacted product line |
If a coupon applies to multiple invoice lines, Hyperline splits the discount across the impacted lines and creates one coupon discount line for each non-zero allocated share.
When `custcol_hyperline_line_item_id` exists, Hyperline sends the same `ili_...` value on the product line and its coupon discount lines. This preserves their relation when a product appears more than once or NetSuite reorders transaction lines. Without this optional field, Hyperline uses the impacted product's NetSuite item on each negative coupon line. If explicit invoice line associations are unavailable, Hyperline allocates the coupon to lines with a non-zero discount, or to all invoice lines as a fallback.
If a rounding product is configured on **Settings > Integrations > NetSuite**, Hyperline checks the NetSuite total after creating or updating an invoice or credit memo. When NetSuite differs from the Hyperline total by one currency minor unit, Hyperline adds a non-taxable **Round Off** line with the configured item. Larger differences stop with an integration issue.
Any NetSuite transaction body custom field on invoices can be mapped from a Hyperline invoice custom property. The standard NetSuite **Location** transaction body field is also available in the invoice field selector. When the mapped Hyperline property is a `select` custom property, Hyperline resolves the selected value name to the matching active NetSuite location.
Any NetSuite column-level custom field 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.
### Products and items
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.
Only active sale or resale items of type `Service`, `Non-Inventory Part`, and `Inventory Part` are exposed by Hyperline.
In OneWorld accounts, the item selector is filtered by the mapped subsidiary. Items available through parent subsidiaries with child access are also included.
If a line item is missing a product mapping, the invoice synchronization fails with a clear issue so you can fix the mapping and retry.
### Accounts
NetSuite requires an income account on every invoice line and a bank or accounts receivable account on customer payments, refunds, and chargeback Customer Refunds.
* **Per-line invoice account**: resolved through sync rules configured from **Settings > Integrations > NetSuite > Sync rules**. Hyperline converts the resolved account code to the matching NetSuite internal account ID before sending the invoice or credit note.
* **Coupon discount line account**: inherited from the product line the coupon discounts. To route coupon-impacted lines differently, use coupon criteria on invoice sync rules so the impacted product line resolves to the expected account.
* **Invoice write-off account**: resolved from the **Bad Debt Expense** account on the matching invoice sync rule. Hyperline debits this account on the write-off Journal Entry and credits the invoice's A/R account, then applies the journal through a zero-amount Customer Payment.
* **Customer Payment and Customer Refund account**: resolved through sync rules for payment, refund, and chargeback transactions. If no rule resolves to a NetSuite account, the Customer Payment or Customer Refund is sent without an explicit account so NetSuite can apply its own default behavior.
* 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. Hyperline then resolves the configured tax code and pushes it to NetSuite on each taxable line item.
Both `salestaxitem` and `taxgroup` records are exposed, filtered by subsidiary.
### Payments
Payments, refunds, and chargebacks use a per-payment-method synchronization mode. Each payment method can be set to:
* **No synchronization**: payments, refunds, and chargebacks are not synchronized.
* **From Hyperline to NetSuite**: settled payments in Hyperline are pushed as NetSuite Customer Payments with their current applications. Settled refunds and chargebacks for the same payment method are also synchronized.
Hyperline creates one NetSuite **Customer Payment** per eligible settled Hyperline transaction. The Customer Payment belongs to the transaction rather than to one invoice, so one payment can be applied across several invoices.
| NetSuite Customer Payment field | Hyperline source |
| ------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `customer` | Customer on the Hyperline transaction |
| `payment` | Transaction amount |
| `account` | Account resolved from transaction sync rules |
| `tranDate` | Transaction processing date, or the synchronization date if no processing date is available |
| `memo` | `Transaction {transaction_id}` |
| `externalId` | Hyperline transaction ID |
| `apply.items` | One application for each current invoice allocation, capped to the NetSuite invoice's available balance |
The sum of the applications can be lower than the Customer Payment amount. This happens when some or all of the transaction is unallocated, when the allocated amount exceeds the available NetSuite invoice balance, or when part of the transaction was added to the wallet but has not been consumed yet. The difference remains unapplied on the Customer Payment.
A €500 transaction has current allocations of €300 to Invoice A and €150 to Invoice B. NetSuite receives one €500 Customer Payment with two applications. The remaining €50 is unapplied.
If an allocation is removed or moved in Hyperline, Hyperline reconciles the existing Customer Payment's applications. Removing an allocation leaves that amount unapplied. Moving it removes the previous application and adds the new one. Past allocations remain available in Hyperline for traceability but do not affect the current NetSuite applications.
The reverse is also supported: if an invoice is paid by several eligible transactions, Hyperline creates one Customer Payment for each transaction. This supports partial payments and mixed payment sources.
If a settled transaction amount is greater than the remaining balance on the NetSuite Invoice, Hyperline still creates the Customer Payment for the full transaction amount. It applies only the remaining invoice balance and leaves the excess amount unapplied on the Customer Payment. This excess is not converted into a wallet top-up.
An eligible settled transaction with no active allocation is still synchronized. Hyperline creates or updates the Customer Payment without an invoice application so the funds remain unapplied in NetSuite.
See [Understand payment allocations](/docs/payments/allocations) for the allocation rules in Hyperline.
If a settled payment is later charged back, the original Customer Payment remains in NetSuite and the chargeback is represented separately as a NetSuite Customer Refund applied to that payment. See [Refunds and chargebacks](#refunds-and-chargebacks).
When a Hyperline transaction is deleted, the corresponding NetSuite Customer Payment is deleted by matching the Hyperline transaction ID stored in `externalId`. If the Customer Payment belongs to a closed, fully locked, or A/R locked period, Hyperline leaves it in NetSuite and records an integration issue.
When payment synchronization runs again, Hyperline only deletes stale NetSuite Customer Payments that it created, identified by a Hyperline transaction ID in `externalId`. Before deleting stale Hyperline-owned Customer Payments, Hyperline checks that each payment can be deleted. If one is blocked by a closed, fully locked, or A/R locked period, no stale payment is removed and an integration issue is recorded.
If the NetSuite invoice already has applied Customer Payments that were not created by Hyperline, Hyperline does not delete or overwrite them. A blank-`externalId` Customer Payment can be adopted only when it uniquely matches a Hyperline transaction by amount and transaction date. In that case, Hyperline sets the Customer Payment `externalId` to the Hyperline transaction ID and continues future updates against that record. Hyperline also checks for existing Customer Payments by transaction `externalId`, so a previously synchronized payment is not recreated if it is later unapplied or applied to another invoice in NetSuite.
If Hyperline cannot confidently match an existing applied Customer Payment, synchronization stops with an integration issue instead of creating another payment that could duplicate the accounting record. Wallet top-up Customer Payments are also preserved because they are reconciled by wallet payment synchronization.
### Wallet top-up payments
Paid wallet top-ups are handled separately from regular invoices and are created only from wallet top-up flows, not from invoice overpayments:
* Hyperline does not create or push an invoice, receipt, or payment advance document for a paid wallet top-up.
* The paid top-up is pushed as a NetSuite Customer Payment when its backing transaction is settled, has no chargeback amount, and its payment method is configured to synchronize.
* Wallet debits are allocated to paid top-ups using persisted FIFO funding allocations, then applied to the NetSuite invoices paid with wallet balance.
* If one backing transaction is partly allocated directly to an invoice and partly added to the wallet, NetSuite receives one Customer Payment for the full transaction. Its applications combine the current direct allocations and the wallet-funded invoice applications.
* Free wallet credits are not pushed as Customer Payments.
* If a paid wallet top-up is reverted, Hyperline removes its wallet-funded applications, preserves any direct applications from the same transaction, and creates a NetSuite Customer Refund for the eligible reverted wallet amount.
If the original Customer Payment is missing when a paid wallet top-up is reverted, Hyperline does not create the Customer Refund. It records an integration issue so you can synchronize or review the missing payment, then retry.
Wallet funds can only create NetSuite applications for invoices issued by the same Hyperline invoicing entity as the paid top-up. If wallet funds are consumed across invoicing entities, Hyperline leaves those NetSuite applications unapplied and records an integration issue because an intercompany accounting entry is required.
### Credit notes refunded to wallet
When a credit note refunds value to the customer's wallet, Hyperline treats that wallet credit as customer balance rather than a cash refund. NetSuite synchronization follows the accounting effect of the credit note:
1. Hyperline synchronizes the wallet payment applications for the customer.
2. If the credit note reverses an invoice that used wallet balance, Hyperline reverses the related wallet debit allocation first.
3. Hyperline checks the original NetSuite Invoice remaining balance.
4. If more balance must be opened before applying the Credit Memo, Hyperline reduces Hyperline-managed non-wallet Customer Payment applications for the shortfall.
5. Hyperline creates or updates the NetSuite Credit Memo and applies it to the original NetSuite Invoice.
For example, if a `100` invoice was paid by card and a `30` credit note is refunded to wallet, Hyperline reduces the NetSuite card Customer Payment application to `70`, applies a `30` Credit Memo to the original invoice, and leaves the customer value available as wallet balance in Hyperline. In NetSuite, the customer has an unapplied payment credit for the same amount.
If a `100` invoice was paid with `40` from wallet and `60` by card, and a `50` credit note is refunded to wallet, Hyperline first reverses `40` of wallet payment application, then reduces the card Customer Payment application by `10`, and applies the `50` Credit Memo to the invoice.
Manual NetSuite payments and payments that Hyperline cannot identify as Hyperline-managed are not changed by this flow. If they prevent the Credit Memo from being applied, Hyperline records an integration issue so the payment can be reviewed manually.
### Refunds and chargebacks
Credit notes are synchronized as NetSuite Credit Memos and are applied to the original NetSuite Invoice when they are linked to an invoice in Hyperline.
Settled refund transactions are synchronized as NetSuite **Customer Refund** records when the refund payment method is configured with **From Hyperline to NetSuite**.
For a refund linked to an original payment, Hyperline:
1. Finds the original NetSuite Customer Payment using the original Hyperline transaction ID.
2. Reconciles that Customer Payment's applications to the amounts that remain allocated across its invoices.
3. If part of the refund is allocated to a credit note, reduces the corresponding Credit Memo applications by that amount.
4. Creates a Customer Refund applied to the original Customer Payment, the affected Credit Memos, or both.
A linked refund can still be synchronized when it has no active allocation. In that case, the Customer Refund is applied to the original Customer Payment, while the original payment's remaining invoice applications come from the current allocation state.
For a refund recorded without an original payment, the refund must be fully allocated to one or more credit notes before NetSuite synchronization. Hyperline then:
1. Creates or updates the affected NetSuite Credit Memos.
2. Reconciles each Credit Memo's remaining invoice applications.
3. Creates a Customer Refund applied to the Credit Memos according to the refund allocations.
If a standalone refund is unallocated, partially allocated, or allocated to an invoice instead of a credit note, Hyperline records an integration issue instead of creating an inconsistent NetSuite refund.
| NetSuite Customer Refund field | Hyperline source |
| ------------------------------ | -------------------------------------------------------------------------------------------------- |
| `customer` | Customer on the NetSuite Invoice or Credit Memo |
| `account` | Account resolved from transaction sync rules |
| `tranDate` | Refund transaction processing date, or the synchronization date if no processing date is available |
| `memo` | Refund transaction reference |
| `externalId` | Hyperline refund transaction ID |
| `apply.items` | Applications to the original Customer Payment and any refunded Credit Memos |
When a refund transaction is deleted in Hyperline, Hyperline deletes the matching NetSuite Customer Refund and restores the Customer Payment or Credit Memo application.
For a refund linked to an original payment, that Customer Payment must already exist in NetSuite. If Hyperline cannot find it, Hyperline does not create the Customer Refund and records an integration issue. Synchronize the original payment, then retry the refund synchronization.
Chargebacks are synchronized as NetSuite **Customer Refund** records when the chargeback's payment method is configured with **From Hyperline to NetSuite**.
For chargebacks, Hyperline:
1. Finds the original NetSuite Customer Payment using the charged-back Hyperline transaction ID.
2. Reconciles the Customer Payment applications to the amounts that remain allocated across its invoices.
3. Creates or updates a Customer Refund applied to that Customer Payment.
Hyperline creates one chargeback Customer Refund per original payment and uses the total active chargeback amount. A chargeback can remain linked to an invoice without a current allocation when another movement, such as a refund, has already removed that part of the payment effect.
| NetSuite Customer Refund field | Hyperline source |
| ------------------------------ | ------------------------------------------------------------ |
| `customer` | Customer on the NetSuite Invoice |
| `account` | Account resolved from chargeback sync rules |
| `tranDate` | Chargeback date, or the original transaction processing date |
| `memo` | Chargeback transaction reference |
| `externalId` | Hyperline chargeback transaction reference |
| `apply.items` | Application to the original Customer Payment |
If a chargeback amount is later cleared, Hyperline deletes the matching NetSuite Customer Refund and restores the Customer Payment application instead of leaving a stale chargeback record in NetSuite.
When a transaction is deleted in Hyperline, Hyperline removes the matching chargeback Customer Refund before deleting the related Customer Payment. If the chargeback Customer Refund cannot be deleted, Hyperline still attempts the payment deletion and records an integration issue for the chargeback cleanup.
### Optional Hyperline URL fields
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 is 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` | Invoice and Credit Memo | Free-Form Text | `https://app.hyperline.co/app/invoices/{id}` |
If the definition lookup succeeds and confirms the field does not exist, Hyperline skips it. A failed metadata lookup can block synchronization; absence of a field and lack of access to its definition are different conditions.
### Optional Hyperline line item field
Create the following transaction line field to group each product line with its related coupon discount lines. Hyperline sends the same line item ID to the product line and its discounts, even when the same product appears multiple times or NetSuite reorders the transaction lines. No extra mapping is required.
| NetSuite field ID | Record type | Field type | Value pushed |
| -------------------------------- | ---------------- | -------------- | ------------------------------------------ |
| `custcol_hyperline_line_item_id` | Transaction line | Free-Form Text | Hyperline invoice line item ID (`ili_...`) |
If the definition lookup succeeds and confirms the field does not exist, Hyperline skips it. A failed metadata lookup can block synchronization; absence of a field and lack of access to its definition are different conditions.
## Synchronization architecture and latency
Synchronization is asynchronous and event-driven:
* New eligible Hyperline records schedule synchronization automatically.
* Updates to linked Hyperline invoices and customers schedule updates to the matching NetSuite records.
* **Resync** schedules synchronization for existing records after mappings, credentials, or NetSuite record links are corrected.
* Hyperline stores NetSuite record links so subsequent updates target the existing NetSuite record instead of creating duplicates. If a link is missing during a migration, Hyperline can reconcile invoices and credit notes against NetSuite `externalId` or document number before creating a new record.
* Hyperline uses Hyperline record IDs as NetSuite external IDs where supported, including customers, invoices, credit notes, payment transactions, refund transactions, and chargeback records.
Queue backlog, NetSuite rate limits, retries, and bulk resync volume can delay completion. Each eligible record follows the same validation, transformation, and push flow; five minutes is not a guaranteed maximum.
If NetSuite is temporarily unavailable or credentials are invalid, Hyperline cannot complete the push at that moment. The source record remains in Hyperline, and Hyperline records an integration issue when the synchronization attempt fails. After NetSuite is available again or credentials are corrected, retry the affected records from the issue workflow or run **Resync** for the relevant scope.
## Error handling and recovery
Hyperline owns synchronization attempts, NetSuite record links, and issue creation. Your finance or implementation team owns correcting configuration, permissions, mappings, locked periods, and source data that NetSuite rejects.
Retries are managed from Hyperline. After the blocking condition is fixed, retry the affected issue or run **Resync** for the relevant scope. You should not manually recreate the same record in NetSuite unless Hyperline support confirms that the record is outside the integration scope.
Common recoverable issues include:
| Issue | Recovery |
| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Missing subsidiary mapping | Map the invoicing entity to a NetSuite subsidiary, then retry or resync. |
| Missing customer link while customer synchronization is disabled | Link the customer manually, then retry or resync. |
| Missing product item mapping | Map the Hyperline product to a NetSuite item, then retry or resync. |
| Missing or unresolved account | Update Hyperline sync rules, then retry or resync. |
| Missing write-off bad debt account | Configure **Bad Debt Expense** on the matching invoice sync rule, then retry or resync. |
| Missing chargeback account | Update the chargeback account mapping in Hyperline sync rules, then retry or resync. |
| Missing tax code | Configure the tax code in the Hyperline invoicing entity tax settings, then retry or resync. |
| Required mapped custom field is empty | Complete the Hyperline field value, then retry or resync. |
| Closed, fully locked, or A/R locked accounting period | For invoice, credit note, and payment creation or updates, Hyperline keeps the original transaction date and posts to the nearest open NetSuite posting period. For Customer Payment deletion, Hyperline records an integration issue and leaves the payment in NetSuite; adjust or remove it in NetSuite with the right administrator permissions, then resolve or ignore the issue in Hyperline. |
| NetSuite permission error | Check the actual token role, the [record access requirements](./netsuite#record-access), and account restrictions. Correct the identified access issue, then retry. |
| Field search shows no results or NetSuite reports `Record 'customfield' was not found` | Follow the [metadata access checks](#metadata-and-query-access) and contact Hyperline. Do not assume the field is absent or that the base API permissions are sufficient. |
| Write-off journal awaiting approval | Approve the journal in NetSuite, then retry the invoice sync. |
| NetSuite unavailable or credentials revoked | Restore NetSuite availability or reconnect NetSuite, then retry or resync. |
Eligible records are not deleted from Hyperline when synchronization fails, so they are not permanently lost from the source system. A matching NetSuite record can remain missing until the blocking issue is fixed and the record is retried or resynchronized. However, some records are intentionally out of scope and will not create NetSuite records through this integration:
* Invoices in unsupported statuses, such as draft or archived invoices.
* Records created before the connection date unless included in a supported resync or handled with support.
* Payments, refunds, or chargebacks for methods set to **No synchronization**.
* Free wallet credits.
* NetSuite dispute or write-off records for chargebacks. Chargebacks are synchronized as Customer Refund records when they are in scope.
This means eventual consistency is expected for eligible records when NetSuite is available and all required configuration is valid. It is not expected for records outside the integration scope or records that continue to fail validation.
## Reconciliation model
Hyperline provides issue tracking, NetSuite record links, and resync tools for operational reconciliation. It does not currently provide a dedicated NetSuite balance certification report.
Use the following reconciliation approach after go-live:
1. Open **Settings > Integrations > NetSuite > View issues** and resolve all open NetSuite issues.
2. Export or review Hyperline invoices, credit notes, payments, refunds, and chargebacks for the go-live period.
3. In NetSuite, use saved searches for **Invoice**, **Credit Memo**, **Customer Payment**, and **Customer Refund** records created by Hyperline.
4. Match records using NetSuite `externalId`, Hyperline document numbers, customer names, dates, currencies, subsidiaries, and optional Hyperline URL fields.
5. Compare invoice, credit note, and payment totals by subsidiary, currency, and accounting period.
6. Review known exceptions separately, especially disabled payment methods, free wallet credits, unsupported invoice statuses, chargebacks that require manual dispute reporting, and records outside the selected resync period.
7. Run **Resync** for missing eligible records after any mapping or permission corrections.
For easier reconciliation, create the optional Hyperline URL fields in NetSuite before go-live. They give reviewers a direct link from NetSuite records back to the source customer or invoice in Hyperline.