Development Considerations Overview

Before you begin writing SOAP web services applications, you should be aware that SOAP web services adhere to the same role-based permission structure enforced in the NetSuite UI. Because a SOAP web services application needs a pair of sign-in credentials to login, its permission to various operations and records is subjected to the role it uses, like it would when it is used for a browser session. For example, a SOAP web services application that logs in with the Accountant role will receive the same permissions as it will logging in to the browser interface using the same role.


See Roles and Permissions in SOAP Web Services for additional details.

Another characteristic of SOAP web services is that its behavior is very similar to that of the NetSuite UI. The workflow of a SOAP web services application and its underlying SOAP exchange with NetSuite tightly mimics the browser interface. For example:

  1. A successful login operation must be performed to obtain a session to perform any subsequent operations. (See the documentation on SOAP web services Authentication for SOAP Web Services for more details.)

  2. Some add operations are done in a tandem, such as loading an existing sales order to gain the context and then adding a new item fulfillment record. The loading of the sales order (using the initialize API) is the first operation; adding the item fulfillment record is the second.

  3. Restrictions and requirements on custom forms are honored in SOAP web services. Therefore, a SOAP application's attempt to set a field that is hidden on a form results in a permission error. Likewise, as in the UI, a SOAP application must set fields that are required on the form it is using.

The combination of permission adherence and similar behavioral patterns between SOAP web services and the NetSuite UI provides a consistent and predictable platform for developers.


When you are unsure of how to achieve something with SOAP web services, try observing how it is done in the UI, then replicate it programmatically.


A SOAP web services application should use the response object to handle any errors, if any, generated by a Web service operation.


SOAP web services use the HTTP protocol, therefore service interruptions can occur from time to time. If you receive an HTTP 503 error (Service Unavailable), try sending your SOAP web services request later.

Related Topics

NetSuite Features in SOAP Web Services
SOAP Web Services Reliability Considerations
Effects of Account Configuration in SOAP Web Services
Enumerations, Special Characters, and Character Encoding
Image References in SOAP Web Services

General Notices