REST Web Services Now Support Batch Operations for Multi-Record Processing

NetSuite's REST web services now support batch operations, enabling you to create, update, upsert, retrieve, or delete up to 100 records of a single record type in one HTTP request. All batch requests execute asynchronously and in parallel.

What changed

A new batch pattern is available on the standard REST record endpoint:

/services/rest/record/v1/{recordType}

Supported HTTP methods

• POST — create records. Body contains an items array of record payloads.
• PUT — upsert via external ID only. Each item must include an externalId.
• PATCH — update existing records. Each item must include id (internal) or externalId. Internal ID takes precedence when both are provided.
• GET — retrieve records. Pass ?expandRecords=true&ids=1,2,eid:extKey. External IDs are prefixed with eid:; values with spaces must be single-quoted (eid:'my key'). Optional parameters: expandSubResources, expand, fields.
• DELETE — delete records. Pass ?ids=1,2.

Required headers

• Prefer: respond-async — mandatory on every batch request.
• Content-Type: application/vnd.oracle.resource+json; type=collection — mandatory on POST, PATCH, and PUT.
• X-NetSuite-idempotency-key — optional but recommended. Attach a unique value to safely retry a request without duplicating records.

Async job tracking

Every batch request returns HTTP 202 with a Location header pointing to the async job:

/services/rest/async/v1/job/{jobId}

Poll the task list at /services/rest/async/v1/job/{jobId}/task and fetch individual results at /services/rest/async/v1/job/{jobId}/task/{taskId}/result. Each sub-request becomes its own task — you cannot retrieve all sub-request results in a single response.

Constraints and limits

• Maximum 100 records per batch.
• Subject to standard governance limits, account concurrency caps, licensed capacity (SuiteCloud Plus), and the concurrency settings on the integration record.
• Subresources cannot be accessed directly via the batch URL (e.g., /salesOrder/subrecord?expandRecords=true is not supported).

What to do

1. Confirm your concurrency limits. Check your integration record's concurrency setting and your account's SuiteCloud Plus entitlement. Batch operations run in parallel, so submitting too many concurrent batches can hit throttling.
2. Tune parallelism empirically. Oracle explicitly recommends tuning against observed completion rate, error rate, and account concurrency rather than flooding all available work at once.
3. Add idempotency keys. For any non-idempotent operation (POST, PUT), include X-NetSuite-idempotency-key so retries after timeouts or network errors do not create duplicates.
4. Build polling logic. Since every batch is async, your integration must poll the job/task endpoints to determine success or failure of individual records. Design for partial failures — some tasks within a batch can succeed while others fail.
5. Migrate high-volume SOAP calls. If you currently use SuiteTalk SOAP addList/updateList/deleteList, evaluate switching to REST batch operations for reduced overhead and built-in async handling. Note that REST batches cap at 100 records vs. SOAP's 200-record limit, so adjust chunking logic accordingly.
6. Do not rely on execution order. Batch items run in parallel, not sequentially. If records have dependencies (e.g., parent-child), submit them in separate sequential requests.

Note: The source documentation does not specify which NetSuite release introduced batch operations. Verify availability in your account's release notes or by testing against your sandbox.