MuleSoft Technical Guides

NetSuite Integration using MuleSoft

User MuleSoft Integration Team
Calendar January 04, 2024

NetSuite is a cloud-based enterprise resource planning (ERP) software suite that helps businesses manage their core operations in one place. It offers a wide range of features for financial management, accounting, customer relationship management (CRM), inventory management, eCommerce, and more.

Here are some key things to know about NetSuite:

  • Functionality: It provides a comprehensive suite of tools for everything from accounting and finance to inventory management and eCommerce.
  • Cloud-based: It is fully hosted in the cloud, eliminating the need for on-premises hardware and software installations.
  • Scalability: It can be easily scaled to accommodate the needs of growing businesses.
  • Customization: It is highly customizable, allowing businesses to tailor the software to their specific needs.
  • Integration: It integrates with a wide range of third-party applications, allowing businesses to streamline their operations.


Here we’ll discuss NetSuite connector which allows us to achieve SOAP-based integration. However, MuleSoft does have NetSuite connector which allows us to achieve REST-based integration which is known as NetSuite Restlet Connector.

In this blog, we are going through the understanding and working of these NetSuite Connectors:

  • Add – Creates a new record.
  • Get – Retrieves a record by providing the unique ID that identifies the record.
  • Search – Executes a search for a specific record type based on a set of criteria.
  • Update – Updates an existing record.
  • Upsert – Adds a new instance or updates a record instance in NetSuite.


Before getting started, we need to add the dependencies and module of the NetSuite Connector to our project. The following steps will get you started:

1. Add NetSuite Connector module from Anypoint Exchange to your project.

2. We have successfully added the NetSuite Connector module to the current working project. Before diving deep with the connectors, there are a few terminologies that one needs to know for smooth integration of NetSuite using MuleSoft.


  • Internal ID: When a record is created in NetSuite, it generates an ID which is used to uniquely identify that record.
  • External ID: The externalId attribute of a RecordRef provides a means to reference an object by its foreign key in an external database. It is mandatory to mention while performing an Upsert operation.
  • Record: A custom record is an object type in NetSuite that allows a NetSuite admin or developer to group, structure, and link sets of custom fields in an almost infinite number of ways to meet the unique needs of the business.


3. Connector Configuration:

a. Create a global connector configuration for NetSuite which will be accessible and used throughout the project in the global elements.

b. Fill in the required configuration details such as Consumer Key, Consumer Secret, Token ID, Token Secret, and Account Id.

c. Best Practices – We should always externalize the properties and store them properties or yaml files, also we should encrypt the properties to ensure that the valuable information is secure and protected.

Note: Select the Wsdl version as v2021_1 or higher as there has been recent discovery of bugs in the previous version.

Doing this will complete the step of configuring your NetSuite Connector and to check if the credentials are correct, test your connection.

Note: If you’re passing the key as runtime property, then the test connection will fail. To ensure that test connection doesn’t fail, create a global property of the key-value pair that you’re passing in runtime.

Steps to prepare a SOAP Payload for NetSuite:

1. Identify the type of record and search for the same on NetSuite documentation.

2. Fetch the required namespaces for the type of record after opening it and mention the same while preparing the payload.

3. Ensure the level of the fields while mentioning them or else you’ll face NETSUITE: SOAP_FAULT saying you can’t initialize an abstract type.

Add Operation

Add operation allows to create a new record of the type that we mention in the connector as well as in the payload.

Here, for example we are using type Customer, drop the transform message before Add Connector to fetch the metadata of the record.

This is how the payload for Adding a Customer should be structured:

The response of successful add operation is returned in XML. However, we can transform it to JSON as per requirement and to not lose the attributes, use writeAttributes=true as writer property beside your output MIME type.

Get Operation

Get operation allows to retrieve a record by providing the Internal ID or External ID of the record. However, if the ID passed isn’t present on NetSuite it’ll throw NETSUITE: NETSUITE_ERROR with the description invalid key or ref.

While performing Get operation we need to select the Ref Type and Type.

This is how the payload for performing a Get operation on Customer should be structured:

Search Operation

Search operation allows us to perform a search on a particular type of record based on the set of criteria.

There are various types of Search available based on the type of record such as for Customer there are CustomerSearch, CustomerSearchAdvanced, CustomerSearchBasic, CustomerSearchRow, and CustomerSearchRowBasic etc.

This is how the payload for performing a Search operation on Customer should be structured:

Update Operation

Update operation allows to update an existing record hence passing the internal ID is a must while performing an update operation. If the internal ID is not passed it’ll throw NETSUITE: NETSUITE_ERROR with the description invalid key or ref.

This is how the payload for performing an Update operation on Customer should be structured:

Upsert Operation

Upsert operation allows us to add or update a record, if present. While performing Upsert, passing external Id is must and we shouldn’t pass the internal Id or else one might face the error NETSUITE: NETSUITE_ERROR with description that record does not exist.

This is how the payload for performing a Upsert operation on Customer should be structured:

Steps to prepare payload for Add, Update, or Upsert having Custom Fields

For example, this is the custom field,
StringCustomFieldRef__custitem_adc_item_status: “active”

1. The StringCustomFieldRef is the type of custom field, which represents it stores string values. Different types of custom field are:

a. StringCustomFieldRef – String
b. DateCustomFieldRef – Date
c. BooleanCustomFieldRef – Boolean
d. SelectCustomFieldRef – List or Object

2. Followed by custitem_adc_item_status is the script Id of the custom field. Script Id can also be in the following way:

a. custcol
b. custbody
c. custitem

3. And “active” being the value of the custom field.

Now, to have this value added, updated, or upsert, the payload needs to be structured in this format:

MuleSoft and NetSuite are the best in their respective fields. It is critical to achieve compatibility and seamless integration. We hope that this blog will help us achieve the same goal. Find more MuleSoft Technical Guides at Caelius Consulting Resource Center.

Leave a comment

Your email address will not be published. Required fields are marked *