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.
Limitation on Upsert
- Although records of a particular type may be used in multiple integration scenarios, each record instance can only have a single external ID value. To maintain data integrity, only a single integrated application can set and update external ID values for each record type. External ID values for all records of a particular type must all come from the same external application.
- Upsert cannot complete updates during an initialize / initializeList operation when a record is transformed into a record of another type. In this case, upsert only adds and does not update records.
- Updates through the upsert operation are also subject to the same limitations as updates through the update operation. For details of these limitations.
Request
<soapenv:Envelope
xmlns:xsd='http://www.w3.org/2001/XMLSchema'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/'
xmlns:platformCore='urn:core_2021_2.platform.webservices.netsuite.com'
xmlns:listRel='urn:relationships_2021_2.lists.webservices.netsuite.com'
xmlns:listAcct='urn:accounting_2021_2.lists.webservices.netsuite.com'
xmlns:platformMsgs='urn:messages_2021_2.platform.webservices.netsuite.com'>
<soapenv:Header>
<tokenPassport xsi:type='platformCore:TokenPassport'>
<account xsi:type='xsd:string'>{{accountId}}</account>
<consumerKey xsi:type='xsd:string'>{{consumerKey}}</consumerKey>
<token xsi:type='xsd:string'>{{tokenId}}</token>
<nonce xsi:type='xsd:string'>{{nonce}}</nonce>
<timestamp xsi:type='xsd:long'>{{timestamp}}</timestamp>
<signature algorithm='HMAC_SHA256' xsi:type='platformCore:TokenPassportSignature'>{{signature}}</signature>
</tokenPassport>
</soapenv:Header>
<soapenv:Body>
<upsert xsi:type='platformMsgs:UpsertRequest'>
<record xsi:type='listRel:Customer' externalId='123456634'>
<email xsi:type='xsd:string'>testtest@gmail.com</email>
</record>
</upsert>
</soapenv:Body>
</soapenv:Envelope>Response
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header>
<platformMsgs:documentInfo
xmlns:platformMsgs="urn:messages_2021_2.platform.webservices.netsuite.com">
<platformMsgs:nsId>WEBSERVICES_TSTDRV2782962_073120231408367550995892899_c438c3</platformMsgs:nsId>
</platformMsgs:documentInfo>
</soapenv:Header>
<soapenv:Body>
<upsertResponse
xmlns="">
<platformMsgs:writeResponse
xmlns:platformMsgs="urn:messages_2021_2.platform.webservices.netsuite.com">
<platformCore:status isSuccess="true"
xmlns:platformCore="urn:core_2021_2.platform.webservices.netsuite.com">
<platformCore:statusDetail>
<platformCore:afterSubmitFailed>false</platformCore:afterSubmitFailed>
</platformCore:statusDetail>
</platformCore:status>
<platformMsgs:baseRef internalId="24" externalId="123456634" type="customer" xsi:type="platformCore:RecordRef"
xmlns:platformCore="urn:core_2021_2.platform.webservices.netsuite.com"/>
</platformMsgs:writeResponse>
</upsertResponse>
</soapenv:Body>
</soapenv:Envelope>