Idempotent Quickbooks Online integrations - RequestID to the Rescue!

For more information please visit developer.intuit.com.

Integrating with Quickbooks Online provides a lot of functionality and supports many different application architectures. One important feature that should be implemented by integrations with Quickbooks Online is the use of a RequestID parameter. This parameter uniquely identifies the HTTP request sent from your application to the Quickbooks service. RequestID values also enable your application to correlate requests and responses in the outside chance that your application needs to resend an operation to the Quickbooks Online service. In this article, we’re going to demonstrate why the RequestID parameter is important and how you can implement it in your application.

We strongly recommend all developers transfer a unique RequestID value with every API request to Quickbooks Online. By taking this step, idempotency can be guaranteed because Quickbooks Online can identify if the operation was previously received. In the case that the RequestID was previously submitted, the original request will be returned to your application without changing the state of the data. Additionally, in the event of a service disruption data duplication can be prevented in both the Quickbooks service and your application.

Sample RequestID Walkthrough

Let’s walk through adding RequestID to an application’s integration with Quickbooks Online and review the advantages that we gain from adding this parameter to our service calls.

In a new request to the Quickbooks service, our app should transmit a new, unique RequestID as a querystring parameter with the name `requestid`. If the Quickbooks service receives another request with the same RequestID, instead of performing the operation again or returning an error, the service sends the same response as it did for the original request. There are some requirements for specifying a RequestID when making a service call:

• The RequestID your app specifies as the querystring parameter must be unique for all requests for a given company.
• The RequestID can have a maximum of 50 characters for all operations except batch.
• For batch operations, the RequestID supports a maximum of 36 characters. For each batch operation ID, only 10 characters are allowed when RequestID is also specified.
• To avoid duplicate IDs, the app is responsible for generating a unique ID for each request. We recommend your application generates requestid values be with a library such as java.util.UUID or use the .NET System.GUID.
• We recommend you log the RequestID to a persistent data storage, such as a relational database or log file. Tracking this value will enable you to re-execute the same request if you detect an error in the operation.

The following scenario shows how an app might use the RequestID in a create operation:

1. The app sends a request to create an invoice, specifying the RequestID 4957: baseURL/company/1234/invoice?RequestID=4957
2. The service processes the request to create the invoice.
3. An error happens and the application loses its connection to the service and does not receive the response.
4. The application sends the request to create the invoice again, specifying the same content and requestid as in step 1.
5. The Quickbooks service determines that the RequestID has been sent before. Quickbooks decides not to process the request a second time and sends the same response as in step 2. If the application had not specified a RequestID, the service would create a duplicate invoice with a new entity ID.
6. The application receives the response and verifies that it contains no errors.

Advantages of using RequestID

The following two sequence diagrams depict the advantages of using RequestID.

Summary

In large system integrations, it is important that service calls between systems remain idempotent – that is that the same operation with the same inputs returns the same outputs. To help ensure these operations do not execute more than once in Quickbooks, we strongly encourage you to implement the RequestID parameter on all future interactions with the Quickbooks Online service.