NetSuite integrations: subsidiaries, custom fields and SuiteTalk

When a software company moves from small business to mid-market, one question starts showing up in every sales call: "Do you integrate with NetSuite?"

A NetSuite integration is not a bigger QuickBooks integration. Customers run several legal entities, have years of custom fields, route bills through approvals and share API capacity across every tool they own. Get those patterns wrong and the deal stalls in the technical review.

This guide covers the NetSuite patterns that matter most. Details reflect Oracle NetSuite's public documentation at the time of writing; check the current docs for your account's version and limits.

The API surfaces#

NetSuite offers several ways in, and most serious integrations use more than one.

• SuiteTalk SOAP web services. The long-standing API, with broad record coverage and strict schemas.
• SuiteTalk REST web services. A newer REST interface over NetSuite records, with metadata endpoints describing each account's record shapes.
• SuiteQL. A SQL-like query language, available through the REST API, for efficient reads and joins.
• RESTlets. Custom endpoints written in SuiteScript and deployed into the customer's account.

A common pattern: SuiteQL for bulk reads, REST web services for writes, and RESTlets only when a customer needs logic that standard endpoints can't express. RESTlets live in the customer's account, so they add deployment and maintenance work.

Auth: TBA and OAuth 2.0#

NetSuite supports token-based authentication (TBA), an OAuth 1.0a-style scheme with consumer and token credentials, and OAuth 2.0 for REST and SuiteQL.

Practical notes:

• Integration records. Your app is registered as an integration record in each customer's account, or installed through a bundle or SuiteApp.
• Roles decide access. Tokens act as a user with a role. The role's permissions decide which records your integration can see and change. Write down the minimum permissions you need, and give customers a role template.
• Account ids matter. Each customer has an account id, and sandbox accounts have their own. Keep them distinct.

Permission errors are the most common NetSuite support ticket. Make them clear in your product: name the missing permission, not just "access denied".

Subsidiaries and multi-entity#

NetSuite OneWorld lets one account hold many subsidiaries, each a legal entity with its own currency, and often its own tax setup.

This changes almost every object:

• Transactions belong to a subsidiary. An invoice or vendor bill is posted for one subsidiary.
• Entities span subsidiaries. A vendor can be shared across several subsidiaries, with rules about which can transact with it.
• Accounts are restricted. An account may be available to some subsidiaries only.
• Intercompany transactions link records across subsidiaries.

Your product must ask, or infer, which subsidiary a write belongs to. Filter reads by subsidiary when your users think in entities.

curl "https://api.unifyint.com/v1/finance/vendor-bills?subsidiary_id=sub_02" \
  -H "Authorization: Bearer $UNIFY_API_KEY" \
  -H "Unify-Connection-Id: conn_nts_5q2w4"

Dimensions: departments, classes and locations#

NetSuite classifies transactions by department, class and location, and customers can add custom segments. Finance teams report on them, so writes without the right dimensions create cleanup work.

Map dimensions once per connection, let users choose defaults, and validate them before submit. Some accounts make a dimension mandatory on certain transactions; read the requirements instead of guessing.

Custom fields and custom records#

Mid-market NetSuite accounts are customized. You will meet:

• Custom body fields (custbody_ prefix) on transaction headers.
• Custom column fields (custcol_ prefix) on transaction lines.
• Custom entity fields (custentity_ prefix) on customers, vendors and employees.
• Custom item fields (custitem_ prefix) on items.
• Custom records (customrecord_ prefix), entirely new record types.

Some custom fields are mandatory. A vendor bill write that ignores a required custom field fails. Your integration needs a way to discover custom fields per account, let the customer map them, and send values on writes.

Custom records are harder. They are account-specific record types with their own fields. Most integrations expose them through a generic path, such as SuiteQL reads and passthrough writes, rather than modeling each one.

Approvals and transaction states#

Many NetSuite customers route vendor bills, purchase orders and journal entries through approval workflows. A bill may be created as pending approval and only post to the general ledger once approved.

Respect the workflow:

• Create records in the state the workflow expects, usually pending approval.
• Don't set approval fields directly unless the customer asks you to and the role allows it.
• Read approval status so your product shows "awaiting approval" instead of "synced".

Bypassing approvals is a fast way to fail a customer's controls review.

Concurrency governance#

NetSuite limits how many web service requests an account can process at once. The limit depends on the account's service tier and any extra SuiteCloud Plus licenses. Every integration the customer runs shares that pool.

Implications:

• You are not alone. Your integration competes with the customer's other tools.
• Exceeding the limit returns errors you must retry with backoff.
• Batch and query efficiently. SuiteQL reads that return many records in one call use less capacity than many single-record gets.
• Schedule heavy syncs outside the customer's busy hours.

SuiteScript also has governance limits on the work a script can do. If you deploy RESTlets, budget for them.

Saved searches and reporting#

Finance teams live in saved searches. Customers may ask you to read a specific saved search instead of raw records. It can be a quick path to the data they trust, but it ties your integration to a definition you don't control. Document the dependency.

A checklist for the technical review#

• Minimum role permissions written down, with a template role.
• Subsidiary handling on every read and write.
• Department, class, location and custom segment mapping.
• Custom field discovery and mapping per account, with required fields enforced.
• Custom records reachable through a generic path.
• Approval-aware writes.
• Backoff on concurrency errors, efficient bulk reads.
• Clear permission error messages.
• Separate sandbox and production account handling.

How Unify Int fits#

The Unify ERP API models NetSuite subsidiaries, dimensions, custom fields and approval states on the Unify Graph. Custom records are available through passthrough, and the Technology Center can model recurring ones for you.

See the ERP API, the NetSuite integration, or book a demo to walk through your customers' accounts.