NetSuite Sync Troubleshooting Tips

This guide explains common NetSuite sync failures, how to diagnose them, and best practices for working with NetSuite fields, especially sublist (line-level) fields on transaction records.

Using NetSuite API Documentation

To confirm valid fields and structure:

1. Open the NetSuite Schema Browser
2. Search for the record type (for example, Journal Entry)
3. Review:
   • Header/body fields
   • Sublist fields (such as lineList, itemList, or applyList)
4. Click into the sublist definition to see:
   • Available fields
   • Required vs optional fields

This is the most reliable way to validate field names and structure.

Sublist Field Formatting

What Is a Sublist?

Many NetSuite records contain sublists:

• Header (body) fields
  High-level information such as date, currency, or memo
• Sublist (line) fields
  Line-item details such as account, item, amount, or quantity

Example: Journal Entry

• Header: Post date, currency, memo
• Sublist: Debit and credit lines, account, amount

Sublist Field Structure

Sublist fields are sent as arrays of objects in the NetSuite API.

Example:

[
  { "account": { "internalId": 426 }, "credit": 13 },
  { "account": { "internalId": 426 }, "debit": 13 }
]

Important notes:

• Sublist fields are the most common source of NetSuite sync errors
• Field names are case-sensitive
• Fields must match NetSuite's API schema exactly

Apply Fields (Special Sublist Case)

Some transactions can be applied to other transactions, such as:

• Applying a vendor credit to a bill
• Applying a payment to an invoice

These fields behave like sublists and often include:

• apply
• amount
• doc
• line

Example:

[
  { "apply": true, "doc": "9247", "total": 12 }
]

Key detail:
doc should be the internal ID of the transaction being applied.

Alternative Approach: HTTP Request Object

For complex scenarios or unsupported objects, you can use the HTTP Request object to interact directly with NetSuite's REST API.

Benefits

• Easier debugging
• More flexible field handling

NetSuite's REST API documentation often provides clearer examples that can be tested iteratively.