upsertList
In SOAP web services, the upsertList operation is used to add or update one or more instances of a record type in NetSuite.
If there are multiple records, they can either be of the same record type or different record types. For example, it's possible to add or update a customer and a contact within a single request using this operation.
The upsertList operation is similar to both the addList and updateList operations, but upsert can be run without first determining whether records exist in NetSuite. Records are identified by their external ID and their 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, upsertList is supported only for records that support the external ID field. Also, this operation prohibits the passing of internal ID values.
SOAP Request
The following example shows the usage of the upsertList operation on multiple customer records.
<soap:Body>
<upsertList 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="ext1">
<q1:entityId>XYZ Inc 0</q1:entityId>
<q1:companyName>XYZ, Inc. 0</q1:companyName>
</record>
<record xmlns:q2="urn:relationships_2025_1.lists.webservices.netsuite.com" xsi:type="q2:Customer" externalId="ext2">
<q2:entityId>XYZ Inc 1</q2:entityId>
<q2:companyName>XYZ, Inc. 1</q2:companyName>
</record>
</upsertList>
</soap:Body>
SOAP Response
The following example shows the result of a successful operation.
<soapenv:Body>
<upsertListResponse xmlns="urn:messages_2025_1.platform.webservices.netsuite.com">
<writeResponseList>
<writeResponse>
<platformCore:status isSuccess="true" xmlns:platformCore="urn:core_2025_1.platform.webservices.netsuite.com"/>
<baseRef internalId="970" externalId="ext1" type="customer" xsi:type="platformCore:RecordRef" xmlns:platformCore="urn:core_2025_1.platform.webservices.netsuite.com"/>
</writeResponse>
<writeResponse>
<platformCore:status isSuccess="true" xmlns:platformCore="urn:core_2025_1.platform.webservices.netsuite.com"/>
<baseRef internalId="974" externalId="ext2" type="customer" xsi:type="platformCore:RecordRef" xmlns:platformCore="urn:core_2025_1.platform.webservices.netsuite.com"/>
</writeResponse>
</writeResponseList>
</upsertListResponse>
</soapenv:Body>
In REST web services, you can use batch operations to upsert multiple instances of the same record type in a single REST request.
Batch operations in REST web services are executed asynchronously and in parallel. You can currently work with a maximum of 100 records in one batch request.
When you use batch operations for upserting records, you must specify the following REST request headers:
-
prefer: respond-async -
content-type: application/vnd.oracle.resource+json; type=collection
Additionally, you can specify the X-NetSuite-idempotency-key header with a unique idempotency key value. For an example, see Sending an Asynchronous Request Using an Idempotency Key.
REST Request
The following example shows how to upsert records with batch requests. You can upsert records using the PUT and PATCH operations.
PATCH and PUT requests have an internal or external ID specified in each item.
You can specify both internal and external IDs in the request, but only one is used to match it to a record. The internal ID takes precedence over the external ID.
URL:
PATCH https://demo123.suitetalk.api.netsuite.com/services/rest/record/v1/salesOrder
HEADERS:
Authorization: /*Auth token goes here*/
Prefer: respond-async
Content-type: application/vnd.oracle.resource+json; type=collection
BODY:
{
"items": [
{
"id" : 5,
"name": "item 1",
"field1" : {"id" : "1"}
},
{
"externalId" : "item 2 eid",
"name": "item 2"
}
]
}
REST Response
Asynchronous batch requests return a response with a link to the newly created asynchronous task. The following is an example of a response. Then you can send a request using the job ID in the response header to retrieve the list of tasks.
Response:
HTTP CODE: HTTP 202
BODY:
HEADERS:
Preference-Applied: respond-async
location: https://demo123.suitetalk.api.netsuite.com/services/rest/async/v1/job/1