Hey Devs,
Using the Postman Runner, we’re happy to present to you a new and easy way to see how useful a combination of QuickBooks Online API calls can be. The Postman Runner is an effective tool that allows several API endpoints to be chained to create useful flows. We’ve put together six such chains highlighting some of the most important use cases of QuickBooks Online. This tutorial will help you quickly get started using the Postman Runner to make use of the QuickBooks Online APIs. Let’s see how it works!
Step 1. To get started, click on the run button 
Step 2. A new collection, “QuickBooks Orchestrated Examples”, will appear in your Postman app
Within the collection are six separate folders, each covering a specific use case. To see more detail of each use case, select “…” and within the menu select edit.
Step 3. Now that we’ve imported the collection to your Postman, let’s take a look at one of the use cases in detail. In this tutorial, we will look at “Create a SalesReceipt for a Customer”. Select “Create a SalesReceipt for a Customer” under the QuickBooks Orchestrated Examples. There are three API calls within this use case, “Customer-Create”, “Item-Create”, and “Receipt-Create”. As the names imply, after running these three API calls, a Customer, Item, and Receipt will be created. It’s important to note that the order in which the calls are made is very important; making the “Receipt-Create” call before “Customer-Create” and “Item-Create” will result in an error.
Let’s take a look at the “Customer-Create” call in more detail. Choose “Customer-Create”, and the call will appear in Postman.
First thing to note: this is a POST call with the following URI. Please note that the base url, company id, and minor version are all stored as environment variables. We will explain this in more detail further down this post.
Under Authorization, the Type selected is OAuth 1.0 (if it isn’t already selected, please choose it now and save the call). You will see that Consumer Key, Consumer Secret, Token and Token Secret are saved as Environment variables.
At this point, you will need to enter your App credentials. Go to the gear icon in the top right of Postman and select Manage Environments.
Next, select “QBOV3-Env-Variables” and fill in the consumerKey, consumerSecret, OAuth AccessToken, OAuth AccessSecret, and the RealmId with your credentials. For more information on where to get these, please check out Configure the Postman Authorization header. Also note: the baseurl, companid, minorversion are all saved as environment variables here.
Now, let’s take a look at the request body, by selecting “Body”. You’ll now see the request body of this call. In this use case, we will only be passing the following arguments.
{
"DisplayName": "CustomerName - {{$guid}}"
}
Note that {{$guid}} is a built-in Postman random variable. In this case $guid provides us with a V4 style guid. In this case, we are passing in a single object attribute “DisplayName”. There are plenty of other object attributes for Customer; for a rundown of each, check out the Customer Reference guide.
Now, let’s take a look at the “Item-Create” API call. Select “Item-Create” to see the URI for the Item-Create POST call.
The body we will use for the call is:
{
"Name": "ServiceItem - {{$guid}}",
"IncomeAccountRef": {
"value": "1",
"name": "Services"
},
"Type": "Service"
}
The object attributes we are passing into the request are: Name, IncomeAccountRef, and Type. In this case, we are creating an item that is a non-tangible good the company sells and buys that is not tracked as inventory. For example, specialized labor, consulting hours, and professional fees. For more details about the Item Object Attributes, check out our docs.
Let’s move on to the “Receipt-Create” call. Just like before, go ahead and select “Receipt-Create”.
Again, this is a POST call. The above is the URI for the Receipt-Create call and the following is the body.
{
"Line": [
{
"Id": "1",
"LineNum": 1,
"Description": "Sold item",
"Amount": 1000,
"DetailType": "SalesItemLineDetail",
"SalesItemLineDetail": {
"ItemRef": {
"value": "{{ItemId}}",
"name": "{{ItemName}}"
},
"UnitPrice": 1000,
"Qty": 1,
"TaxCodeRef": {
"value": "NON"
}
}
},
{
"Amount": 1000,
"DetailType": "SubTotalLineDetail",
"SubTotalLineDetail": {}
}
],
"CustomerRef": {
"value": "{{CustomerId}}",
"name": "{{CustomerDisplayName}}"
}
}Note the object attributes Line.SalesLineItemDetail.ItemRef and Line.CustomerRef. Each one is populated by an instance of a Postman variable. These variables are created and populated from the response of the calls, “Customer-Create” and “Item-Create”. This is why it is very important to run the API calls in order of “Customer-Create”, “Item-Create” before “Receipt-Create”.
In this call, a receipt has been created for the customer in the “Customer-Create” request, for purchasing a single quantity of the Item created in the “Item-Create” request at the cost of 1000.
Step 4. Now that we’ve explored each API call in detail and have taken care of our environment variable, let’s run the collection. In our example, we will choose Create a SalesReceipt for a Customer. Select Runner in Postman to bring up the Collection Runner. Once you are within the Collection Runner, choose “QuickBooks Orchestrated Examples”, then choose “Create a SalesReceipt for a Customer”. For the other options: Select “QBOV3-Env-Variables” Environment, 1 iteration, and check Persist Variables.
Step 5. Now select “Start Run”. Once the calls have been completed, the Run Results appears.
In the example above, all three API calls were successful. If there is a failure here, please double check the Authorization headers and environment variables as outlined earlier in the article.
Step 6. The collection runner allows the user to see the request URL, request headers, request body, response headers, and response body for each API call made in this use case. To do this, select the API call and choose the option desired in the menu.
Taking a look at the Response Body for the Receipt-Create API call, we should see something similar to this. Yours of course, should be unique to the request that you made.
Response Body:
{
"SalesReceipt": {
"domain": "QBO",
"sparse": false,
"Id": "442",
"SyncToken": "0",
"MetaData": {
"CreateTime": "2017-05-01T23:44:57-07:00",
"LastUpdatedTime": "2017-05-01T23:44:57-07:00"
},
"CustomField": [{
"DefinitionId": "1",
"Name": "Crew #",
"Type": "StringType"
}],
"DocNumber": "1140",
"TxnDate": "2017-05-01",
"CurrencyRef": {
"value": "USD",
"name": "United States Dollar"
},
"Line": [{
"Id": "1",
"LineNum": 1,
"Description": "Sold item",
"Amount": 1000.00,
"DetailType": "SalesItemLineDetail",
"SalesItemLineDetail": {
"ItemRef": {
"value": "126",
"name": "ServiceItem - 5665b0ab-1552-4f8e-bb79-771fb2eccca7"
},
"UnitPrice": 1000,
"Qty": 1,
"TaxCodeRef": {
"value": "NON"
}
}
}, {
"Amount": 1000.00,
"DetailType": "SubTotalLineDetail",
"SubTotalLineDetail": {}
}],
"TxnTaxDetail": {
"TotalTax": 0
},
"CustomerRef": {
"value": "231",
"name": "CustomerName - 441acd11-40e1-4dc4-a8d2-c83a3aedb874"
},
"TotalAmt": 1000.00,
"ApplyTaxAfterDiscount": false,
"PrintStatus": "NeedToPrint",
"EmailStatus": "NotSet",
"Balance": 0,
"DepositToAccountRef": {
"value": "4",
"name": "Undeposited Funds"
}
},
"time": "2017-05-01T23:44:56.575-07:00"
}Let’s check out this Sales Receipt in the sandbox UI. In your sandbox, select Transactions and then Sales. Now search for the “SalesReceipt.Id” from your “Reciept-Create” response. If you are sorted based on date, this should be the latest transaction on this list. Select the receipt and you should see the details of the Sales Receipt. Now verify that the Customer name is the same as the Customer.DisplayName from the response of “Customer-Create”, the same applies to the Item. Also the amount of the transaction as well as the Sales Receipt Id.
That is it! You’ve programmatically recreated one of the most popular use cases within QuickBooks Online. Please check out the other use cases within this collection.
Leave a Reply