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.

Table of Contents

• Initial Setup and Preliminary Strategic Decisions

• Steps to Configuring the NetSuite Account

• NetSuite APIs and Integration Tools:

                • SuiteScript    

                • RESTlet

                • REST

                • SuiteQL

               • Why HATEAOS is Inefficient

                • SOAP

                • How to Make a Dynamic SuiteQL Query

• More Support for your NetSuite Integrations

Initial Setup

No matter what applications you’re trying to build, there’s a standard set of steps you’ll want to follow to ensure a successful foundation for any new integrations:

Preliminary Strategic Decisions:

Auth 

Selecting an authentication method, e.g. choosing between methods like OAuth 2.0 and token-based authentication.

Select an API

Choose which of the available NetSuite APIs will be useful for your needs - this would be using NetSuites SOAP, REST, or even RESTlets.

Steps to Configuring the NetSuite Account:

1. Create the integration record in NetSuite (the step when you specify authentication methods, callback URLs, and generate the consumer key and secret).

2. Create a role to use with the new integration. This is when permissions are determined. 

• During initial development, an administrator role is most helpful, since during development the specific records and fields you'll need to work with will surface, and that's what will ultimately determine the necessary permissions.  

• Once you’ve finished writing the bulk of your integration, you’ll need to hone in on the proper permissions it requires (instead of just using the administrator-level permissions as you likely did in development). 

This can be difficult especially when managing multiple NetSuite accounts and integrations. We’ve had to use a good deal of trial and error in this, and 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 records 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 different 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.

3. Use the role with the NS integration record to generate the token and token secret (in order to use OAuth1 you need the consumer id and consumer secret AND the token id and the token secret).

4. Pro-Tip: - Once you’ve gone through these basics, you should test your API access and credentials using something like Postman or Insomnia.

• If you’re using a sandbox NetSuite account, it will have some kind of sb suffix on the company id. In the url, that needs to be referenced in the following way: 123456-sb1. In the auth, that same company id needs to be referenced in the following way: 123546_SB1.
• The login audit trail is also a useful tool in resolving auth issues when you’re first connecting.

• NetSuite errors are often unhelpful. For example, a timeout may be surfaced as several different types of errors, including unauthorized errors like a 401.

• Example: If you try to access a field or record via SuiteQL when the relevant role for your token doesn’t have permission for it, it will say that the field/record doesn't exist rather than surfacing a permission error.

5. Set up your code repository by installing and configuring any necessary libraries in the appropriate integration repository. Certain NetSuite APIs require specific libraries in order to use the API. As an example, if you’re using SuiteTalk's SOAP API, you may need to install a SOAP library.

Related Content: Download the State of APIs and Integrations at 400 SaaS Companies

NetSuite APIs and Integration Tools

Let’s look at an overview of the available NetSuite APIs and integration tools that you may use when developing your apps:

1. SuiteScript

‍‍SuiteScript is based on JavaScript, and allows developers to create custom scripts and functions within NetSuite that can be triggered by specific events.

‍

SuiteScript allows for extensive custom logic in NetSuite, including validation, reporting and dashboards customization, and data transformation. And with the ability to trigger on specific events, SuiteScript is a viable tool to automate multiple business processes and workflows within NetSuite.

Related Content: How ShipBob Designs and Scopes Their User-Facing Integrations

‍2. RESTlet‍

A RESTlet is a SuiteScript that executes when called by an external application or  another SuiteScript, that may also return data to the calling application.

A RESTlet can perform any function that can be implemented by using SuiteScript. But with a couple advantages:

• The RESTlet can return data, in plain text or JSON, to the client script.
• The majority of RESTlet calls require a content-type header, which tells NetSuite how your request body will be formatted and how NetSuite should format its response.
• NetSuite requires authentication for RESTlets. If a RESTlet call originates from a client that does not have an existing session in the NetSuite account where the RESTlet is deployed, NetSuite requires the call to include an authorization header.

Note: If searching for advice about how to interact with NetSuite RESTlets, SuiteScript generally arises as a primary solution. 

However, when we were developing we found that these tools didn’t seem to be valid solutions for us because they are written for a single NetSuite account at a time. 

At Pandium, one of our tenets is to enable the capability to manage many NetSuite accounts with just one native, configurable integration. So we turned our attention to some of the other tools NetSuite offers.

Related Content: How to Integrate Systems Like a CTO: 10 Best Practices

‍3. REST

‍Many of NetSuite's REST API endpoints are still in Beta. Even the end points that are in GA only offer a top-level view on items since this API uses the HATEAOS constraint. HATEAOS requires multiple queries for each item, impacting performance.

To access Beta REST endpoints, you must have a NetSuite account, enable the feature in the account permissions configuration, as well as access to the NetSuite Beta Program. Once you see how the HATEAOS set up dictates how to request information from this API you'll probably decide that this isn't the best way to read information from NetSuite.

Why HATEAOS is Inefficient

Below is an example of a HATEAOS 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 HATEAOS REST API:

After, we'll receive this response, which 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.

‍4. SuiteQL

‍SuiteQL is a query language that allows you to query the NetSuite data model; however, it only supports read operations. It’s technically a component of the REST API; often the one that is most valuable for getting information out of NetSuite. 

‍Why SuiteQL is Much Better than HATEAOS

Let's compare SuiteQL to the previous example of HATEAOS. I can make one GET request to the REST API with a SuiteQL query to receive all the information that four GET requests to the HATEAOS REST API gave me.

GET Request:

Response:

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

You might initially be intimidated by the prospect of writing your own SuiteQL queries, but there's are lots of resources to make this easier! The Records Catalog is a great reference to show which records exists, what fields they contain, and how records are related to one another.

The Records Catalog shows the kinds of records that exist, what fields are on each record, and how different kinds of records are related. 

Because its content can vary based on how a NetSuite account is configured, so one needs to be logged into a particular NetSuite 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 will naturally cause failed queries and surface various errors. Creating dynamic queries helps to counteract this possibility, and is worth looking at, especially with non-standard integration configurations. 

‍5. SOAP

‍While SOAP is generally considered a pretty old way to arrange an API, when it comes to NetSuite that happens to mean it is more reliable.  We've found the SOAP API is more useful than the REST API for writing information into NetSuite.

• All fields can be referenced in a SOAP request. There are some features on a record that the REST API doesn’t allow access to (even if the record is in GA and not just Beta)
• Example: An item fulfillment will not register tracking information if the item fulfillment payload does not specify which type of package the item fulfillment is using. The REST API only allows one to specify a generic package. The SOAP API allows one to reference all the package types (generic, UPS, USPS, and FedEx)
• If you are encountering rate limiting issues, try reducing the frequency of your API requests, by making requests that reference many records at once rather than many requests which each reference one record. The SOAP API allows for such bulk create or update requests.

Here are some tips for getting comfortable with using their SOAP API:

• SOAP supports TBA authentication, which is OAuth1.  For TBA authentication, you first need to create a NetSuite integration and Access Token, and then go through the standard OAuth1 process.
• In SOAP protocol, metadata is stored in a WSDL file. One of the limitations with WSDL is that you only get standard objects and standard fields.
• If you want to get custom records or fields using the SOAP API you can create a custom RESTlet using SuiteScript. You can also use custom entities/fields in your SOAP requests without a custom RESTlet if you know their names and types.
• NetSuite also provides their SOAP Schema Browser that allows you to view the information (from the WSDL and XSD) in a much more human-readable format that can help formulate proper SOAP payloads.

‍

How to Make a Dynamic SuiteQL Query

What if the user wants the option to get additional transaction fields? Then you'll need to be able to change the SuiteQL query you send to NetSuite based on how the user has configured the integration. For example, this could look like:

‍

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 need assistance with a NetSuite integration project, or just don't want to deal with it yourself, reach out to us at Pandium. Our team has the experience and knowledge developing complex, native integrations across a variety of systems, and we can help you get the most out of NetSuite to accomplish your business goals.