Best Practices

Recommended setup

Use Objects for standard records

Choose Objects when you need a standard or custom record type as-is — invoices, sales orders, vendor bills, and similar records map cleanly to a single table this way.

Use SuiteQL for joins and custom filters

Choose SuiteQL when you need fields from multiple related records in one row, calculated columns, or filters that aren't exposed as Object parameters.

Scope the Access Token role to what's needed

Create a role for the Access Token that grants view access only to the record types your data flows actually use, rather than reusing an Administrator token. This limits blast radius if the token is ever exposed.

Confirm Token-Based Authentication is enabled before troubleshooting

Most first-time connection failures trace back to Token-Based Authentication or REST Web Services not being enabled under SuiteCloud features, or an Access Token created under the wrong role.

Data refresh and scheduling

Use Start date for incremental objects

For record types that support it (those with a last-modified field), set Start date to pull only recently changed records instead of re-exporting the entire object every run.

Daily refresh for most transactional data

Invoices, sales orders, and vendor bills are typically entered during business hours — a daily refresh after close of business captures the day's activity.

Full-refresh objects don't need frequent scheduling

Record types without a last-modified field re-pull in full every run regardless of schedule. For large ones, refresh less frequently to reduce load and run time.

SuiteQL always runs full

SuiteQL has no incremental mode — build the date filter into your query's WHERE clause if you want to limit each run's scope.

Performance optimization

Lower Window in days for large objects

Objects with a high transaction volume (e.g., Invoice, Journal Entry) can time out with the default 30-day window. Reduce Window in days to page through smaller date slices.

Increase Window in days for small objects

For low-volume record types, a larger window reduces the number of API round trips and speeds up the sync.

Filter and aggregate inside the SuiteQL query

SuiteQL is capped at 100,000 rows per query. Narrow the WHERE clause or aggregate (e.g., SUM, GROUP BY) in the query itself rather than pulling raw rows and aggregating downstream.

Split one large custom record set across flows

If a single Object or SuiteQL query is consistently slow or times out, split it into multiple data flows by date range or subsidiary and combine the results with Append.

Dashboard accuracy

Match Access Token role across environments

If you maintain separate production and sandbox data flows, make sure both Access Tokens use roles with equivalent permissions — otherwise sandbox exports may be missing objects that production has.

Verify record types support the fields you expect

Custom record types vary in which fields they expose. Run an Object once and check the output columns before building downstream transformations or dashboards on it.

Reconcile against NetSuite for one period first

Before scheduling a recurring flow, compare totals from a SuiteQL query or Object export against the equivalent NetSuite saved search or report for one period to confirm filters and date logic match.

Common pitfalls to avoid

Do

• Scope the Access Token's role to only the records you need
• Use Start date on objects that support incremental sync
• Aggregate and filter inside SuiteQL queries to stay under the row cap
• Save the Consumer Secret and Token Secret immediately when NetSuite generates them

Don't

• Don't assume Start date filters every object — records without a last-modified field always sync in full
• Don't expect SuiteQL to return more than 100,000 rows in one query
• Don't reuse an Administrator-level token when a scoped role would do
• Don't forget the sandbox suffix on the Realm when connecting to a sandbox account