1. SuiteCloud Platform
  2. SuiteTalk Web Services
  3. SuiteTalk REST Web Services API Guide
  4. REST Web Services Operations
  5. Batch Operations

Batch Operations

You can use batch operations in REST web services to add, update, delete, or upsert multiple instances of a record type in a single REST request.

Batch operations reduce the number of network requests by processing multiple records in one request, minimizing latency and server load. This is useful for large-scale data imports, updates, and deletions, as it improves system performance and user experience. Batch operations in REST web services are executed asynchronously and in parallel.

When you use batch operation, you must specify the following REST request headers:

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.

You can currently work with a maximum of 100 records in one batch request.

Creating an Updating Records with Batch Requests

The following example shows how to create or update records with batch requests, using the POST, PATCH and PUT operations. You can create new records using the POST and PUT operations. You can update existing records using the PUT and PATCH operations.

In the request, you can specify any field that can be used to create a single record.

            URL:
POST 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": [
    {
      "name": "item 1",
     "field1" : {"id" : "1"}
    },
    {
      "name": "item 2"
    }
  ]
}

PATCH and PUT requests have an internal or external ID specified in each item. PUT requests only support external ID for the upsert operation.

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"
    }
  ]
}

Getting and Deleting Records with Batch Requests

You can use batch operations to retrieve or delete a collection of records using a GET or DELETE request.

To retrieve a collection of records, you must specify the expandRecords=true URL parameter in the GET request.

To retrieve or delete a collection of records, you must specify the ids URL parameter, containing the internal or external ID of the existing records.

Optionally, you can use the expandSubResources, expand, and fields parameters in the request. If these parameters are not used, the request returns all body fields of the records.

For more information, see REST Web Services Request Processing and Sending an Asynchronous Request Using an Idempotency Key.

Note:

You cannot directly access subresources through the request URL. For example, the request https://demo123.suitetalk.api.netsuite.com/services/rest/record/v1/salesOrder/subrecord?expandRecords=true is not supported.

The following example shows the structure of a batch GET request.

            URL:
GET https://demo123.suitetalk.api.netsuite.com/services/rest/record/v1/salesOrder?expandRecords=true&ids=1,2,3,eid:test,eid:'test 5'

HEADERS:
Authorization: /*Auth token goes here*/
Prefer: respond-async

BODY:

The following example shows the structure of a batch DELETE request.

            URL:
DELETE https://demo123.suitetalk.api.netsuite.com/services/rest/record/v1/salesOrder?ids=1,2

HEADERS:
Authorization: /*Auth token goes here*/

BODY:

Working with Asynchronous Batch Request Responses

Asynchronous batch requests return a response with a link to the newly created asynchronous task. The following is an example of a response.

            Response:
HTTP CODE: HTTP 202

BODY: 

HEADERS:
Preference-Applied: respond-async
location: https://demo123.suitetalk.api.netsuite.com/services/rest/async/v1/job/1

Then you can send a request using the job ID in the response header to retrieve the list of tasks.

Note that you cannot retrieve all responses for all record sub-requests in a single response.

            URL:
GET https://demo123.suitetalk.api.netsuite.com/services/rest/async/v1/job/1/task

Response:
HTTP CODE: HTTP 200

BODY: 
{
    "links": [
        {
            "rel": "self",
            "href": "https://demo123.suitetalk.api.netsuite.com/services/rest/async/v1/job/1/task"
        }
    ],
    "count": 1,
    "items": [
        {
            "links": [
                {
                    "rel": "self",
                    "href": "https://demo123.suitetalk.api.netsuite.com/services/rest/async/v1/job/1/task/1"
                },
                {
                    "rel": "self",
                    "href": "https://demo123.suitetalk.api.netsuite.com/services/rest/async/v1/job/1/task/2"
                }
            ]
        }
    ]
}

The following example shows how the retrieve the result of a single task.

            URL:
GET https://demo123.suitetalk.api.netsuite.com/services/rest/async/v1/job/1/task/2/result

Response:
HTTP CODE: ...

BODY: 
{
    ...
}

Related Topics

General Notices