Invoices
Stores header-level information for customer invoices, including customer details, invoice dates, terms, due dates, and balances, supporting accounts-receivable tracking and reporting.
Table Specific Information
Invoices can be inserted, queried, or updated through the Invoices or InvoiceLineItems tables. Invoices can be deleted using the Invoices table.
Select
All filterable columns support the following operators:
- =
- !=
- >=
- <=
- >
- <
- IN
- LIKE
- CONTAINS
The driver processes other filters client-side within the driver.
Insert
To create an invoice, specify a Customer and at least one Line Item. Use the LineAggregate column to provide an XML aggregate of line item data. The structure of the XML aggregate is as follows:
- Use <Line> at the base level.
- Each underscore (_) character denotes a hierarchy within the XML structure.
- The LineAggregate content is passed directly to the API.
Ensure that all values in each field match the API's required format, such as:
- Dates in yyyy-MM-dd
- Date-times in yyyy-MM-dd'T'HH:mm:sszzz
The prefix Line_ identifies columns in the aggregates that are part of the line item. Use Line_ columns along with the DocNumber to link specific lines to their corresponding invoices.
Note: When inserting an inventory item, you must also include a quantity using the <Qty> tag. Inventory items can be identified by the Type column in the Items table.
INSERT INTO Invoices (CustomerRef, LineAggregate)
VALUES ('4', '
<Line><Amount>0.01</Amount><DetailType>SalesItemLineDetail</DetailType><SalesItemLineDetail><ItemRef>2</ItemRef></SalesItemLineDetail></Line>
<Line><Amount>0.02</Amount><DetailType>SalesItemLineDetail</DetailType><SalesItemLineDetail><ItemRef>3</ItemRef></SalesItemLineDetail></Line>
<Line><Amount>0.03</Amount><DetailType>SalesItemLineDetail</DetailType><SalesItemLineDetail><ItemRef>4</ItemRef><Qty>2</Qty></SalesItemLineDetail></Line>
')
Columns
| Name | Type | ReadOnly | References | Filterable | Sortable | Description |
| Id [KEY] | String | True | True | True |
The unique identifier (Id) of the invoice record. This value is assigned by QuickBooks Online and used to reference or update the invoice in API operations. | |
| SyncToken | String | True | False | False |
Specifies the version number of the invoice object that is used to lock the record for use by one application at a time. When an application modifies an invoice, its sync token is incremented. Attempts to modify an invoice with an older sync token fail. Only the latest version of the object is maintained by QuickBooks Online. | |
| MetaData_CreateTime | Datetime | True | True | True |
The date and time when the invoice record was created in QuickBooks Online. | |
| MetaData_LastUpdatedTime | Datetime | True | True | True |
The date and time when the invoice record was last updated in QuickBooks Online. | |
| CustomFieldAggregate | String | False | False | False |
An XML-formatted aggregate of custom field information linked to this invoice. This structure allows you to retrieve all custom field names and values in a single field for downstream processing or display. | |
| DocNumber | String | False | True | True |
The reference number that is assigned to the invoice transaction. This number often appears on customer-facing documents and can be used to match the invoice with external systems. | |
| TxnDate | Date | False | True | True |
The date the user entered when the invoice transaction occurred. This is the effective transaction date used in reporting and aging. | |
| PrivateNote | String | False | False | False |
A private note attached to the invoice that does not appear on the printed or emailed transaction sent to the customer. | |
| LinkedTxnAggregate | String | False | False | False |
An XML-formatted aggregate of transactions linked to the invoice, such as payments or credit memos. This field allows you to see all related transactions without querying each individually. | |
| LineAggregate | String | False | False | False |
An XML-formatted aggregate of all line items associated with the invoice, including product or service items, discounts, and subtotals. This field lets you access every line item and its attributes in a single read for reporting or data export. | |
| TxnTaxDetail_TxnTaxCodeRef | String | False |
TaxCodes.Id | False | False |
Specifies the tax code that is applied to the overall invoice. This tax code determines which tax rules and rates are used to calculate taxes on all applicable line items. |
| TxnTaxDetail_TotalTax | String | False | False | False |
The total tax that is calculated for the invoice. This amount excludes any manually inserted tax lines in the transaction line list, making it easier to separate system-calculated taxes from manual adjustments. | |
| TxnTaxDetail_TaxLineAggregate | String | False | False | False |
An XML-formatted aggregate of the individual tax line items associated with the invoice. This structure provides details for each tax component—such as jurisdiction and rate—used to calculate the total tax. | |
| CustomerRef | String | False |
Customers.Id | True | False |
The unique identifier of the customer linked to this invoice. This value maps the invoice back to the customer's record in QuickBooks Online. |
| CustomerRef_Name | String | True |
Customers.DisplayName | False | False |
The name of the customer linked to this invoice. This value is retrieved from the Customer record for easier human-readable display and reporting. |
| CustomerMemo | String | False | False | False |
A message or note intended for the customer that appears on the invoice itself and in any printed or emailed copies. | |
| BillAddr_Id | String | False | False | False |
The unique identifier of the entity for the billing address, mainly used for modifying the address on this invoice. This identifier is assigned by the QuickBooks Online data service. | |
| BillAddr_Line1 | String | False | False | False |
The first line of the billing address that is associated with the invoice. | |
| BillAddr_Line2 | String | False | False | False |
The second line of the billing address that is associated with the invoice. | |
| BillAddr_Line3 | String | False | False | False |
The third line of the billing address that is associated with the invoice. | |
| BillAddr_Line4 | String | False | False | False |
The fourth line of the billing address that is associated with the invoice. | |
| BillAddr_Line5 | String | False | False | False |
The fifth line of the billing address that is associated with the invoice. | |
| BillAddr_City | String | False | False | False |
The city name in the billing address. | |
| BillAddr_Country | String | False | False | False |
The country name in the billing address. | |
| BillAddr_CountrySubDivisionCode | String | False | False | False |
Specifies the region within a country in the billing address. For example, this value is the state name for the USA or the province name for Canada. | |
| BillAddr_PostalCode | String | False | False | False |
Specifies the postal code in the billing address. For example, this value is the ZIP code for the USA or the postal code for Canada. | |
| BillAddr_Lat | String | False | False | False |
The latitude coordinate of the geocoded billing address for mapping or validation purposes. | |
| BillAddr_Long | String | False | False | False |
The longitude coordinate of the geocoded billing address for mapping or validation purposes. | |
| ShipAddr_Id | String | False | False | False |
The unique Id of the entity for the shipping address, mainly used for modifying the address. This Id is assigned by the QuickBooks Online data service. | |
| ShipAddr_Line1 | String | False | False | False |
The first line of the shipping address that is associated with the invoice. | |
| ShipAddr_Line2 | String | False | False | False |
The second line of the shipping address that is associated with the invoice. | |
| ShipAddr_Line3 | String | False | False | False |
The third line of the shipping address that is associated with the invoice. | |
| ShipAddr_Line4 | String | False | False | False |
The fourth line of the shipping address that is associated with the invoice. | |
| ShipAddr_Line5 | String | False | False | False |
The fifth line of the shipping address that is associated with the invoice. | |
| ShipAddr_City | String | False | False | False |
The city name in the shipping address. | |
| ShipAddr_Country | String | False | False | False |
The country name in the shipping address. | |
| ShipAddr_CountrySubDivisionCode | String | False | False | False |
Specifies the region within a country in the shipping address. For example, this value is the state name for the USA or the province name for Canada. | |
| ShipAddr_PostalCode | String | False | False | False |
Specifies the postal code in the shipping address. For example, this value is the ZIP code for the USA or the postal code for Canada. | |
| ShipAddr_Lat | String | False | False | False |
The latitude coordinate of the geocoded shipping address. This value helps pinpoint the exact location of the shipping address for logistics or reporting. | |
| ShipAddr_Long | String | False | False | False |
The longitude coordinate of the geocoded shipping address. This value works with the latitude coordinate to define the precise location. | |
| ClassRef | String | False |
Class.Id | True | False |
The unique Id of the class that is linked to this invoice transaction. Classes allow you to categorize transactions for reporting or tracking purposes. |
| ClassRef_Name | String | True |
Class.FullyQualifiedName | False | False |
The name of the class that is linked to this invoice transaction. This name helps users identify which category or class is applied. |
| SalesTermRef | String | False |
Terms.Id | False | False |
The unique Id of the sales term that is linked to this invoice transaction. Sales terms define payment expectations or conditions. |
| SalesTermRef_Name | String | True |
Terms.Name | False | False |
The name of the sales term that is linked to this invoice transaction. This value helps confirm which payment term is applied. |
| DueDate | Date | False | True | False |
The date when the invoice is due for payment, not including any early payment discounts or late payment penalties. If no date is supplied, the current server date is used. | |
| ShipMethodRef | String | False | False | False |
The unique Id of the shipping method that is linked to this invoice transaction. Shipping methods represent carriers or delivery options. | |
| ShipMethodRef_Name | String | True | False | False |
The name of the shipping method that is linked to this invoice transaction. This name helps identify which carrier or delivery option is chosen. | |
| ShipDate | Date | False | False | False |
The date scheduled for delivery of goods or services. This value can be used for scheduling fulfillment and tracking. | |
| TrackingNum | String | False | False | False |
The tracking number that is assigned by the shipping provider to monitor the delivery status of the goods associated with this invoice. | |
| TotalAmt | Decimal | True | True | True |
The total amount of the invoice. This includes the sum of all charges, allowances, discounts, and taxes applied. | |
| PrintStatus | String | False | False | False |
Indicates the print status of the invoice. This value shows whether the invoice has been printed or not. The allowed values are NotSet, NeedToPrint, PrintComplete. The default value is NotSet. | |
| EmailStatus | String | False | False | False |
Indicates the email status of the invoice. This value shows whether the invoice has been emailed, is pending to be emailed, or has another status. The allowed values are NotSet, NeedToSend, EmailSent. The default value is NotSet. | |
| BillEmail_Address | String | False | False | False |
The primary email address where the invoice is sent. If the EmailStatus attribute is set to NeedToSend, this field is required. | |
| BillEmailCc_Address | String | False | False | False |
The email address where the invoice is sent as a carbon copy (CC). This field allows additional recipients to be copied on the invoice email. | |
| BillEmailBcc_Address | String | False | False | False |
The email address where the invoice is sent as a blind carbon copy (BCC). This field allows additional recipients to receive the invoice email without being visible to other recipients. | |
| Balance | Decimal | True | True | True |
Indicates the current outstanding balance or finance charge for the invoice transaction. | |
| PaymentRefNum | String | False | False | False |
The reference number that is assigned to the payment applied to this invoice. This number helps cross-reference related payment records. | |
| PaymentMethodRef | String | False | False | False |
The unique Id of the payment method that is linked to this invoice. This identifies how the payment was or will be made. | |
| PaymentMethodRef_Name | String | True |
PaymentMethods.Name | False | False |
The name of the payment method that is linked to this invoice. This name helps users recognize which payment option is selected. |
| DepositToAccountRef | String | False |
Accounts.Id | False | False |
The unique Id of the asset account where the payment money for this invoice is deposited. If you do not specify this account, QuickBooks Online defaults to the Undeposited Funds account. |
| DepositToAccountRef_Name | String | True |
Accounts.Name | False | False |
The name of the asset account where the payment money for this invoice is deposited. If you do not specify this account, QuickBooks Online defaults to the Undeposited Funds account. |
| DeliveryInfo_DeliveryType | String | False | False | False |
Specifies the type of delivery used for the invoice, such as email or postal mail. This field is used to confirm that the email has been sent via the send operation. | |
| DeliveryInfo_DeliveryTime | Datetime | False | False | False |
The date and time when the invoice was delivered. This timestamp confirms when the send operation occurred. | |
| Deposit | Decimal | False | False | False |
The deposit amount already applied toward this invoice. This value reduces the total due. | |
| DepartmentRef | String | False |
Departments.Id | False | False |
The unique Id of the department where the transaction is recorded, as defined using location tracking in QuickBooks Online. |
| DepartmentRef_Name | String | True |
Departments.Name | False | False |
The name of the department where the transaction is recorded, as defined using location tracking in QuickBooks Online. |
| AllowOnlineCreditCardPayment | Boolean | False | False | False |
Specifies whether online credit card payments are allowed for this invoice. This corresponds to the 'Cards' online payment checkbox on the QuickBooks UI. | |
| ApplyTaxAfterDiscount | Boolean | False | False | False |
Indicates whether discounts are applied before tax is calculated. Set this to true to apply discounts before tax. | |
| CurrencyRef | String | False | False | False |
The unique Id of the currency used in this invoice transaction. | |
| CurrencyRef_Name | String | True | False | False |
The name of the currency used in this invoice transaction. This name helps identify which currency values are denominated in. | |
| ExchangeRate | Decimal | False | False | False |
The currency exchange rate that is used for this invoice transaction. This field is valid only when the company file is set up for multicurrency. QuickBooks records exchange rates as the number of home currency units equal to one foreign currency unit. This field is available in the UK, AU, and CA editions. | |
| GlobalTaxCalculation | String | False | False | False |
The method used to apply tax for this invoice. This field is valid in the UK, AU, and CA editions. The allowed values are TaxExcluded, TaxInclusive, NotApplicable. | |
| HomeTotalAmt | Decimal | True | False | False |
The total amount of the invoice expressed in the home currency. This includes the sum of all charges, allowances, discounts, and taxes. This field is valid in the UK, AU, and CA editions. | |
| AllowOnlineACHPayment | Boolean | False | False | False |
Specifies whether this invoice can be paid with online bank transfers (ACH). This corresponds to the Free bank transfer online-payment checkbox on the QuickBooks UI. | |
| TransactionLocationType | String | False | False | False |
The location or branch of the account where the transaction is recorded. This field is valid only in the FR editions. The allowed values are WithinFrance, FranceOverseas, OutsideFranceWithEU, OutsideEU. | |
| InvoiceLink | String | True | False | False |
A shareable link for the invoice sent to external customers. This link allows recipients to view and pay the invoice online. | |
| ProjectRef | String | False | True | False |
The unique Id of the project that is linked to this invoice transaction. Linking a project helps track costs and revenue. | |
| RecurDataRef | String | True | False | False |
The unique Id of the recurring transaction template that this invoice was created from. This links the invoice back to its recurring template. | |
| TaxExemptionRef | String | True | False | False |
The tax exemption Id for the customer that is associated with this invoice. This Id is typically issued by the state or tax authority. | |
| FreeFormAddress | Boolean | False | False | False |
Indicates how the shipping address is stored—formatted or unformatted. The value is system-defined based on the format of the shipping address at the time the object was created. | |
| HomeBalance | Decimal | True | False | False |
The outstanding balance for this invoice expressed in the home currency. This provides a convenience view of what is still due in the home currency. |