Customer records represent people or companies that purchase goods and services from your business. Use the customer record to manage these customers. Client applications can create, update, or delete customer records. For more details, see Customers.

The Customer record is defined in the listRel (relationship) XSD.

Supported Operations

The following operations can be used to modify Customer records:

add | addList | attach / detach | delete | deleteList | get | getDeleted | getList | getSavedSearch | getSelectValue | search | searchMoreWithId | update | updateList | upsert | upsertList


You can also use the asynchronous equivalents of SOAP web services list operations. For information about asynchronous operations, see SOAP Web Services Asynchronous Operations. For more information about request processing, see Synchronous Versus Asynchronous Request Processing.

Field Definitions

The SOAP Schema Browser includes definitions for all body fields, sublist fields, search filters, and search joins available to this record. For details, see the SOAP Schema Browser’s customer reference page. For information about using the SOAP Schema Browser, see SOAP Schema Browser.


The monthlyClosing field is used only by the Japan Edition of NetSuite.


The balance, overdueBalance, and depositBalance fields are only returned when using advanced search. They are not returned when using the <Record>SearchBasic search object. In advanced search, you must set the bodyFieldsOnly preference to false. These fields are not returned if the bodyFieldsOnly preference is set to true. For more information, see bodyFieldsOnly.

Usage Notes

Usage notes are provided for the following topics:

The EntityID Field

The entityID field is set as an inline text field by default. Inline text fields are read only fields and may not be edited through SOAP web services. To create a new customer record, you must leave out the entityID field.

Understanding Customer Stages

In the NetSuite UI, there are three possible stages that can be defined for a customer — lead, prospect or customer. When entering new customers into NetSuite, you can create the record as a lead, prospect or customer record, or you can create the customer as a lead and allow NetSuite to automatically update the stage as certain criteria are met.


When adding leads through SOAP web services, you can use the rules you have defined in the SFA (Sales Force Automation) feature to assign leads. Be aware that SFA rules are applied regardless of the setting for the “Use Conditional Defaults on Add” preference.

This workflow is also maintained when working with SOAP web services. The Stage field indicates whether the customer is a lead, prospect or customer as defined above. For example, if a customer record is defined as a Lead by SOAP web services and then that customer record has an opportunity record associated with it by SOAP web services, the customer record Stage field will automatically be updated to reflect the new prospect stage. After the opportunity record is updated to Closed-Won, the record Stage field is automatically updated to Customer. To enter a new customer record at a specified stage, set the Stage field to Lead, Prospect or Customer as desired.


In SOAP web services the entityID field of a Customer record is by default an Inline Field Type (read-only). If you try to set the entityID when adding a new Customer, you will receive an error message. To avoid the error message, you should not set a value for the entityID field. If you need to enter an entityID, you must enable the Allow Override option for it in Setup > Company > Setup Tasks > Auto-Generated Numbers. For more information, see Overwrite Entity and CRM Record Type Numbers.

Customer Status and Stage Internal IDs

The following table lists the internal IDs for all standard Customer Status and Stage values that can be used to populate the entityStatus or stage field.


In addition to the following standard custom status values, your organization may have defined custom Customer Status values. If the Show Internal IDs preference is enabled, you can confirm the internal ID values in the associated list. For more details, see Setting the Show Internal IDs Preference

Customer Statuses


Customer Stages






















Closed Lost



Identified Decision Makers



In Discussion



In Negotiation



Opportunity Identified









Closed Won



Lost Customer





Returning a Contact List for a Customer

To return a list of contacts associated to a specific customer record, you must first get the customer record and then perform a search for the contacts associated to that customer.

Sample Java Code

          // First get your customer 
Customer c = (Customer)port.get(new RecordRef("17",RecordType.customer)).getRecord(); 

// Now do a specific search for the Contacts 
ContactSearch cts = new ContactSearch(); 

// Search for an exact match between Customer.EntityId and the ContactSearch Field Company.cts.setCompany(new SearchStringField(c.getEntityId(),; 

// Execute the search and you have your contactlist. 
SearchResult scts =; 


Working with Customer Sublists

The SOAP Schema Browser includes all sublists associated with the customer record. See the following information for usage notes regarding specific customer sublists. Usage notes are not provided for every sublist type.

For general information about working with sublists in SOAP, see Sublists in SOAP Web Services.


This sublist is available for updates of customer records only. You can update this sublist's data to provide Customer Center access to contacts. You can provide access to contacts that already exist in NetSuite and that have already been attached to a customer that already exists in NetSuite. You cannot use this sublist to attach new contacts. The workflow is as follows: 1) Add customer. 2) Add contacts. 3) Attach contacts to customer. 4) Update customer with contact access information with this sublist.

The fields in this sublist map to the fields on the Access subtab in the UI. These fields include:

Operations on this sublist do not preserve row order. In some cases, rows added to the sublist will not be returned in the same order.


As of the 2011.2 endpoint, the CustomerContactList sublist is no longer supported. You can use the CustomerContactRoleList instead. In addition, you can add or update contacts through the attach/detach operations, and you can retrieve contact names and roles for an entity through an advanced search on the entity record and its associated contacts. This advanced search technique is described in Returning a Contact List for a Customer.


The creditCardsList field is a list field that lets you provide multiple credit card entries for a customer. The customer can then use these entries for payments. These fields are all mapped to the Financial tab in the UI.

When working with credit card data, be aware of the following security features:


This list enables you to define multiple currencies that can be used for a customer's transactions, in addition to the primary currency set for a customer. This list is available when the Multiple Currencies feature is enabled. For details about using this feature, see Customers and Multiple Currencies.

This list's Currency field maps to the Currency field on the Currencies subtab on the Financial subtab of the standard customer record in the UI.


The addressBookList field is a list field that lets you provide multiple addresses for a customer. These fields are all mapped to the Address tab in the UI.

When you work with the addressbookList on customer records in the 2009.2 endpoint and beyond, be sure to use internalId as the key. Do not use label. For the 2009.1 and lower endpoints, the addressbookList is not a keyed sublist, but you can use label to identify records.


Sales territory assignments are based on customers' default billing addresses. If you do not set defaultBilling to True for a customer address, it is not assigned to a territory automatically.


This list is only available when the Team Selling feature is enabled.


The Sell Downloadable Items feature must be enabled in an account to provide downloads for customers in the Customer Center.


The subscriptionsList sublist on the customer record can be updated. Use the replaceAll flag to update specific lines in this sublist, using subscription as the key. Be aware that SOAP web services updates to this sublist follow the logic that is permitted in the NetSuite UI. After an entity is unsubscribed from a category, only the entity itself can re-subscribe.

Tax Registrations Sublist

The tax registrations sublist is available when the SuiteTax feature is enabled at Setup > Company > Setup Tasks > Enable Features, on the Tax subtab.

Whenever you change the Tax Registration Number value on a sublist line, it triggers the regeneration of the value of a hidden ID field, and the values of ID fields are regenerated on all sublist lines. The ID field is hidden in the UI, but it is visible through SOAP web services. The ID field is searchable, so you can access the updated values through SOAP web services.

For information about working with tax registration in the UI, see Assigning Tax Registrations to an Entity in SuiteTax.

Related Topics

Entity Search
How to Use the SOAP Web Services Records Help
SOAP Web Services Supported Records
SOAP Schema Browser
SuiteTalk SOAP Web Services Platform Overview

General Notices