ETL: NetSuite REST Destination

Use the NetSuite REST destination component to write records to NetSuite through NetSuite’s REST web services. It can insert new records, update existing records by internal ID or external ID, or upsert records by external ID. It writes standard and custom records, including transactions with lines such as vendor bills, invoices, and journal entries, and it sets standard and custom fields. A field that points to another record (a vendor, an account, a department) can be given as that record’s internal ID or external ID.

​

Connection Setup

Select an existing NetSuite SOAP or NetSuite OAuth connection, or create a new one. The component works with both connection types: Whichever type you use, NetSuite must allow REST web services for the account and for the role behind the connection:

​

Destination Properties

Choosing another record type clears the schema mapping, because the new record type has different fields. An update or upsert keeps an empty row for its key.

​

Operations

​

Errors and Result File

​

Schema Mapping

Map each input field to a NetSuite field. The NetSuite field list holds the record type’s writable fields:

• Header fields, by field ID, for example memo, tranDate, or entity. Custom body fields appear by their script ID, for example custbody_project_code.
• Line fields, as sublist.field, for example expense.account, expense.amount, or item.quantity. Custom column fields appear the same way, for example expense.custcol_cost_center.

Read-only fields are not listed, except id. Subrecords (such as addresses) and multi-select fields are not listed either. The list is read from NetSuite each time you open the component. If a custom field is missing, check that the connection’s role can see it, then open the component again. For an update or an upsert, the grid starts with a row for the key field (externalId or id). Its NetSuite field is fixed, and the row cannot be removed: pick the input field that holds each record’s key. Reference type appears for fields that point to another record. It tells NetSuite whether the input value is the other record’s internal ID or its external ID: Internal ID means NetSuite’s internal ID of the record, not an account number or a name. Use External ID when your source data carries the external IDs of the records you point to. Auto-fill maps input fields to header fields with the same name, keeping the rows already mapped. Clear unmapped removes rows that do not map an input field to a NetSuite field. How values are sent:

• Empty values are not sent, so they never clear a value that is already in NetSuite.
• Date fields take YYYY-MM-DD strings. A Datetime value sent to a date field is sent as its date.
• A numeric internal ID such as 42.0 is sent as 42.
• A value that cannot be written to NetSuite, such as a map or a bag, fails its record.
• NetSuite stores < and > in text fields as < and >, so reading such a value back from NetSuite returns the entities. Other characters, including &, quotes, and non-ASCII letters, are stored as sent.

​

Transactions with Lines

Mapping a line field changes how input rows become records. The rows that share the same record key value become one NetSuite record:

• The header fields come from the first row of the group.
• Every row adds one line to each sublist it has values for, in input order. A row with no values for a sublist adds no line to it, so one input can carry, for example, expense lines and item lines side by side.
• Rows with an empty record key cannot be grouped. Each one fails as a record of its own and counts against Maximum errors.

Which input field is the record key depends on the operation: For an update or an upsert, Existing lines decides what happens to the lines a record already has:

​

Example: A Vendor Bill with Expense Lines

Input rows: Settings and mapping:

• Record type: vendorbill. Operation type: Upsert. Existing lines: Replace.
• bill_number to externalId (the upsert key row), vendor_code to entity with reference type External ID, memo to memo, tran_date to tranDate, account_id to expense.account with reference type Internal ID, amount to expense.amount.
• No record key to choose: an upsert groups the rows by bill_number, the input field mapped to its key.

The two rows become one vendor bill with the external ID INV-1001 and two expense lines. NetSuite creates the bill on the first run, and a later run with the same rows updates it and replaces its expense lines instead of adding them again.

​

Result File

The result file has a row for each record the job processed, written or failed: The file is written even when the job fails, so it is available after a run stopped by Maximum errors. If NetSuite rejects the connection’s credentials, the job stops at once: the file has the records processed before that, and none after. A following package can read it to post each record’s result back to the source system.

​

How Records Are Written

• One request per record. Records are written one at a time, so throughput depends on how fast NetSuite answers. Plan large loads around your NetSuite account’s concurrency limits.
• Rate limits are retried. A rate-limited request (HTTP 429) is retried with increasing waits.
• Server errors are retried only when that is safe. A server error (HTTP 5xx) is retried for an update or upsert that replaces every sublist it sends. An insert, or a write that appends lines, is reported as failed instead, because NetSuite may already have applied it and a retry could duplicate the record or its lines.
• Rejected credentials stop the job. NetSuite would reject every other record the same way. Test the connection, and reconnect it if it is a NetSuite OAuth connection.
• Rejected records do not stop the job until Maximum errors is exceeded. Each one is in the result file with the status failed.
• Failed tasks are not retried. Task retries are turned off for this component, so a task that fails partway is not run again and its records are not written twice.

​

Best Practices

• Prefer upsert by external ID for loads you may re-run. A re-run updates the same records instead of creating duplicates, and with Replace it does not duplicate lines either.
• Use Append only to add lines on purpose. Running the same append twice adds the lines twice.
• Turn on the result file, especially when Maximum errors is above 0. It lists each failed record with NetSuite’s reason.
• Test against a sandbox account first. For a NetSuite SOAP connection, a sandbox account ID carries the _SB<number> suffix.
• For an insert with lines, choose a stable record key, such as a document number, so rows that belong together always group into the same record.

​

FAQ

Q: How is NetSuite REST different from the NetSuite SOAP destination? NetSuite REST writes through NetSuite’s REST web services, with the operations, line handling, and references described on this page. The NetSuite SOAP destination writes through NetSuite’s SOAP web services and can also delete records, which NetSuite REST does not do. Q: Why does the record type list show vendorbill instead of “Vendor Bill”? NetSuite lists record type IDs in lowercase, and the list shows them as NetSuite returns them. NetSuite accepts them in any case, so vendorbill and vendorBill name the same record type. Search the list by ID. Q: The record is already found by its external ID. Why do some fields need a reference type? The two settings identify different records. The update or upsert key finds the record being written, for example the vendor bill with the external ID INV-1001. A reference type belongs to a field that points to another record, for example the bill’s vendor (entity) or an expense line’s account. NetSuite needs to know whether the value in that field is the vendor’s internal ID or its external ID. The reference type defaults to Internal ID, so you only change it when your data holds the external IDs of the records you point to. Q: How do I write a custom field? Custom fields of the record type appear in the NetSuite field list by script ID: custbody_... for header fields and sublist.custcol_... for line fields. Map them like any other field. If one is missing, check the field’s access for the connection’s role, then open the component again. Q: What happens when a referenced record does not exist? NetSuite rejects the record, for example with NONEXISTENT_EXTERNAL_ID, and the result file reports it as failed. It is never written without the reference. Q: Can I clear a field in NetSuite? No. Empty values are not sent, so an empty input value leaves the NetSuite field as it is. Q: Why did the job stop after the first failed record? Maximum errors defaults to 0. Raise it, or set it to -1, and turn on the result file to see every failure.

​

Related