Create an invoice

Invoices are a fundamental part of accounting and thus are a vital entity in our APIs. In this tutorial, we’ll go through how to create an invoice using our API Explorer. We will then view the newly-created invoice inside of QuickBooks Sandbox Company UI and map what we see to what is returned in the payload from our API. For this tutorial, you must use a US Sandbox company. Manage your sandbox companies here.

Concepts

Before going through this tutorial, checkout invoice concepts to learn what an invoice is. The minimum fields required to create an Invoice are:

  1. A Line - What is being sold and how much does it cost?
  2. A Customer - Who is buying it?

We can create the invoice once we can answer the questions for each field above. Let’s use a basic invoice as reference:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
   "Line": [
      {
         "DetailType": "SalesItemLineDetail",
         "Amount": 100.0,
         "SalesItemLineDetail": {
            "ItemRef": {
               "name": "Concrete",
               "value": "3"
            }
         }
      }
   ],
   "CustomerRef": {
      "value": "1"
   }
}

#. What is being sold and how much does it cost? According to the payload the company is selling concrete that costs $100. We know that because the first (and only) Line refers a SalesItemLineDetail. The ItemRef is called ”Concrete” and has a value of “3” representing its Id. #. Who is buying it? According to the payload the company is selling to their customer with an Id of “1”.

Now that we know who and what - let’s go to the API Explorer to create this invoice.

Create a basic invoice
  1. Let’s visit the API Explorer.
  2. We need to sign in to enable testing with our sandbox company. Click ‘Sign In’ in the upper-right.
  3. On the right, we can see the Request URL and Request Body. We can add the JSON request from above to the Request Body.
  4. Now we can click the ‘Try It’ button to POST the request to our API.
qbo/docs/workflows/createinvoice-tutorial.png
qbo/docs/workflows/createinvoice-tutorial.png

x

And just like that, we created an invoice in the sandbox company - Nice! Of course, what the customer is buying isn’t always going to be a product, and the company won’t only have one customer. Companies can have many products and services. They are called Items in our API. They will also have many Customers. We can keep track of these items and customers:

The API Explorer is an excellent tool for exploring and for testing before we start coding. Aside from taking an accounting course specifically for QuickBooks - there is no better way to learn what QuickBooks Online does and how our APIs work at the same time.

“If it can be done with the API Explorer, it can be done in code!” - Wise Developer

The resulting invoice will look like this in our sandbox:

qbo/docs/workflows/invoiceinui.png
qbo/docs/workflows/invoiceinui.png

x

Most invoices are going to contain more information than explained above. You may be creating an invoice that includes taxes or discounts or shipping charges. You may also need to add some custom fields or link an invoice with another transaction, such as a payment. Read on to learn more.

Add more lines to an invoice

Line items, or simply, lines in an Invoice represent individual line items of a transaction. Line items are used to show customers an itemized description of the products or services provided and charges associated with each. Each line is specified with a separate <Line> element. Possible line types for invoices include:

The first invoice we created included a single SalesItemLine. Let’s create an invoice now that contains multiple lines.

  1. Head back to API Explorer, sign in and select your sandbox company.
  2. Let’s modify the default Request Body with more data.
  3. Add more lines to the invoice to include bundle items and provide a discount. Here’s the JSON request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "Line": [
     {
      "DetailType": "GroupLineDetail",
      "GroupLineDetail": {
       "GroupItemRef": {
        "value": "19",
        "name": "Bundle One"
       },
       "Quantity": 2
      }
     },
     {
      "Description": "Additional info here",
      "DetailType": "DescriptionOnly"
     },
     {
      "DetailType": "DiscountLineDetail",
      "DiscountLineDetail": {
       "PercentBased": true,
       "DiscountPercent": 10
      }
     }
    ],
    "CustomerRef": {
      "value": "1"
    }
  }

Note that in this example, the GroupItemRef ID “19” used is a previously created bundle item containing multiple individual items. Determine the Item by querying the Item endpoint. You may have to create one in your sandbox if you don’t have any.

The resulting invoice will look like this in our sandbox:

qbo/docs/workflows/invoice-ui-lines.png
qbo/docs/workflows/invoice-ui-lines.png

x

See the API Explorer for more details on required fields.

Manage sales tax

QuickBooks Online has different specifications for US and non-US companies. US QuickBooks Online companies created after November 10, 2017, manage sales tax calculations via an automated sales tax (AST) engine. Non-US QuickBooks Online companies will need to handle sales taxes manually, using tax codes and tax services.

Add custom fields

Custom fields are user-defined fields used to track additional information that QuickBooks doesn’t already track. They are set up via Company Preferences in the UI. Custom field definitions can be read via the Preferences entity. See custom fields for further information about creating and using them.

qbo/docs/workflows/Invoice1040CustomFields.jpg
qbo/docs/workflows/Invoice1040CustomFields.jpg

x

Process payments

Payments received for an invoice are represented in the Invoice object with the LinkedTxn attribute. The image below shows how linked transactions relate to the actual payments received for this Invoice object. See linked transactions for complete details about linked transactions and processing payments.

Add more information

The full complement of fields in the Invoice object that are references to other objects or lists is listed below. See Invoice in the API Reference for individual requirements and details.

We can see an example of how an invoice maps to our APIs:

qbo/docs/workflows/invoicemapping1.png
qbo/docs/workflows/invoicemapping1.png

x

In all cases, the referenced object must exist in the company to reference it in a create or update request. Query the resource to determine the appropriate object to reference in the Invoice. Use Id and Name from that object for the reference value and name fields, respectively. If a reference object doesn’t exist, the QuickBooks Online API returns a validation fault message similar to the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
   "Fault": {
      "Error": [{
         "Message": "Invalid Reference Id",
         "Detail": "Invalid Reference Id : Something you're trying to use has been made inactive.
                    Check the fields with accounts,customers,items,vendors or employees.",
         "code": "2500",
         "element": ""
      }],
      "type": "ValidationFault"
   },
   "time": "2019-06-07T12:37:12.158-07:00"
}
Code

We’ve tested in the API Explorer, and we get the concepts. So how is this done in code? We have SDKs for Java, .NET, and PHP. We also have examples of creating an Invoice for each of them.