Integrating NetSuite With MuleSoft

NetSuite stands as a cloud-based enterprise resource planning (ERP) software suite designed to streamline various core business operations within a unified platform. Offering a robust set of features spanning financial management, accounting, customer relationship management (CRM), inventory management, eCommerce, and more, NetSuite proves to be a comprehensive solution for businesses.

Key aspects to note about NetSuite include:

Functionality: NetSuite encompasses a wide array of tools, covering areas such as accounting, finance, inventory management, and eCommerce. Cloud-Based: The software operates entirely in the cloud, eliminating the need for on-premises hardware and software installations. Scalability: NetSuite is easily scalable, accommodating the evolving needs of growing businesses. Customization: Businesses can extensively tailor NetSuite to suit their specific requirements, owing to its high level of customization. Integration: NetSuite seamlessly integrates with various third-party applications, allowing businesses to optimize their operational processes.

In this discussion, we will explore the NetSuite connector, which facilitates SOAP-based integration. Additionally, MuleSoft offers the NetSuite Restlet Connector for achieving REST-based integration.

This blog delves into the comprehension and functioning of these NetSuite Connectors, highlighting their key operations:

  • 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: Modifies an existing record.
  • Upsert: Adds a new instance or updates a record instance in NetSuite.

Before embarking on the integration journey, it is imperative to add the necessary dependencies and modules of the NetSuite Connector to your project. The following steps serve as a guide:

  1. Integrate the NetSuite Connector module from Anypoint Exchange into your project.
  1. The NetSuite Connector module has been successfully incorporated into the existing project. Before delving deeper into the connectors, it is essential to familiarize oneself with certain terminologies to ensure a seamless integration of NetSuite using MuleSoft.


  • Internal ID: Generated when a record is created in NetSuite, this ID serves as a unique identifier for that specific record.
  • External ID: The externalId attribute of a RecordRef enables the referencing of an object by its foreign key in an external database. It is mandatory to specify this attribute when performing an Upsert operation.
  • Record: In NetSuite, a custom record is an object type that allows a NetSuite administrator or developer to group, structure, and link sets of custom fields in diverse ways to meet the unique needs of the business.
  1. Connector Configuration:a. Create a global connector configuration for NetSuite, which remains accessible and utilized throughout the project in the global elements.b. Populate the necessary configuration details, including Consumer Key, Consumer Secret, Token ID, Token Secret, and Account ID.c. Best Practices – It is advisable to externalize the properties and store them in properties or YAML files. Additionally, encrypting the properties is recommended to ensure the security and protection of valuable information.Note: Opt for WSDL version v2021_1 or higher, as recent bug discoveries have been made in the previous versions.

Completing this process will finalize the configuration of your NetSuite Connector. To verify the accuracy of the credentials, perform a test connection.

Note: If you pass the key as a runtime property, the test connection may fail. To prevent this, create a global property for the key-value pair that you pass at runtime.

Steps for preparing a SOAP Payload for NetSuite:

  1. Identify the record type and refer to NetSuite documentation for the same. NetSuite Documentation Link
  2. Extract the necessary namespaces for the identified record type from the documentation and include them while constructing the payload.
  3. Ensure the correct field hierarchy when specifying fields; otherwise, you may encounter a NETSUITE: SOAP_FAULT indicating an inability to initialize an abstract type.

Add Operation: The Add operation enables the creation of a new record of the specified type in both the connector configuration and the payload.

For instance, when using the Customer type, employ the Transform Message before the Add Connector to retrieve the metadata of the record.

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

The successful response from the Add operation is presented in XML format. Nevertheless, for customization based on requirements and to retain attributes, transform it to JSON by employing writeAttributes=true as a writer property alongside your chosen output MIME type.

Get Operation: The Get operation facilitates the retrieval of a record by providing either the Internal ID or External ID of the record. However, if the provided ID is not present in NetSuite, it will result in a NETSUITE: NETSUITE_ERROR, accompanied by the description “invalid key or ref.”

During the execution of the Get operation, it is essential to specify 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.

Various types of searches are available, depending on the record type. For example, for the Customer record, there are CustomerSearch, CustomerSearchAdvanced, CustomerSearchBasic, CustomerSearchRow, and CustomerSearchRowBasic, among others.

The payload for conducting a Search operation on a Customer should be structured as follows:

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 for preparing the payload for Add, Update, or Upsert operations with Custom Fields:

Consider the example of a custom field:

plaintextCopy code

StringCustomFieldRef__custitem_adc_item_status: “active”

  1. The type of custom field is represented by StringCustomFieldRef, indicating that it stores string values. Various types of custom fields include: a. StringCustomFieldRef – String b. DateCustomFieldRef – Date c. BooleanCustomFieldRef – Boolean d. SelectCustomFieldRef – List or Object
  2. The script Id of the custom field follows; in this case, custitem_adc_item_status. Script Id can also take forms like: a. custcol b. custbody c. custitem
  3. Finally, “active” represents the value assigned to the custom field.

To include, update, or upsert this value, the payload should be structured in the following format:

MuleSoft and NetSuite excel in their respective domains, emphasizing the importance of achieving compatibility and smooth integration. We trust that this blog will serve as a valuable resource to aid in attaining this common objective. Explore additional MuleSoft Technical Guides at the Caelius Consulting Resource Center.