1. SuiteCloud Platform
  2. SuiteTalk Web Services
  3. SuiteTalk SOAP Web Services Platform Guide
  4. SuiteTalk SOAP Web Services Platform Overview
  5. NetSuite WSDL Versioning
  6. Upgrading WSDL Versions

Upgrading WSDL Versions

NetSuite customers typically upgrade their WSDL when a newer version includes functionality that enables them to meet a particular business need. They will also upgrade their WSDL when the one they are currently using is going to be retired by NetSuite (see Support for Existing WSDL Versions for details). If you do plan to upgrade the WSDL you are using, you should upgrade to the latest available version to prolong the life cycle for your integrated application.

Important:

You are not 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).

After upgrading your WSDL version, any API incompatibilities between the new and old versions will be displayed in your development environment. You will be unable to proceed to unit testing until you have fixed any IDE compilation errors. Consequently, most WSDL upgrade issues are usually addressed during development.

Upgrading your WSDL version may require you to re-code parts of your integrated application to be compatible with the latest version of the NetSuite product. Re-coding may be due to any of the following reasons:

Note:

See Working with the Araxis Merge Diff File for information on 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

If you are upgrading your WSDL to make use of a particular NetSuite enhancement, you should use the UI to learn how the feature works. In most cases, NetSuite SOAP web services is the programmatic equivalent of the NetSuite UI. Therefore, if you know how a feature works in the UI, your learning curve for understanding how to leverage the feature in SOAP web services will be minimized.

Be aware that WSDL upgrades may take considerable planning and testing. Consequently, you may decide to upgrade only when you know your version is going to be retired. (See Support for Existing WSDL Versions for more information.)

Testing After a NetSuite Upgrade

NetSuite strives to maintain backward compatibility from one NetSuite version to the next. However, your integration may rely on unique workflows that might break 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):

Note:

As of 2018.1, all customers access the UI for their 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.

Note:

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

To help you see the differences between the latest WSDL and the version that preceded it, refer to the Araxis diff file provided in the release notes for each release. When reviewing the diff file, start by investigating the records you are currently using. For example, if your SOAP web services application interacts with customer and vendor records, use the diff file to review any changes made to these records. These changes may include added or removed fields or field (element) data type changes.

If you want to compare the latest WSDL with the version you are currently using, you can download Araxis and compare your own version to any other version listed 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 2024.1 Endpoint in the 2024.1 Release Notes.

Related Topics

NetSuite Versioning and WSDL Versioning Overview
Support for Existing WSDL Versions
SOAP Web Services Archives

General Notices