1. SuiteCloud Platform
  2. SuiteTalk Web Services
  3. SOAP Web Services To Rest Web Services Upgrade Guide
  4. SOAP Web Services and REST Web Services Operations
  5. upsert

upsert

In SOAP web services, the upsert operation is used to add a new instance or to update an instance of a record in NetSuite.

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 required for this operation, upsert is supported only for records that support the external ID field.

SOAP Request

The following example shows how to use the upsert operation.

            <soap:Body>
    <upsert xmlns="urn:messages_2025_1.platform.webservices.netsuite.com">
       <record xmlns:q1="urn:relationships_2025_1.lists.webservices.netsuite.com" xsi:type="q1:Customer" externalId="THISISMYEXTID">
          <q1:entityId>XYZ 2 Inc</q1:entityId>
          <q1:companyName>XYZ 2, Inc.</q1:companyName>
          <q1:email>bsanders@xyz.com</q1:email>
       </record>
    </upsert>
 </soap:Body>

SOAP Response

The following example shows the result of a successful operation.

            <soapenv:Body>
    <upsertResponse xmlns="urn:messages_2025_1.platform.webservices.netsuite.com">
       <writeResponse>
          <platformCore:status isSuccess="true" xmlns:platformCore="urn:core_2025_1.platform.webservices.netsuite.com"/>
          <baseRef internalId="973" externalId="THISISMYEXTID" type="customer" xsi:type="platformCore:RecordRef" xmlns:platformCore="urn:core_2025_1.platform.webservices.netsuite.com"/>
       </writeResponse>
    </upsertResponse>
 </soapenv:Body>

REST Request

In REST web services, you can use the PUT operation with an external ID as a key to a record instead of an internal ID to create or update a record instance.

In REST web services, an external ID starts with the prefix "eid:" in the following format: eid:external_id.

You can use external IDs anywhere in the URL where an internal ID can be used.

The following example shows how to add or update a customer record.

            PUT http://demo123.suitetalk.api.netsuite.com/services/rest/record/v1/customer/eid:CID001
BODY {
  "firstName": "John",
  "lastName": "Smith",
  "isPerson": true,
  "subsidiary": {
  "id": "1"
  }
 }

If the request is successful, an HTTP 204 No Content response is returned.

Related Topics

General Notices