Implement invoicing features

If you want your app to utilize QuickBooks Online invoicing features, set up this basic invoicing implementation.

Step 1: Learn about basic accounting implementations

For your app’s implementations, make sure you pre-create entities so your app can reference them in transactions.

Transactions in QuickBooks frequently need to reference common entities such as account, taxcode, or customer. If you have pre-created versions of common objects and entities, all your app needs to do is reference their IDs while creating transactions such as invoices and bills.

If these entities don’t already exist, the transactions your app creates won’t have anything to reference. Referenced entities can’t be created on the fly within a transaction.

Note

Notes about managing invoices and automated sales tax

As of November 10, 2017, all new US-based customer-created QuickBooks Online companies use the automated sales tax (AST) engine. This engine automatically calculates sales tax 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 features.
Step 2: Code the invoicing implementation

This implementation generally does the following:


Invoicing implementations

.NET

Java

PHP

 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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
/// <summary>
                        /// This routine creates an Invoice object
                        /// </summary>
                        private void CreateInvoice()
                        {
/// Step 1: Initialize OAuth2RequestValidator and ServiceContext
                        OAuth2RequestValidator ouathValidator = new OAuth2RequestValidator(
                                (string)Application["accessToken"]);
                        ServiceContext serviceContext = new ServiceContext(
                                (string)Application["realmId"],
                                IntuitServicesType.QBO, ouathValidator);
/// Step 2: Initialize an Invoice object
                        Invoice invoice = new Invoice();
                        invoice.Deposit = new Decimal(0.00);
                        invoice.DepositSpecified = true;

/// Step 3: Invoice is always created for a customer, so retrieve reference to a customer and set it in Invoice
                        QueryService<Customer> querySvc =
                                new QueryService<Customer>(serviceContext);
                        Customer customer = querySvc.ExecuteIdsQuery
                                ("SELECT * FROM Customer WHERE CompanyName like 'Amy%'").
                                FirstOrDefault();
                        invoice.CustomerRef = new ReferenceType()
                        {
                                Value = customer.Id
                        };

/// Step 4: Invoice is always created for an item so the retrieve reference to an item and create a Line item to the invoice
                        QueryService<Item> querySvcItem =
                                new QueryService<Item>(serviceContext);
                        Item item = querySvcItem.ExecuteIdsQuery(
                                "SELECT * FROM Item WHERE Name = 'Lighting'");FirstOrDefault();
                        List<Line> lineList = new List<Line>();
                        Line line = new line();
                        line.Description = "Description";
                        line.Amount = new Decimal(100.00);
                        line.AmountSpecified = true;
                        lineList.Add(line);
                        invoice.Line = lineList.ToArray();

                        SalesItemLineDetail salesItemLineDeatil = new SalesItemLineDetail();
                        salesItemLineDetail.Qty = new Decimal(1.0);
                        salesItemLineDeatil.ItemRef = new ReferenceType
                        {
                                Value = item.Id
                        };
                        line.AnyIntuitObject = salesItemLineDetail;

                        line.DetailType = LineDetailTypeEnum.SalesItemLineDetail;
                        line.DetailTypeSpecified = true;

/// Step 5: Set other properties such as total amount, due date, email status, and transaction date
                invoice.DueDate = Datetime.UtcNow.Date;
                invoice.DueDateSpecified = true;

                invoice.TotalAmt = new Decimal(10.00);
                invoice.TotalAmtSpecified = true;

                invoice.EmailStatus = EmailStatusEnums.NotSet;
                invoice.EmailStatusSpecified = true;

                invoice.Balance = new Decimal(10.00);
                invoice.BalanceSpecified = true;

                invoice.TxnDate = DateTime.UtcNow.Date;
                invoice.TxnDateSpecified = true;
                invoice.TxnTaxDetail = new TxnTaxDetail()
                {
                                TotalTax = Convert.ToDecimal(10),
                                TotalTaxSpecified = true
                };

///Step 6: Initialize the service object and create Invoice
                DataService service = new DataService(serviceContext);
                Invoice addedInvoice = service.Add<Invoice>(invoice);
}
Tip: Some methods, like creating or querying accounts, are omitted in the sample for brevity. Visit our GitHub to see the complete code.

 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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
//create oauth object
                OAuth2Authorizer oauth = new OAuth2Authorizer(accessToken);
//create context
                Context context = new Context(oauth, ServiceType.QBO, realmId);
//create DataService
                DataService service = new DataService(context);

//add customer
                Customer customer = new Customer();
                customer.setDisplayName(RandomStringUtils.randomAlphanumeric(6));
                EmailAddress emailAddr = new EmailAddress();
                emailAddr.setAddress("testconceptsample@mailinator.com");
                customer.setPrimaryEmailAddr(emailAddr);
                Customer savedCustomer = service.add(customer);

//add item
                Item item = new Item();
                item.setName("Item" + RandomStringUtils.randomAlphanumeric(5));
                item.setUnitPrice(new BigDecimal("200"));
                item.setType(ItemTypeEnum.SERVICE);
                Account incomeAccount = getIncomeBankAccount(service); //query or income account
                item.setIncomeAccountRef(createRef(incomeAccount));
                Item savedItem = service.add(item);

//create invoice using customer and item created above
                Invoice invoice = new Invoice();
                invoice.setCustomerRef(createRef(savedCustomer));
                Line line1 = new Line();
                line1.setAmount(new BigDecimal("300.00"));
                line1.setDetailType(LineDetailTypeEnum.SALES_ITEM_LINE_DETAIL);
                SalesItemLineDetail salesItemLineDetail1 = new SalesItemLineDetail();
                salesItemLineDetail1.setItemRef(createRef(savedItem));
                line1.setSalesItemLineDetail(salesItemLineDetail1);
                List<Line> lines1 = new ArrayList<>();
                lines1.add(line1);
                invoice.setLine(lines1);
                Invoice savedInvoice = service.add(invoice);

//send invoice email to customer
                service.sendEmail(savedInvoice, customer.getPrimaryEmailAddr().getAddress());

//receive payment for the invoice
                Payment payment = new Payment();
                payment.setCustomerRef(createRef(customer));
                payment.setTotalAmt(invoice.getTotalAmt());
                List<LinkedTxn> linkedTxnList = new ArrayList<LinkedTxn>();
                LinkedTxn linkedTxn = new LinkedTxn();
                linkedTxn.setTxnId(savedInvoice.getId());
                linkedTxn.setTxnType(TxnTypeEnum.TxnTypeEnum.INVOICE.value());
                linkedTxnList.add(linkedTxn);
                Line line1 = new Line();
                line1.setAmount(invoice.getTotalAmt());
                line1.setLinkedTxn(linkedTxnList);
                List<Line> lineList = new ArrayList<Line>();
                lineList.add(line1);
                payment.setLine(lineList);
                service.add(payment);
Tip: Some methods, like creating or querying accounts, are omitted in the sample for brevity. Visit our GitHub to see the complete code.

 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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
<?php
//create dataservice
                $dataService->updateOAuth2Token($accessToken);

//add customer
                $customerRequestObj = Customer::create(["DisplayName" => $customerName . getGUID()]);
                $customerRequestObj = $dataService->Add($customerRequestObj);

//add item
                $ItemObj = Item::create([
                "Name" => $itemName,
                "UnitPrice" => 25,
                "Type" => "Service",
                "IncomeAccountRef"=> ["value"=>  $incomeAccount->Id]
                ]);
                $resultingItemObj = $dataService->Add($ItemObj);

//create invoice using customer and item created above
                $invoiceObj = Invoice::create([
                "CustomerRef" => ["value" => $customerRequestObj>Id],
                "BillEmail" => ["Address" => "author@intuit.com"],
                "Line" => [
                        "Amount" => 100.00,
                        "DetailType" => "SalesItemLineDetail",
                        "SalesItemLineDetail" => [
                                "Qty" => 2,
                                "ItemRef" => ["value" => $resultingItemObj>Id]
                        ]

                ]);
                $resultingInvoiceObj = $dataService->Add($invoiceObj);

//send invoice email to customer
                $resultingMailObj = $dataService->sendEmail($resultingInvoiceObj,$resultingInvoiceObj->BillEmail->Address);

//receive payment for the invoice
                $paymentObj = Payment::create([
                        "CustomerRef" => ["value" => $customerRequestObj>Id],
                        "TotalAmt" => 100.00,
                        "Line" => [
                                "Amount" => 100.00,
                                "LinkedTxn" => ["TxnId" => $invoiceId,"TxnType" => "Invoice"]
                        ]
                ]);
                $dataService->Add($paymentObj);
        ?>
Tip: Some methods, like creating or querying accounts, are omitted in the sample for brevity. Visit our GitHub to see the complete code.
Step 3: Set up other basic implementations

Depending on what basic QuickBooks features you want your app to utilize, you can set up other basic accounting implementations: