Hey Devs,
Did you know that QuickBooks Online has batch operations? Instead of sending requests to the QuickBooks API one at a time, requiring you to make a request and then wait for a response, Batch operations provides a way to perform batches of operations on multiple services. For example, in a single batch request an application can create a customer, update an invoice, and read an account.
Its important to know that within a batch request, the individual requests are performed serially. For example, you can have within your batch request the following operations: Create a customer, Create an Item, Create an Invoice. Due to the serial nature of the batch process, a customer will be created first, followed by creating an item, and then finally creating an invoice. However, requests do not have visibility of earlier requests included from the same payload. For example, consider a batch request containing a customer create followed by an invoice create: that new customer object is not available to the invoice create request.
Benefits of Batch Operations
-
Reduces network latency (having to wait for synchronous API calls to respond)
-
More efficient code
-
Reduce number of api calls
Guideline for Throttling
When using the Batch Operation we recommend that you follow the following limits:
- 40 requests per minute
- 10 payloads per batch
Documentation
Batch Operation reference guide can be found here: https://developer.intuit.com/docs/api/accounting/batch
How to test using Postman
Download the QuickBooks Accounting API Postman Collection and select the Batch Operation folder. For more information about the QuickBooks Accounting API Postman Collection, go here.
For each payload, you will get a single response
Here is a sample request where we will perform 2 operations in a single batch request. We will first create a customer and then query a customer. We will provide code snippets for the same request in the SDK section below this.
{
"BatchItemRequest":
[
{
"bId": "bid1",
"operation": "create",
"Customer": {
"DisplayName": "Bob Smith (Customer)"
}
},{
"bId": "bid2",
"Query": "select * from Customer startposition 1 maxresults 1"
}
]
}Here is a sample response:
{
"BatchItemResponse": [
{
"Customer": {
"domain": "QBO",
"sparse": false,
"Id": "262",
"FullyQualifiedName": "Bob Smith (Customer)",
"DisplayName": "Bob Smith (Customer)",
"Active": true
},
"bId": "bid1"
},
{
"QueryResponse": {
"Customer": [
{
"Taxable": true,
"domain": "QBO",
"Id": "75",
"SyncToken": "1",
"MetaData": {
"CreateTime": "2017-01-26T00:42:22-08:00",
"LastUpdatedTime": "2017-01-26T05:31:56-08:00"
},
"FullyQualifiedName": "0.2602763659613787",
"DisplayName": "0.2602763659613787",
"Active": true
}
],
"startPosition": 1,
"maxResults": 1
},
"bId": "bid2"
}
],
"time": "2017-07-25T15:08:01.730-07:00"
}SDK Support
[tabby title=”JAVA”]
The JAVA SDK supports batch processes.
- Installation, usage and documentation for the JAVA SDK
The Batch Operation for the same request in the above section.
OAuth 1.0
OAuthAuthorizer oauth = new OAuthAuthorizer(consumerKey, consumerSecret, accessToken, accessTokenSecret);
Context context = new Context(oauth, appToken, ServiceType.QBO, realmID);
DataService service = new DataService(context);OAuth 2.0
//create oauth object – pass OAuth2 access token
OAuth2Authorizer oauth = new OAuth2Authorizer(accessToken);
//create context – pass realm id
Context context = new Context(oauth, ServiceType.QBO, realmId);
The Batch Request
DataService service = new DataService(context);
BatchOperation batchOperation = new BatchOperation();
// Create a customer object with name - Bob Smith (Customer)
Customer customer = new Customer();
customer.setDisplayName("Bob Smith (Customer)");
// Add the customer object to BatchOperation.
batchOperation.addEntity(customer, OperationEnum.CREATE, "bID1");
// Add a query string
String query = "select * from Customer startposition 1 maxresults 1";
// Add the query string to the batchOperation
batchOperation.addQuery(query, "bID2");
// Execute the batch
service.executeBatch(batchOperation);For more information and a full example of creating a batch request
[tabby title=”.NET”]
The .NET SDK supports batch processes.
- Installation, usage and documentation for the .NET SDK
Here is a code snippet for the above raw request.
OAuth 1.0
OAuthRequestValidator oauthValidator = new OAuthRequestValidator(accessToken, accessTokenSecret, consumerKey, consumerSecret);
ServiceContext serviceContext = new ServiceContext(realmId, IntuitServicesType.QBO, oauthValidator);
DataService commonServiceQBO = new DataService(context);OAuth 2.0
OAuth2RequestValidator oauth2Validator = new OAuth2RequestValidator(access_token);
ServiceContext serviceContext = new ServiceContext(realmId, IntuitServicesType.QBO, oauth2Validator);The Batch Operation
DataService commonServiceQBO = new DataService(context);
//Create batch request
Batch batchTest1 = commonServiceQBO.CreateNewBatch();
//Create customer object with some random name
Customer customer12 = new Customer();
string guid = Guid.NewGuid().ToString("n");
customer12.DisplayName = guid.Substring(0, 20);
//Query customer endpoint
String query = "select * from Customer startposition 1 maxresults 1";
//Add first batch operation
batchTest1.Add(customer12, "Customer1", OperationEnum.create);
//Add second batch operation
batchTest1.Add(query, "Query1", OperationEnum.query);
//Execute Batch
batchTest1.Execute();For more information and a full example of creating a batch request
[tabby title=”PHP”]
The PHP SDK supports batch processes.
- Installation, usage and documentation for the PHP SDK
The Batch Operation for the same request in the above section.
OAuth 1.0
$dataService = DataService::Configure(array(
'auth_mode' => 'oauth1',
'consumerKey' => "Your Consumer key",
'consumerSecret' => "Your Consumer secret",
'accessTokenKey' => "Your Access Tokens",
'accessTokenSecret' => "Your Access Token secrets",
'QBORealmID' => "Your CompanyID",
'baseUrl' => "Either sandbox or Production QBO URL"
));
OAuth 2.0
$dataService = DataService::Configure(array(
'auth_mode' => 'oauth2',
'ClientID' => "Your Client ID",
'ClientSecret' => "Your Client Secret",
'accessTokenKey' => 'Your Access Token',
'refreshTokenKey' => "Your Refresh Token",
'QBORealmID' => "Your CompanyID",
'baseUrl' => "Either sandbox or production QBO URL"
));The Batch Request
$batch = $dataService->CreateNewBatch();
$customerObj = Customer::create([
"Title"=> "Mr",
"GivenName"=> "James",
"MiddleName"=> "B",
"FamilyName"=> "King",
"Suffix"=> "Jr",
"FullyQualifiedName"=> "King Groceries",
"CompanyName"=> "King Groceries",
"DisplayName"=> "King's Groceries",
]);
$batch->AddEntity$customerObj, "addcustomer1", OperationEnum::create);
$batch->AddQuery("select * from Vendor startPosition 0 maxResults 100", "queryVendor");
$batch->Execute();
//Create response
$batchItemResponse = $batch->intuitBatchItemResponses[0];
$createdCustomer= $inuititemresponse->entity;
//Query response$batchItemResponse = $batch->intuitBatchItemResponses[1];
$vendors = $batchItemResponse->entities;For more information and a full example of creating a batch request
[tabbyending]
Thats it! Creating a batch request is really quite simple and helpful for the performance of your code. If you have any questions regarding what we’ve covered here, ask away on the developer forums!
Have a good one Devs!
Jimmy Wong
Intuit Developer Evangelist
Leave a Reply