The upsert operation is used to add a new instance or to update an instance of a record in NetSuite. It is similar to the upsertList operation, which allows users to add or update more than one record at a time.

The upsert operation is similar to both the add and update operations, but upsert can be run without first determining whether a record exists in NetSuite. A record is identified by its external ID and its record type. If a record of the specified type with a matching external ID exists in the system, it is updated. If it does not exist, a new record is created.

Because external ID is mandatory for this operation, upsert is supported only for records that support the external ID field. Also, this operation prohibits the passing of internal ID values.


To prevent duplicate records, you should use external IDs and the upsert and upsertList operations to add records to NetSuite.

Limitations on upsert


The UpsertRequest type is used for the request. It contains the following fields.

Element Name

XSD Type




Contains an array of record objects. The record type is an abstract type so an instance of a type that extends record must be used—such as Customer or Event.


The UpsertResponse type is used for the response. It contains the following fields.

Element Name

XSD Type




Contains details on the status of the operation and a reference to thecreated or updated record.


Sample Code

SOAP Request

            <upsert xmlns="">
               <record xmlns:q1="" xsi:type="q1:Customer" externalId="THISISMYEXTID">
                  <q1:entityId>XYZ 2 Inc</q1:entityId>
                  <q1:companyName>XYZ 2, Inc.</q1:companyName>


SOAP Response

            <upsertResponse xmlns="">
                  <platformCore:status isSuccess="true" xmlns:platformCore=""/>
                  <baseRef internalId="973" externalId="THISISMYEXTID" type="customer" xsi:type="platformCore:RecordRef" xmlns:platformCore=""/>



          private void upsertCustomer()
              // This operation requires a valid session
              this.login( true );
              Customer customer = new Customer();
              // Get externalId for upsert      
              _out.write( "\nEnter externalId for customer record to be created or updated : " );
              customer.externalId = _out.readLn().ToUpper();
              // Set name and email
              customer.entityId = "XYZ 2 Inc";
              customer.companyName = "XYZ 2, Inc.";
     = "";
              // Invoke upsert() operation
              WriteResponse response = _service.upsert( customer );
              // Process the response
              if (response.status.isSuccess )   
                    "\nThe upsert operation was successful :" +
                    "\ninternalId=" + ((RecordRef) response.baseRef).internalId +
                    "\nexternalId=" + ((RecordRef) response.baseRef).externalId +
                    "\nentityId=" + customer.entityId +
                    "\ncompanyName=" + customer.companyName);
              } else {
                    _out.error( getStatusDetails( response.status ) );



          public void upsertCustomer() throws RemoteException,ExceededUsageLimitFault,
            UnexpectedErrorFault, InvalidSessionFault,ExceededRecordCountFault
            // This operation requires a valid session
            Customer customer = new Customer();
            // Get extenalId for add or update
            _console.write("\nEnter externalId for customer record to be updated : ");
            // Set name and email
            customer.setEntityId("XYZ 2 Inc");
            customer.setCompanyName("XYZ 2, Inc.");
            // Invoke upsert() operation
            WriteResponse response = _port.upsert(customer);
            // Process the response
            if (response.getStatus().isIsSuccess())
        "\nThe following customer was created/updated successfully:"
                        + "\nkey=" + ((RecordRef) response.getBaseRef()).getInternalId()
                        + "\nexternalId=" + ((RecordRef) response.getBaseRef()).getExternalId()
                        + "\nentityId=" + customer.getEntityId()
                        + "\ncompanyName=" + customer.getCompanyName()
                        + "\nemail=" + customer.getEmail());


Related Topics

SuiteTalk SOAP Web Services Platform Overview
SOAP Web Services Development Considerations
SOAP Web Services Processing
SOAP Web Services Operations
SOAP Web Services Standard Operations
SOAP Web Services List Operations
SOAP Web Services Asynchronous Operations

General Notices