Create basic invoices

Invoicing is a fundamental accounting task for most businesses. Small businesses use invoices when they sell products and services, but expect customers to pay for them later on.

The invoice entity is a critical part of our API. Creating, sending, and managing invoices also involves many other API entities. You’ll need to consider the customers (Customer entity), items (Item entity), sales tax, and payment processing involved.

This requires you to think broadly about what type of sales functionality you want for your app.

We’ll cover invoicing basics, go over the invoice entity, and show you how to create invoices using multiple entities.

Step 1: Learn more about how invoicing works

Small businesses send invoices to customers to record the sale of products and services. Business owners send invoices when they expect to be paid in the future, not at the time of sale.

Invoicing is fundamental to QuickBooks Online. Most users do invoicing every day. Learn more about invoicing as an accounting concept.

Step 2: Set up your app on the Intuit Developer Portal

If you haven’t already, get a QuickBooks Online sandbox company to test with and create an app on the dev portal.

When you create your app, make sure you review your app’s scopes. Scopes limit the API entities and data your app can access.

Step 3 : Get your apps credentials

Get the Client ID and Client Secret for your app.

You’ll use these to connect your app to services like OAuth 2.0.

Step 4: Set up authorization

If you haven’t already, set up OAuth 2.0 for your app.

Step 5: Set up basic accounting implementations

For your app’s implementations, make sure you pre-create entities and then reference them in transaction entities for the implementation.

Follow these steps to set up basic implements:

Step 6: Learn about the invoice entity

There are two required objects for every invoice:

Let’s look at sample payload to understand the basics:

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

This payload, specifically the line and customer objects, tells us a few things about our invoice:

Step 7: Create a basic invoice

Now we know what data needs to be on an invoice object, we can call the relevant API entities. To create invoices, use the following entities:

Review each entity to see more details about specific fields, parameters, and operations. For this example, we’ll use a sandbox company to see the code in action on the API Explorer:

  1. Sign in to your developer account.
  2. Go to the API Explorer.
  3. In the Sandbox bar, select the sandbox company you want to test with.
  4. Select the Invoice reference section.
  5. Go to the Create an invoice section.
  6. Review the request in the Request Body code sample.
  7. Select Try It.
  8. Review the response in the Returns sample.

The API Explorer automatically sends a POST request to create this sample invoice for your sandbox company.

If you open your sandbox company, you’ll see it. The response has a few key fields:

This tells us the invoice has a single item called “Services,” identified by ID “1”, with the type “SalesItemLineDetail”.

Step 8: Add items to an invoice

So far, our example is a very simple invoice. Your app will need to to create invoices with many products and services for different customers. Review the Invoice entity to see specific field and attribute details. In particular, review the line and line.detailType fields.

The line element can contain multiple items (i.e. products and services).

Each unique item gets its own line on the invoice with its name, description, quantity, and cost per item. You can also use lines for item bundles (also known as “groups”), discounts, and subtotals to an invoice.

Important: Small businesses often use the terms “products and services” instead of “items.” The QuickBooks Online customer-facing UI also uses products (inventory and non-inventory) and services. Learn more about the difference between products and services in QuickBooks Online. However, from a data perspective, the Items entity handles both products and services. This is set by the itemCategoryType attribute.

Now, let’s create an invoice that contains multiple items:

  1. Sign in to your developer account.
  2. Go to the API Explorer.
  3. In the Sandbox bar, select the sandbox company you want to test with.
  4. Select the Invoice reference section.
  5. Go to the Create an invoice section.

Add a few additional line.detailType objects for Lighting and Installation. Use the following names and IDs, but feel free to change the amount.

Lighting

Installation

When you’re done modifying the request body in the API Explorer, select the Try It link. Review the server response in the Returns sample.

Step 9: Add customers and sales tax to invoices

Add customers

To add a customer, use the customerRef and the customerRef.value attribute to identify them by their ID.

Remember, you can only have one customer per invoice. Learn more about the Customer entity.


Add and manage sales tax

QuickBooks Online handles sales tax differently depending on the region. Your app needs to account for these variations so you can support your end-users.

US-based QuickBooks Online companies

As of November 10, 2017, all new US-based QuickBooks Online company files created by customers use the automated sales tax (AST) engine. Sales tax on transactions is automatically calculated based on the entered shipping address and location of the company using QuickBooks. Previously, customers had to enter sales tax manually. Learn more about automated sales tax.

Non-US-based QuickBooks Online companies

Non-US QuickBooks Online companies manually handle sales taxes, using tax codes and tax services. Learn more about managing sales tax for non-US companies.

Step 10: Add custom fields, bundle items, discounts, and more

Let’s modify the same request body and add a bundle, a description, and a discount to the line object.

  1. Sign in to your developer account.
  2. Go to the API Explorer.
  3. In the Sandbox bar, select the sandbox company you want to test with.
  4. Select the Invoice reference section.
  5. Go to the Create an invoice section.
  6. In the Request Body code sample, review the sample request.
  7. Add the following parameters:

 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"
      }
}
  1. Select Try It.
  2. Review the response in the Returns sample.

Here’s a closer look at the request:


If you open your sandbox company, you’ll see the invoice. It should look like this:

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

x

You can further enhance invoices custom fields, or link them to other transactions such as payments.


Add custom fields

QuickBooks Online users can create their own custom-defined fields to track additional info on invoices. They set this up via their company preferences.

Query the Preferences entity to see if the user has any custom fields. Learn more about managing custom fields.

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

x

Add more data to invoices

There are other fields you can add to invoices if you need to add more details. In general, these are optional but can be very useful.

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

x

Review the Invoice entity in the API Explorer to see all possible fields, attributes, requirements, and details.


Connect invoices to payments processing

Payments received for an invoice are displayed in the LinkedTxn attribute of the Invoice entity.

Learn more about linked transactions and see how linked transactions work with payment processing.

Step 11: Review errors and validation faults

If a reference object doesn’t exist, the server 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"
}

Here’s more info about errors and fault codes.

Step 12: Query items and customers on an invoice

To see what items are on an invoice:

  1. Query the Item endpoint.
  2. Use the item.Id and item.Name attributes for the itemRef.value and itemRef.name.

To see the customer are associated with an invoice:

  1. Query the Customer endpoint.
  2. Use customer.Id and customer.DisplayName attributes for the customerRef.value and customerRef.name.
Step 13: Start developing using an SDK

Use one of our SDKs to get started. Our SDKs handle many parts of the development process for you that you’d have to otherwise set up manually.

Here are examples of how to set up invoicing features: