A Guide to Integrating with NetSuite’s API

NetSuite is one of the top cloud-based ERP systems, used globally to power a wide array of businesses and programs. For those who look to integrate with NetSuite successfully, building and maintaining integrations, particularly native ones, can be complex - NetSuite is highly customizable with several distinct APIs, all of which have their own best use cases for your needs. 

At Pandium, we have significant experience developing robust, native integrations, including between NetSuite and other major platforms.

The complexity of ERP platforms in general, combined with the plethora of customization options in NetSuite can lead to unique challenges. In this article, we aim to help inform any NetSuite integration plans you might have by explaining some general NetSuite knowledge, as well as highlight some of the insights we’ve gathered through our work.

No matter what applications you’re trying to build, there are several decisions you’ll need to make for any new integration:

Select Authentication Method 

There are three ways NetSuite allows you to authorize requests to their APIs.

User Credentials:

All NetSuite documentation discourages use of this auth method. The REST API doesn’t support it. Up to date netsuite accounts can’t use RESTlets that rely on user credentials. So we won’t say more about this non-option.

Token-based authentication (TBA): 

This is just NetSuite’s term for OAuth 1.0. With TBA you combine 5 credentials that do not expire into a signature for each request. It’s generally easiest to let a library handle the signature creation. If you’re working in JavaScript or TypeScript oauth-1.0a works well. 

Here are some tips to make sure you feed your library the correct values for each of those five secrets:

• In some cases the names Netsuite gives to those credentials may not be what you would expect from OAuth 1.0 documentation, so here’s a quick translation:

• If you’re using a sandbox or test NetSuite account, it will usually have some kind of suffix on the company id.
  ‍
  For example in the url you might see https://123456-sb1.app.netsuite.com
  ‍
  When building an OAuth1 signature the account ID would be the realm, and it would need to be referenced in the following way: 123546_SB1. Note that the letters are capitalized and the hyphen has been replaced with an underscore.
  

Look at Get API credentials for your NetSuite Account to see how to get each element needed to complete an OAuth1 signature. 

OAuth 2.0

OAuth 2.0 is the most standard and modern way of authorizing requests, though notably it isn’t supported by NetSuite’s SOAP API. It is more secure because the access tokens expire regularly. 

The tradeoff for that added security is the complex process for obtaining OAuth 2.0 access tokens and refreshing them when they expire. Get API credentials for your NetSuite Account below briefly describes this.

If you have never set up an OAuth 2.0 flow it might be simplest to use token-based authentication.

If you’re determined to have the added security of OAuth2.0 but can’t build the infrastructure to support it, talk to Pandium; there are many OAuth2.0 APIs our product already supports by:

• Creating the custom url at which users approve the integration’s access.
• Receiving the temporary authorization code and exchanging it for the access token.
• Storing refresh tokens and regularly exchanging them for new access tokens.

Select NetSuite API

Netsuite has three different APIs, each with their own strengths and capabilities.

RESTlets

A RESTlet is a script installed on a NetSuite account that runs when an external application calls it. Once a user has deployed a RESTlet’s script to an account, NetSuite provides its URL. Users can call that URL from an integration to run the RESTlet’s logic, which can return data to the user in the form of plain text or JSON.

RESTlets must be written in ‍‍SuiteScript, a custom scripting language based on JavaScript.

Advantages to using RESTlets:

• Because a RESTlet runs within NetSuite its interactions are faster. 
• It is an efficient use of the limited calls NetSuite allows to their API because one call to a RESTlet URL can kick off a suiteScript that performs many NetSuite interactions. Here is an example from NetSuite’s documentation.
• The NetSuite developer community is pretty SuiteScript-oriented, so when you’re searching for solutions you'll find more examples and Stack Overflow answers that are directly applicable

Drawbacks to using RESTlets:

• It must be written in SuiteScript as opposed to an engineer’s language of choice.
• They do not allow the deletion of records.
• When business growth is the purpose of your integration, it’s important that one configurable integration can be easily installed on many different accounts, and RESTlets make that hard.
  
  • Each RESTlet must be uploaded and deployed to every NetSuite account that installs the integration. The main way to do that is with the manual UI. 
  • That is a tedious set up process which doesn’t leave a path for easily updating logic within the RESTlets across many accounts at a later time.
  • The SOAP API offers a potential workaround because it allows for the creation of file objects. If you can use that to programmatically install and update RESTlets across many NetSuite accounts then a RESTlet based integration could help you grow your business, but it would not be simple.

‍Bottom line: You should probably use the RESTlets if this describes your project

• Speed is important.
• Your integration only needs to work with one NetSuite account.
• Your integration needs to write (but not delete) NetSuite records.

SOAP

‍While SOAP is generally considered a pretty old way to arrange an API in comparison to REST, when it comes to NetSuite it can be more reliable. We've found the SOAP API covers more features, especially when it comes to writing data. Here are some examples:

• The SOAP API can perform all interactions, unlike RESTlets which cannot delete records.
• All fields can be referenced in a SOAP request. This is not always true for the REST API.
  
  • Example: We were working with a NetSuite account that had implemented custom sublists for their item fulfillment packages. One side effect was that a newly created item fulfillment would only include tracking information if the payload specified its custom package type. The REST API did not have a way to do that, but the SOAP API did.  
• There are records the SOAP API can create and work with that are not covered in the REST API. One example is the file object we mentioned above which could be used to programmatically create RESTlets.

Drawbacks:

• It does not support SuiteQL, which is the fastest way to read information from NetSuite; you can read more about it in rate limiting section of Integration Best Practices with NetSuite 
• Current Built For NetSuite (BFN) requirements actively discourage SOAP, so if certification is on your roadmap, plan around it from the start
• It doesn’t support OAuth 2.0, so you won’t be able to onboard any new installation of your integration after the start of 2027.

Tips for working with SOAP

• In SOAP protocol, metadata is stored in the WSDL and XSD files. Your code can pass the WSDL into a SOAP library to get a comprehensive lightweight NetSuite Client.
• When it comes to reading about what your SOAP payloads should look like, don’t use the WSDL or XSD files. The NetSuite SOAP Schema Browser allows you to view the same information in a much more human-readable format.
• When deciding whether to use a List SOAPAction be aware of what it does and does not give you:
  
  • A list SOAPAction, such as addList in place of add, allows you to request the creation of many NetSuite records in one HTTP request, so it can be useful if you’re bumping up against concurrency limits.
  • The elements within a list request are processed by NetSuite in sequence, not in parallel, so it does not help an integration run faster. 

‍Bottom line: You should probably use the SOAP API if this describes your project,

• You don’t need BFN certification.
• You want your integration to work with multiple NetSuite accounts, some of which may have customizations.
• Your integration needs to write to NetSuite.

REST

The main reason to use REST is obvious; it’s what most modern developers are familiar with. 

That’s probably why NetSuite has expanded the functionality of this API in recent years. However its coverage isn’t quite complete. For example, you will run into issues if you’re working with legacy tax features or trying to create records that have custom sublists.

Apart from that you’ll find it pretty straight-forward to use for write operations.

When it comes to reading data, you will need to be a little more thoughtful because most of the REST endpoints use HATEOAS. This means they only give a top-level view on items, so you often need to make several queries to get all the information for one record.

Why HATEOAS is Inefficient

Below is an example of a HATEOAS response for this GET order:

‍

HATEAOS Response:

This response gives us information about an order, but what if we want to know which items are on the order?

Then we need to make the following GET request to the HATEOAS REST API:

‍

After, we'll receive this response:

‍

This response tells us how MANY items are on the order (i.e. 2), and what end points we can use to get the detailed information about those items:

So, as you can see, we need to make 4 GET requests to NetSuite to get some pretty basic information about this order with two items. That's very inefficient, especially when you consider you probably want to get information about many orders.

‍The good news is that the REST API also has the query endpoint which accepts read requests written in SuiteQL. There is a bit of a learning curve in using SuiteQL, but it’s the fastest way to read information from NetSuite.  Check out the rate limiting section of Integration Best Practices with NetSuite below to learn how it can get around the HATEOAS read difficulties we just explored.

Bottom line: You should probably use the REST API if this describes your project:

• Your integration needs to work with multiple NetSuite accounts, none of which use custom features like sublists.
• Speed of reading NetSuite records is important, assuming you’re willing to use suiteQL.

Now that we’ve explored each of the three API options lets do a quick side by side comparison:

‍

Keep in mind that you can choose to use more than one API. We’ve written integrations that read using the suiteQL with the REST API and write using the SOAP API

Get API Credentials for your NetSuite Account:

Once you’ve decided how you will auth your requests to NetSuite and which API to use, you’ll have to take care of these tasks to get all the credentials you need.

Configure your NetSuite Account for your selected auth method and API(s).

What: Enable the appropriate features in your NetSuite Account.

Why:  This allows the choices you’ve made for Auth and APIs to work.

How: Go to Setup > Company > Setup Tasks > Enable Features

Create the integration record in NetSuite.

What: In this step you specify authentication methods and callback URLs.

How: Go to Setup > Integration > Manage Integrations > New.

Why: Once this is complete NetSuite will give you either of the following: 

• The consumer key and consumer secret. In Token-based authentication these are part of the credentials needed for all requests.
• The client ID and client secret. In OAuth 2.0 these are needed to get an authorization code and access token.

Create a role to use with the new integration.

What: This is when permissions are determined. If you’re not sure how to choose the permission you need check out the security section under Integration Best Practices with NetSuite later in this blog. At minimum, assign the Log in Using Access Tokens permission under the Setup subtab.

Why: When NetSuite issues an access token it is tied to a user and their role.  The permissions of the role determine what that token is authorized to access.

How: Go to Setup > Users/Roles > User Management > Manage Roles

Assign the role to the user who will request the access token.

What: This creates the relationship between the user and a role.

Why: Access tokens get their permissions from the user's assigned role, so the user must have the role before a token can use it.

How: Go to Lists > Employees > Employees, Click edit for the user, go to the access tab and assign the role.

Use the role with the netsuite integration record to get a token.  The way to do this varies based on how you’ve chosen to auth your requests to NetSuite.

OAuth2.0:

What: This uses the client ID from the first task and the credentials of the user with the new role to create an OAuth 2.0 access token.

Why: To use OAuth 2.0 authentication for a request the access token must be in the authorization headers.

How: 

• Make a GET request to the authorization endpoint https://[accountID].app.netsuite.com/app/login/oauth2/authorize.nl‍
  
  • This requires the client ID from the first task as a param.
• Once the user has logged into NetSuite, selected a role, and approved the access request, NetSuite sends a temporary authorization code to your redirect_uri.
• Your redirect_uri is responsible for making a POST request to the token endpoint https://[accountID].suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token‍
  
  • The headers of this request need to be Base64url encoded with the client ID & secret from the first task.
• NetSuite will respond with the access token!

Token-based authentication:

What: This step combines the newly created integration, the role, and a user to get a token ID & token secret.

Why: To use token-based authentication for a request the token ID & token secret are needed (along with the Integration consumer key & consumer secret from the first task). 

How: Go to Setup > Users/Roles > Access Tokens.

Integration Best Practices with NetSuite

Armed with those credentials you can start making requests and writing your integration.  As with any integration, it is important to consider rate limiting, security, and scalability, so here are some tips for doing that with your NetSuite integration.

Rate Limiting

NetSuite's rate limits are relatively low unless the account is on a premium tier, so keeping request frequency low is critical. A chatty integration that requires a lot of API calls per record will be slow.

This means you want to get the most out of every HTTP request you make.  When we’re reading NetSuite data, we’ve found SuiteQL is the best way to do this.

‍SuiteQL is NetSuite’s query language for reading info across its data model.  You can use it through the REST API’s query endpoint, or through the N/query module if you’re writing a RESTlet.

Earlier we discussed an example where four HATEOAS REST requests were needed to get all the info for one record. Now I’ll show how SuiteQL can give us the same info with just one request.

POST Request:  https://<COMPANY ID>.suitetalk.api.netsuite.com/services/rest/query/v1/suiteql?limit=200

Response (scroll to see the entire response):

‍

You can be granular with the fields you get, and easily make joins to append fields from their other kinds of records. This can be accomplished with one request, as opposed to the many requests you’d need to do with the HATEOAS constraint.

You might initially be intimidated by the prospect of writing your own SuiteQL queries, but there are resources to make this easier.

The Records Catalog is a great reference to show which records exist, what fields they contain, and how records are related to one another.

Because its content can vary based on how a NetSuite account is configured, you need to be logged into an account to access the records catalog. For example:

• It will include fields and records custom to a NetSuite account.

• When certain features are disabled, some tables and columns will cease to exist. 

This has a practical consequence for error handling: If your suiteQL references a custom field that doesn’t exist for the account, you’ll get an error. The same is true if your query tries to access a field or record when the role for your token doesn’t have permission for it. NetSuite won't tell you it's a permissions issue. It will just say the field or record doesn't exist.

If you’re writing an integration meant to run across many different NetSuite accounts, this means your query logic can't be static. You may need to build SuiteQL queries dynamically based on each account's configuration. Here’s a situation where we’ve done that.

Our users wanted to export info from the custom fields on their sales order transactions. Since every account had different custom fields, we added a setting that let users select which fields to include, then passed those selections to this function that built the SuiteQL query dynamically. (scroll to see the entire function):

‍

SuiteQL won't solve every rate limit problem, but it's the single best tool for keeping your read operations lean. 

Security

Regardless of how you choose to authorize a request to the NetSuite API, the authorization will be tied to a user and their role. The permissions of that role determine what the API request will have access to, so it is important to select the correct permissions.

If too many permissions are assigned to a role, you are reducing security by exposing more of your NetSuite account than is needed.  If too few permissions are assigned, your integration will not work because it won’t be able to access or edit all the necessary records.

During initial development, an administrator role is most helpful.  When first writing the integration you may not yet know which records you’ll need access to.  The administrator role has access to all records; using it ensures that you won’t be stopped with permissions issues while writing the integration.

During development you’ll identify the specific records and fields you'll need to work with. You’ll use that to hone in on the proper permissions once you’ve finished writing the bulk of your integration.

Narrowing the admin permission to just those needed for your integration can be difficult especially when managing multiple NetSuite accounts and integrations. These two tools have been helpful for us in navigating this:

• The Records Catalog can provide some guidance to which list and transaction permissions may be needed. Each record table has a 'Permissions' column. When accessing a particular record’s field requires a specific permission, it will be listed in that column.

• NetSuite has a feature that lets you view the permission difference between two roles (Setup > Users/Roles > Show Role Differences). This can be helpful when you’re trying to pinpoint why the integration works with one role and not with another.

Getting permissions right is an iterative process, so don't expect to nail it on the first try. The goal is to end up with a role that's as narrow as possible while still letting your integration do its job.

Scalability

A NetSuite integration that works fine in testing can fall apart in production when it's suddenly processing thousands of records instead of dozens. Here’s the key question to ask yourself: if a run can't finish everything in one pass, will the next run know where to pick up?

There are two ways to make sure each run knows which records have not yet been processed.

Tag processed records

Each time the integration finishes processing a record from NetSuite, update that record to mark it processed. The custom fields NetSuite lets you create make this pretty simple. Then you can use SuiteQL to efficiently fetch a list of records based on the value of a custom field.

One great advantage of this strategy is that any record which errors in one run will automatically be retried in the next run.

There are some trade offs though:  

• Each user will need to add that custom field to their account when they install the integration. 
• Updating that field requires the integration to make an extra NetSuite call for each record.  That slows things down a lot.

Pass date of last processed record to next run

There are three elements to this strategy:

• Process records from oldest to newest, keeping track of the most recent record’s date.
• At the end of each run pass forward the date of the last record successfully processed.
• The next run should only fetch records with a date newer than the one provided by the previous run.

This strategy relies on being able to pass a piece of context from one run to the next. This feature is built into the Pandium platform.

Here’s a quick comparison so you can decide which option is best for your project.

‍

If you’d like to learn more about either of those strategies check out our article on writing integrations that handle extreme volumes. 

Need More Support with Your NetSuite Integration? We're here to help!

The NetSuite platform is powerful, and their APIs are great tools for developing and automating business processes. With the right knowledge, and guidance around the many NetSuite idiosyncrasies, you can create streamlined operations and build robust apps to service a wide array of customers.

If you'd rather not go it alone, reach out to us at Pandium. We've built complex, native integrations across a wide variety of systems.  Here are just some of our platform’s features that make it easier to tackle NetSuite:

• Built-in connection settings page: this lets each of your users configure the integration to their specific needs.
• Infrastructure to support secure authentication: both OAuth 2.0 and token-based (aka OAuth 1.0)
• Persistent context between runs: your integration can pass data from one execution to the next through standard out, making it easy to implement resumable, stateful workflows.

And beyond the platform itself, we're happy to share what we've learned structuring multi-account integrations that handle per-account configuration gracefully.