Upgrading WSDL Versions
NetSuite customers typically upgrade their WSDL when a new version offers features that address a specific business requirement. They also upgrade when NetSuite announces the end of support for their current WSDL version. For more details, see Support for Existing WSDL Versions. When you upgrade the WSDL you are using, it's best to upgrade to the latest available version to prolong the life cycle for your integrated application.
You are not always required to upgrade your WSDL when your NetSuite account is upgraded. However, when your account is upgraded, you should re-test all existing integrations to ensure they work against the latest version of NetSuite (see Testing After a NetSuite Upgrade for details). Also, you should consider that when your NetSuite account is upgraded to the newest version, the oldest available WSDL is automatically retired and stops working. You must upgrade your WSDL before NetSuite retires it. See Support for Existing WSDL Versions for more details.
For help with upgrading your WSDL, reach out to your integration's developer, as each application has its own upgrade process.
After a WSDL upgrade, your development environment will show any API incompatibilities between the old and new versions. You won't be able to proceed with unit testing until you've resolved any compilation errors in your IDE. So, most WSDL upgrade issues are typically resolved during the development phase.
A WSDL upgrade might require re-coding parts of your integrated application to ensure compatibility with the latest NetSuite version. You might need to re-code due to various reasons, including:
-
A new required field has been added to NetSuite.
-
A field that was optional in previous versions of NetSuite becomes required in the latest version.
-
A field that is referenced in your integration has been removed from NetSuite.
-
The data type for a field has changed.
-
The method signature changes for a SOAP web services operation that is used in your integration.
-
The authentication method has changed.
See Working with the Araxis Merge Diff File for information about how to use Araxis to see the changes made from one WSDL version to the next. You can also get an idea of the types of changes you must make by reading the release notes from the endpoint you are currently using onwards to the last release of the WSDL.
Testing After a WSDL Upgrade
When upgrading your WSDL to use a new NetSuite feature, start by exploring how it works in the UI. In most cases, Generally, NetSuite SOAP web services mirrors the UI, making it easier to understand how features work programmatically. Therefore, familiarizing yourself with a feature in the UI will reduce the time it takes to learn how to use it in SOAP web services.
Note that WSDL upgrades require significant planning and testing. Consequently, you might choose to upgrade only when your current version is nearing retirement. (See Support for Existing WSDL Versions for more information.)
Testing After a NetSuite Upgrade
NetSuite aims to maintain backward compatibility from one NetSuite version to the next. However, custom workflows in your integration might be affected when your NetSuite account is upgraded. Therefore, you should test all existing integrations in your Release Preview account for the NetSuite upgrade and report any issues you may find to ensure a smooth upgrade of your production account.
In your Release Preview account, you also must modify the WSDL references you are using in your application to point to one of the following endpoints (based on the endpoint you are currently using):
You can access the UI for your Release Preview account from https://system.netsuite.com. Initially, only users with an Administrator role have access to the Release Preview account. For more information, see The Release Preview Account.
-
https://webservices.netsuite.com/wsdl/v2025_1_0/netsuite.wsdl
-
https://webservices.netsuite.com/wsdl/v2024_2_0/netsuite.wsdl
-
https://webservices.netsuite.com/wsdl/v2024_1_0/netsuite.wsdl
-
https://webservices.netsuite.com/wsdl/v2023_2_0/netsuite.wsdl
-
https://webservices.netsuite.com/wsdl/v2023_1_0/netsuite.wsdl
-
https://webservices.netsuite.com/wsdl/v2022_2_0/netsuite.wsdl
-
https://webservices.netsuite.com/wsdl/v2022_1_0/netsuite.wsdl
-
https://webservices.netsuite.com/wsdl/v2021_2_0/netsuite.wsdl
-
https://webservices.netsuite.com/wsdl/v2021_1_0/netsuite.wsdl
-
https://webservices.netsuite.com/wsdl/v2020_2_0/netsuite.wsdl
-
https://webservices.netsuite.com/wsdl/v2020_1_0/netsuite.wsdl
-
https://webservices.netsuite.com/wsdl/v2019_2_0/netsuite.wsdl
-
https://webservices.netsuite.com/wsdl/v2019_1_0/netsuite.wsdl
-
https://webservices.netsuite.com/wsdl/v2018_2_0/netsuite.wsdl
If you are engaged with a partner for any of your SOAP web services integrations, you should contact them and inform them of when your Release Preview account will be available. They can then set up a time with you and a test plan for the integration.
Working with the Araxis Merge Diff File
Use the Araxis diff file in the release notes to compare the latest WSDL with its predecessor. In the diff file, begin by investigating the records you're currently working with. For example, if your application uses customer and vendor records, check the diff file for updates to these records. Look for changes like new or removed fields, or changes to field data types.
ITo compare the latest WSDL with your current version, download Araxis and compare it with any version available on the Developer Portal.
For more information about using the Araxis diff file to review NetSuite WSDL changes, see Araxis Merge Diff File for the 2025.1 Endpoint in the 2025.1 Release Notes.