Skip to main content

​
Manual reconciliation of unsupported sync actions

Orb’s NetSuite integration is designed to preserve the integrity of your financial data between your billing and ERP platform. For a handful of cases where sync handling requires additional intervention or accounting judgment, the integration intentionally does not perform an automated sync. Instead, those cases are surfaced as “Action Needed” errors for manual reconciliation in NetSuite. These unsupported cases are:
  1. Posting transactions into closed accounting periods in NetSuite
  2. Creating invoices for which a customer balance has been applied in Orb
  3. Voiding credit purchases that have already been applied to invoices
Unsupported sync actionCollisionRecommend remediation
  1. Posting transactions into closed accounting periods in NetSuite
In Orb, accounting period locks govern where AR and revenue are reported, but don’t disallow invoicing actions.
In NetSuite, locking accounting periods disallow all transaction activity dated in a closed period.		To sync a transaction dated for a closed period, do one of the following:
  1. Open the relevant accounting period in NetSuite, then resync the invoice from Orb.
  2. OR, manually create a journal entry in NetSuite, then mark the invoice as synced in Orb.
  3. OR, do nothing, and cancel the sync.
  1. Creating invoices for which a customer balance has been applied in Orb
In Orb, any available customer balance is automatically applied to a subsequent invoice and modifies the final amount due. Customer balance can be created from refund credit notes, or manual adjustments.
In NetSuite, the equivalent of customer balance is represented as an AR liability from an open but unapplied credit memo. It must be manually applied to an eligible invoice.		To sync an invoice with customer balance applied:
  1. Sync the invoice anyways, without the balance applied.
  2. Manually apply the credit memo that created this customer balance in NetSuite, then mark this invoice as synced.
  3. OR, do nothing, and cancel this sync.
  1. Voiding credit purchases that have already been applied to invoices
In Orb, once a credit block has been applied to an issued or paid invoice, it can not be returned to the ledger. This holds even if the original credit block has been voided or modified.To sync a void on a credit block that has already been applied to invoices:
  1. OR, do nothing, and cancel this sync.

​
Idempotency handling, record retries and resyncs

​
Idempotency handling

Orb’s NetSuite integration is designed as an asynchronous, queue‑based system that prioritizes idempotent writes: running the same sync job more than once should converge to the same NetSuite state, rather than creating duplicate or conflicting records.
  1. Orb syncs finalized transactions (invoices, credit notes, payments) into NetSuite and records each attempt as an accounting sync record with its own lifecycle and status.
  2. For each record type, Orb uses stable identifiers (for example, Orb customer ID, Orb invoice number, Orb credit note number) mapped into locked custom fields in NetSuite so repeated writes can be recognized and reconciled safely.
  3. The integration sync view in Orb surfaces the full timeline of attempts per record, including queued, in‑progress, synced, and action‑needed states.

​
Record retries

Orb automatically retries certain types of failures to keep NetSuite in sync without manual intervention:
  • Transient errors: Network issues, NetSuite rate limits, and other transient 4xx/5xx responses are treated as retryable. Orb keeps the record in the NetSuite queue and re‑attempts the write according to internal backoff rules.
  • Non‑retryable errors: Structural problems such as missing mappings, invalid configuration, or NetSuite validation failures are surfaced as Action needed in the sync view so an operator can address the root cause.
Once an error is visible in the sync view, you can:
  • Use Retry record for an individual failure to attempt the same payload again after fixing the issue (ex: incorrect item mappings).
  • Retry all failed to sync all failed records.

​
Sync errors and remediation

Here’s a list of supported integration errors, and recommended troubleshooting or remediation steps.

​
Period / State Errors

Sync errorWhat this meansRecommended remediation
Missing accounting configurationThe NetSuite integration is not fully configured in Orb, so Orb does not have the settings it needs to sync the record.Review the NetSuite integration settings in Orb and complete any missing accounting configuration before retrying the sync.
Missing NetSuite subsidiary IDOrb could not find a required subsidiary value for the sync, so it cannot create the NetSuite record in the correct entity context.Configure the NetSuite subsidiary in the integration settings and then retry the failed record.
Unable to determine subsidiaryOrb could not determine which NetSuite subsidiary should be used for this record based on the current configuration and record data.Check the integration’s subsidiary selection logic and confirm the customer, transaction, and mapping data point to a valid subsidiary.
Insufficient permissionsThe NetSuite role used by the integration does not have permission to perform the requested operation.Update the NetSuite integration role to include the required permissions, then retry the sync.

​
Customer Errors

Sync errorWhat this meansRecommended remediation
Duplicate customer nameNetSuite found an existing customer with the same name, so Orb cannot safely create a new customer record automatically.Map the Orb customer to the correct existing NetSuite customer using an external customer ID, or rename the conflicting customer record if appropriate.
Customer record not foundThe NetSuite customer Orb expected to use for the sync does not exist or is no longer accessible.Verify the customer mapping in Orb, confirm the NetSuite customer still exists, and reconnect the record to a valid customer before retrying.

​
Reference / Record Errors

Sync errorWhat this meansRecommended remediation
Invalid or missing reference recordA referenced NetSuite record such as a subsidiary, item, entity, or other mapped object is missing, invalid, or cannot be used for this operation.Check the referenced NetSuite records and mappings, restore or replace any invalid records, and then retry the sync.
Missing item mappingsOne or more Orb items in the transaction are not mapped to NetSuite items, so Orb cannot determine how to create the transaction lines.Add NetSuite item mappings for all affected Orb items and retry the failed sync.

​
Period / State Errors

Sync errorWhat this meansRecommended remediation
Closed accounting periodNetSuite rejected the transaction because it is dated in an accounting period that is closed to posting or mutation.Either reopen the accounting period in NetSuite and retry, or manually reconcile the transaction in NetSuite if reopening the period is not acceptable.
Transaction already voidedOrb attempted to void or mutate a NetSuite transaction that has already been voided.Review whether any further action is actually needed, and avoid retrying unless the related Orb and NetSuite records are first reconciled.
Invoice payment already appliedOrb attempted to apply a payment to an invoice that NetSuite already considers paid.Confirm whether the payment has already been applied correctly in NetSuite, and if so mark the issue resolved rather than retrying blindly.
Customer balance already appliedThe Orb transaction depends on customer balance behavior that cannot be completed automatically through the standard NetSuite sync path.Follow the guided remediation flow in the UI to manually reconcile the customer balance scenario in NetSuite before resolving the sync.
Applied credit block voidedOrb is trying to void a credit block that has already been applied downstream, which requires manual accounting cleanup instead of an automatic sync.Follow the guided remediation flow in the UI to manually unwind the applied credit block state in NetSuite and then resolve the sync.
A duplicate record already exists in NetSuite.There’s an idempotency collision for this record.Do not re-sync – this record has already been synced.

​
Transaction / Data Errors

Sync errorWhat this meansRecommended remediation
Transaction not balancedNetSuite rejected the transaction because the line-level amounts do not add up to a balanced transaction, often due to rounding or line-item discrepancies.Review the transaction totals, line amounts, taxes, and adjustments for inconsistencies, then correct the underlying data and retry; escalate to Orb if the mismatch is not obvious.
Transaction linking failedOrb could not link the NetSuite transaction to the expected invoice or related record, usually because of customer mismatches or inconsistent accounting data.Verify that the related customer and transaction records match across Orb and NetSuite, fix any data inconsistencies, and retry the sync.
Global tax processing errorNetSuite failed while processing the tax data included in the sync payload.Review the tax configuration, tax codes, and transaction tax data in both Orb and NetSuite, then retry after correcting the tax setup.
\