NetSuite advanced integration details

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.

​

Role prerequisites

Use a dedicated custom role for the integration. See 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. 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. The exact additional permission needed to expose it to a restricted role is not yet verified by Hyperline. The main setup guide 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. 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.

​

Object mapping summary

​

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, including write-off journals when used, and the metadata and query checks.
• 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. 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. 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. 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. 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: 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: 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. 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. 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 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. 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. When a refund transaction is deleted in Hyperline, Hyperline deletes the matching NetSuite Customer Refund and restores the Customer Payment or Credit Memo application. 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. 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. 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. 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: 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.