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.

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.

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.

Get the Client ID and Client Secret for your app.

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

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

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:

• Implement basic invoicing features

There are two required objects for every invoice:

• A line item: This usually contains the product or service (i.e. Item)being sold
• A customer: The person or business you’re selling to

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:

• Since there’s only one line object, we know we’re only selling one item.
• The detailType field has a value of SaleItemLineDetail. This states that we’re selling an item. The rest of the fields cover the item’s details.
• The amount field tells us the concrete costs $100.
• The itemRef.name attribute tells us we’re selling Concrete.
• The itemRef.value attribute identifies the item’s ID. In this case, the ID is 3.
• The customerRef object identifies the customers connected to this invoice.
• The customerRef.value attribute identifies the customer’s ID. In this case, the ID is 1.
• There can only be one customerRef object per 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:

• Invoice
• Item
• Customer

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:

• detailType: SalesItemLineDetail
• name: Services
• value: 1

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

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.

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

• name: Lighting
• value: 8
• amount: [Any amount]

Installation

• name: Installation
• value: 7
• amount: [Any amount]

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.

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.

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.

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

8. Select Try It.
9. Review the response in the Returns sample.

Here’s a closer look at the request:

• The GroupItemRef.value (in this case “19”) identifies the bundle item. The bundle contains multiple individual items. You can query the Item endpoint to see what’s included.
• The precentBased attribute value is true. This means the discount was applied as a percent. The discountPercent attribute determines the discount amount (in this case 10%).

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

x

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

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.

x

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.

x

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

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.

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.

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.

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:

• Java create an invoice example
• .NET create an invoice example
• PHP create an invoice example