invoice

An Invoice represents a sales form where the customer pays for a product or service later.

Business Rules

  • An invoice must have at least one Line for either a sales item or an inline subtotal.
  • An invoice must have CustomerRef populated.
  • The DocNumber attribute is populated automatically by the data service if not supplied.
  • If ShipAddr, BillAddr, or both are not provided, the appropriate customer address from the referenced Customer object is used to fill those values.
  • If you have a large number of invoice and corresponding payment records that you wish to import to the QuickBooks Online company, sort the invoice and payment records in chronological order and use the batch resource to send invoice and payments batches of 25, one after the other, to ensure any open invoices get credited with their payments.

The invoice object

SAMPLE OBJECT
<IntuitResponse xmlns="http://schema.intuit.com/finance/v3" time="2015-07-24T10:44:52.998-07:00"> <Invoice domain="QBO" sparse="false"> <Id>130</Id> <SyncToken>0</SyncToken> <MetaData> <CreateTime>2014-09-19T13:16:17-07:00</CreateTime> <LastUpdatedTime>2014-09-19T13:16:17-07:00</LastUpdatedTime> </MetaData> <CustomField> <DefinitionId>1</DefinitionId> <Name>Crew #</Name> <Type>StringType</Type> <StringValue>102</StringValue> </CustomField> <DocNumber>1037</DocNumber> <TxnDate>2014-09-19</TxnDate> <LinkedTxn> <TxnId>100</TxnId> <TxnType>Estimate</TxnType> </LinkedTxn> <Line> <Id>1</Id> <LineNum>1</LineNum> <Description>Rock Fountain</Description> <Amount>275.00</Amount> <DetailType>SalesItemLineDetail</DetailType> <SalesItemLineDetail> <ItemRef name="Rock Fountain">5</ItemRef> <UnitPrice>275</UnitPrice> <Qty>1</Qty> <TaxCodeRef>TAX</TaxCodeRef> </SalesItemLineDetail> </Line> <Line> <Id>2</Id> <LineNum>2</LineNum> <Description>Fountain Pump</Description> <Amount>12.75</Amount> <DetailType>SalesItemLineDetail</DetailType> <SalesItemLineDetail> <ItemRef name="Pump">11</ItemRef> <UnitPrice>12.75</UnitPrice> <Qty>1</Qty> <TaxCodeRef>TAX</TaxCodeRef> </SalesItemLineDetail> </Line> <Line> <Id>3</Id> <LineNum>3</LineNum> <Description>Concrete for fountain installation</Description> <Amount>47.50</Amount> <DetailType>SalesItemLineDetail</DetailType> <SalesItemLineDetail> <ItemRef name="Concrete">3</ItemRef> <UnitPrice>9.5</UnitPrice> <Qty>5</Qty> <TaxCodeRef>TAX</TaxCodeRef> </SalesItemLineDetail> </Line> <Line> <Amount>335.25</Amount> <DetailType>SubTotalLineDetail</DetailType> <SubTotalLineDetail /> </Line> <TxnTaxDetail> <TxnTaxCodeRef>2</TxnTaxCodeRef> <TotalTax>26.82</TotalTax> <TaxLine> <Amount>26.82</Amount> <DetailType>TaxLineDetail</DetailType> <TaxLineDetail> <TaxRateRef>3</TaxRateRef> <PercentBased>true</PercentBased> <TaxPercent>8</TaxPercent> <NetAmountTaxable>335.25</NetAmountTaxable> </TaxLineDetail> </TaxLine> </TxnTaxDetail> <CustomerRef name="Sonnenschein Family Store">24</CustomerRef> <CustomerMemo>Thank you for your business and have a great day!</CustomerMemo> <BillAddr> <Id>95</Id> <Line1>Russ Sonnenschein</Line1> <Line2>Sonnenschein Family Store</Line2> <Line3>5647 Cypress Hill Ave.</Line3> <Line4>Middlefield, CA 94303</Line4> <Lat>37.4238562</Lat> <Long>-122.1141681</Long> </BillAddr> <ShipAddr> <Id>25</Id> <Line1>5647 Cypress Hill Ave.</Line1> <City>Middlefield</City> <CountrySubDivisionCode>CA</CountrySubDivisionCode> <PostalCode>94303</PostalCode> <Lat>37.4238562</Lat> <Long>-122.1141681</Long> </ShipAddr> <SalesTermRef>3</SalesTermRef> <DueDate>2014-10-19</DueDate> <TotalAmt>362.07</TotalAmt> <ApplyTaxAfterDiscount>false</ApplyTaxAfterDiscount> <PrintStatus>NeedToPrint</PrintStatus> <EmailStatus>NotSet</EmailStatus> <BillEmail> <Address>Familiystore@intuit.com</Address> </BillEmail> <Balance>362.07</Balance> <Deposit>0</Deposit> </Invoice> </IntuitResponse>

SAMPLE OBJECT
{ "Invoice": { "Deposit": 0, "domain": "QBO", "sparse": false, "Id": "130", "SyncToken": "0", "MetaData": { "CreateTime": "2014-09-19T13:16:17-07:00", "LastUpdatedTime": "2014-09-19T13:16:17-07:00" }, "CustomField": [{ "DefinitionId": "1", "Name": "Crew #", "Type": "StringType", "StringValue": "102" }], "DocNumber": "1037", "TxnDate": "2014-09-19", "LinkedTxn": [{ "TxnId": "100", "TxnType": "Estimate" }], "Line": [{ "Id": "1", "LineNum": 1, "Description": "Rock Fountain", "Amount": 275.0, "DetailType": "SalesItemLineDetail", "SalesItemLineDetail": { "ItemRef": { "value": "5", "name": "Rock Fountain" }, "UnitPrice": 275, "Qty": 1, "TaxCodeRef": { "value": "TAX" } } }, { "Id": "2", "LineNum": 2, "Description": "Fountain Pump", "Amount": 12.75, "DetailType": "SalesItemLineDetail", "SalesItemLineDetail": { "ItemRef": { "value": "11", "name": "Pump" }, "UnitPrice": 12.75, "Qty": 1, "TaxCodeRef": { "value": "TAX" } } }, { "Id": "3", "LineNum": 3, "Description": "Concrete for fountain installation", "Amount": 47.5, "DetailType": "SalesItemLineDetail", "SalesItemLineDetail": { "ItemRef": { "value": "3", "name": "Concrete" }, "UnitPrice": 9.5, "Qty": 5, "TaxCodeRef": { "value": "TAX" } } }, { "Amount": 335.25, "DetailType": "SubTotalLineDetail", "SubTotalLineDetail": {} }], "TxnTaxDetail": { "TxnTaxCodeRef": { "value": "2" }, "TotalTax": 26.82, "TaxLine": [{ "Amount": 26.82, "DetailType": "TaxLineDetail", "TaxLineDetail": { "TaxRateRef": { "value": "3" }, "PercentBased": true, "TaxPercent": 8, "NetAmountTaxable": 335.25 } }] }, "CustomerRef": { "value": "24", "name": "Sonnenschein Family Store" }, "CustomerMemo": { "value": "Thank you for your business and have a great day!" }, "BillAddr": { "Id": "95", "Line1": "Russ Sonnenschein", "Line2": "Sonnenschein Family Store", "Line3": "5647 Cypress Hill Ave.", "Line4": "Middlefield, CA 94303", "Lat": "37.4238562", "Long": "-122.1141681" }, "ShipAddr": { "Id": "25", "Line1": "5647 Cypress Hill Ave.", "City": "Middlefield", "CountrySubDivisionCode": "CA", "PostalCode": "94303", "Lat": "37.4238562", "Long": "-122.1141681" }, "SalesTermRef": { "value": "3" }, "DueDate": "2014-10-19", "TotalAmt": 362.07, "ApplyTaxAfterDiscount": false, "PrintStatus": "NeedToPrint", "EmailStatus": "NotSet", "BillEmail": { "Address": "Familiystore@intuit.com" }, "Balance": 362.07 }, "time": "2015-07-24T10:48:27.082-07:00" }

Id:
required for update
String, filterable, sortable
Unique identifier for this object.
Sort order is ASC by default.
SyncToken:
required for update
String
Version number of the object. It is used to lock an object for use by one app at a time. As soon as an application modifies an object, its SyncToken is incremented. Attempts to modify an object specifying an older SyncToken fails. Only the latest version of the object is maintained by QuickBooks Online.
MetaData:
optional
ModificationMetaData
Descriptive information about the object. The MetaData values are set by Data Services and are read only for all applications.
CustomField [0..3]:
optional
CustomField
Custom field or data extension.
DocNumber:
optional
String, maximum of 21 chars, filterable, sortable
Reference number for the transaction. If not explicitly provided at create time, this field is populated based on the setting of Preferences:CustomTxnNumber as follows:
  • If Preferences:CustomTxnNumber is true a custom value can be provided. If no value is supplied, the resulting DocNumber is null.
  • If Preferences:CustomTxnNumber is false, resulting DocNumber is system generated by incrementing the last number by 1.
If Preferences:CustomTxnNumber is false and a value is supplied, that value is stored even if it is a duplicate. Recommended best practice: check the setting of Preferences:CustomTxnNumber before setting DocNumber.
Sort order is ASC by default.
TxnDate:
optional
Date, filterable, sortable, default is current server date
The date entered by the user when this transaction occurred.
For posting transactions, this is the posting date that affects the financial statements. If the date is not supplied, the current date on the server is used.
Sort order is ASC by default.
DepartmentRef:
optional
ReferenceType, default is null
A reference to a Department object specifying the location of the transaction. Available if Preferences.AccountingInfoPrefs.TrackDepartments is set to true.
Query the Department name list resource to determine the appropriate department object for this reference. Use Department.Id and Department.Name from that object for DepartmentRef.value and DepartmentRef.name, respectively.
PrivateNote:
optional
String, max of 4000 chars
User entered, organization-private note about the transaction. This note does not appear on the invoice to the customer. This field maps to the Statement Memo field on the Invoice form in the QuickBooks Online UI.
LinkedTxn[0..n]:
optional
LinkedTxn
Zero or more related transactions to this Invoice object. The following linked relationships are supported:
  • Links to Estimate and TimeActivity objects can be established directly to this Invoice object with UI or with the API. Create, Read, Update, and Query operations are avaialble at the API level for these types of links.
  • Links to expenses incurred on behalf of the customer are returned in the response with LinkedTxn.TxnType set to ReimburseCharge, ChargeCredit or StatementCharge corresponding to billable customer expenses of type Cash, Delayed Credit, and Delayed Charge, respectively. Links to these types of transactions are established within the QuickBooks UI, only, and are available as read-only at the API level.
  • Links to payments applied to an Invoice object are returned in the response with LinkedTxn.TxnType set to Payment. Links to Payment transactions are established within the QuickBooks UI, only, and are available as read-only at the API level.

Use LinkedTxn.TxnId as the ID in a separate read request for the specific resource to retrieve details of the linked object.
Line [0..n]:
required
Line
Individual line items of a transaction. Valid Line types include:
Sales item line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Group item line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
DetailType:
required
LineDetailTypeEnum
Set to GroupLineDetailfor this type of line.
GroupLineDetail:
required
GroupLineDetail
GroupItemRef:
optional
ReferenceType
Reference to a group item for all the lines that belong to the bundle. Query the Item name list resource to determine the appropriate Item group object (Item.Type=Group) for this reference. Use Item.Id and Item.Name from that object for GroupItemRef.value and GroupItemRef.name, respectively.
Quantity:
optional
Decimal, default is 1
Quantity of the group item.
Line [0..n]:
optional
Line
Individual ItemLine elements that comprise a bundle. Returned in responses.
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Description only (also used for inline Subtotal lines):
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars A string representing one of the following:
  • Free form text description of the line item that appears in the printed record.
  • A subtotal line inline with other lines on the sales form and holds the sum of amounts on all lines above it. This is distinct from the overall transaction subtotal represented with a SubTotal detail line.
    • In create requests, set to Subtotal: (case sensitive) to create the subtotal line; the amount is generated by QuickBooks Online business logic.
    • In read requests, lines with Subtotal: nn.nn returned in this field denote subtotal lines in the object.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to DescriptionOnlyfor this type of line.
DescriptionLineDetail:
optional
DescriptionLineDetail
ServiceDate:
optional
Date
Date when the service is performed.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.

Discount line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation. Not supported for BillPayment, Estimate, Invoice, or Payment objects.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to DiscountLineDetailfor this type of line.
DiscountLineDetail:
optional
DiscountLineDetail
Discount detail type for the entire transaction. This is in contrast to a discount applied to a specific line. The company preference Sales Form Entry | Discounts must be enabled for this type of line to be available.
PercentBased:
optional
Boolean
True if the discount is a percentage; null or false if discount based on amount.
DiscountPercent:
optional
Decimal
Percentage by which the amount due is reduced, from 0% to 100%. To enter a discount of 8.5% use 8.5, not 0.085.
DiscountAccountRef:
optional
ReferenceType
Income account used to track discounts. Query the Account name list resource to determine the appropriate Account object for this reference, where Account.AccountType=Income and Account.AccountSubType=DiscountsRefundsGiven. Use Account.Id and Account.Name from that object for DiscountAccountRef.value and DiscountAccountRef.name, respectively.
ClassRef:
optional
ReferenceType
Reference to the Class associated with this discount. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
TaxCodeRef:
optional
ReferenceType
The TaxCodeassociated with the sales tax for the expense. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.

Subtotal Line (used for the overall transaction)
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to SubtotalLineDetailfor this type of line.
SubtotalLineDetail:
optional
Subtotal LineDetail
ItemRef:
optional
ReferenceType
Reference to the Item. Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively. When a line lacks an ItemRef it is treated as documentation and the Line.Amount attribute is ignored.
For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
TxnTaxDetail:
optional
TxnTaxDetail
This data type provides information for taxes charged on the transaction as a whole. It captures the details sales taxes calculated for the transaction based on the tax codes referenced by the transaction. This can be calculated by QuickBooks business logic or you may supply it when adding a transaction. See Global tax model for more information about this element.
CustomerRef:
required
ReferenceType, filterable
Reference to a customer or job. Query the Customer name list resource to determine the appropriate Customer object for this reference. Use Customer.Id and Customer.DisplayName from that object for CustomerRef.value and CustomerRef.name, respectively.
CustomerMemo:
optional
MemoRef
User-entered message to the customer; this message is visible to end user on their transactions.
BillAddr:
optional
PhysicalAddress
Bill-to address of the Invoice. If BillAddris not specified, and a default Customer:BillingAddr is specified in QuickBooks for this customer, the default bill-to address is used by QuickBooks.
ShipAddr:
optional
PhysicalAddress
Identifies the address where the goods must be shipped. If ShipAddris not specified, and a default Customer:ShippingAddr is specified in QuickBooks for this customer, the default ship-to address will be used by QuickBooks.
ClassRef:
optional
ReferenceType
Reference to the Class associated with the transaction. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerTxn is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
SalesTermRef:
optional
ReferenceType, filterable
Reference to the sales term associated with the transaction. Query the Term name list resource to determine the appropriate Term object for this reference. Use Term.Id and Term.Name from that object for SalesTermRef.value and SalesTermRef.name, respectively.
DueDate:
optional
Date, filterable, sortable
Date when the payment of the transaction is due. If date is not provided, the number of days specified in SalesTermRef added the transaction date will be used.
GlobalTaxCalculation:
optional
GlobalTaxCalculationEnum, default is TaxExcluded
Method in which tax is applied. Allowed values are: TaxExcluded, TaxInclusive, and NotApplicable.
ShipMethodRef:
optional
ReferenceType
Reference to the ShipMethod associated with the transaction. There is no shipping method list. Reference resolves to a string.
ShipDate:
optional
Date, default is null
Date for delivery of goods or services.
TrackingNum:
optional
String
Shipping provider's tracking number for the delivery of the goods associated with the transaction.
TotalAmt:
optional
BigDecimal
Indicates the total amount of the transaction. This includes the total of all the charges, allowances, and taxes. Calculated by QuickBooks business logic; any value you supply is over-written by QuickBooks.
CurrencyRef:
required if multicurrency is enabled for the company
CurrencyRefType
Reference to the currency in which all amounts on the associated transaction are expressed. This must be defined if multicurrency is enabled for the company.
Multicurrency is enabled for the company if Preferences.MultiCurrencyEnabled is set to true. Read more about multicurrency support here.
ExchangeRate:
optional
Decimal, default is 1, applicable if multicurrency is enabled for the company
The number of home currency units it takes to equal one unit of currency specified by CurrencyRef.
HomeTotalAmt:
optional
Decimal, read-only, applicable if multicurrency is enabled for the company
Total amount of the transaction in the home currency. Includes the total of all the charges, allowances and taxes. Calculated by QuickBooks business logic.
Value is valid only when CurrencyRef is specified.
HomeBalance:
optional
minor version 3
Decimal, read-only, applicable if multicurrency is enabled for the company
Convenience field containing the amount in Balance expressed in terms of the home currency. Calculated by QuickBooks business logic.
Value is valid only when CurrencyRef is specified and available when endpoint is evoked with the minorversion=3 query parameter.
ApplyTaxAfterDiscount:
optional
Boolean, default is false
If false or null, calculate the sales tax first, and then apply the discount. If true, subtract the discount first and then calculate the sales tax.
PrintStatus:
optional
String, default is NotSet
; Printing status of the invoice.
Valid values: NotSet, NeedToPrint, PrintComplete .
EmailStatus:
optional
String, default is NotSet
Email status of the invoice.
Valid values: NotSet, NeedToSend, EmailSent
BillEmail:
optional
EmailAddress
Identifies the e-mail address where the invoice is sent. If EmailStatus=NeedToSend, BillEmailis a required input.
BillEmailCc:
optional
minor version 8
EmailAddress
Identifies the carbon copy e-mail address where the invoice is sent. If not specified, this field is populated from that defined in Preferences.SalesFormsPrefs.SalesEmailCc. If this email address is invalid, carbon copy email is not sent.
BillEmailBcc:
optional
minor version 8
EmailAddress
Identifies the blind carbon copy e-mail address where the invoice is sent. If not specified, this field is populated from that defined in Preferences.SalesFormsPrefs.SalesEmailBcc. If this email address is invalid, blind carbon copy email is not sent.
DeliveryInfo:
optional
DeliveryInfo, read-only
Email delivery information. Returned when a request has been made to deliver email with the send operation.
Balance:
optional
Decimal, filterable, sortable, read-only
The balance reflecting any payments made against the transaction. Initially set to the value of TotalAmt. A Balance of 0 indicates the invoice is fully paid. Calculated by QuickBooks business logic; any value you supply is over-written by QuickBooks.
TxnSource:
optional
String
Used internally to specify originating source of a credit card transaction.
Deposit:
optional
Decimal
The deposit made towards this invoice.
TransactionLocationType:
optional
minor version 4
String, default is WithinFrance
The account location. Valid values include:
  • WithinFrance
  • FranceOverseas
  • OutsideFranceWithEU
  • OutsideEU

For France locales, only.

Create an invoice

REQUEST URL
Sandbox Base URL: https://sandbox-quickbooks.api.intuit.com
Production Base URL: https://quickbooks.api.intuit.com

Operation: POST /v3/company/<realmID>/invoice
Content type: application/json

An invoice must:

  • Have at least one Line a sales item or inline subtotal.
  • Have a populated CustomerRef element.

Request body

SAMPLE REQUEST
{ "Line": [ { "Amount": 100.00, "DetailType": "SalesItemLineDetail", "SalesItemLineDetail": { "ItemRef": { "value": "1", "name": "Services" } } } ], "CustomerRef": { "value": "1" } }

SAMPLE REQUEST
<Invoice xmlns="http://schema.intuit.com/finance/v3"> <Line> <Amount>150</Amount> <DetailType>SalesItemLineDetail</DetailType> <SalesItemLineDetail> <ItemRef>1</ItemRef> </SalesItemLineDetail> </Line> <CustomerRef>1</CustomerRef> </Invoice>

The minimum elements to create an Invoice are listed here.

Line [0..n]:
required
Invoice line object
The minimum line item required for the request is one of the following.
Sales item line type:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Group item line type:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
DetailType:
required
LineDetailTypeEnum
Set to GroupLineDetailfor this type of line.
GroupLineDetail:
required
GroupLineDetail
GroupItemRef:
optional
ReferenceType
Reference to a group item for all the lines that belong to the bundle. Query the Item name list resource to determine the appropriate Item group object (Item.Type=Group) for this reference. Use Item.Id and Item.Name from that object for GroupItemRef.value and GroupItemRef.name, respectively.
Quantity:
optional
Decimal, default is 1
Quantity of the group item.
Line [0..n]:
optional
Line
Individual ItemLine elements that comprise a bundle. Returned in responses.
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Inline subtotal using Description line type:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars A string representing one of the following:
  • Free form text description of the line item that appears in the printed record.
  • A subtotal line inline with other lines on the sales form and holds the sum of amounts on all lines above it. This is distinct from the overall transaction subtotal represented with a SubTotal detail line.
    • In create requests, set to Subtotal: (case sensitive) to create the subtotal line; the amount is generated by QuickBooks Online business logic.
    • In read requests, lines with Subtotal: nn.nn returned in this field denote subtotal lines in the object.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to DescriptionOnlyfor this type of line.
DescriptionLineDetail:
optional
DescriptionLineDetail
ServiceDate:
optional
Date
Date when the service is performed.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
CustomerRef:
required
ReferenceType, filterable
Reference to a customer or job. Query the Customer name list resource to determine the appropriate Customer object for this reference. Use Customer.Id and Customer.DisplayName from that object for CustomerRef.value and CustomerRef.name, respectively.
CurrencyRef:
required if multicurrency is enabled for the company
CurrencyRefType
Reference to the currency in which all amounts on the associated transaction are expressed. This must be defined if multicurrency is enabled for the company.
Multicurrency is enabled for the company if Preferences.MultiCurrencyEnabled is set to true. Read more about multicurrency support here.

Returns

SAMPLE RESPONSE
{ "Invoice": { "Deposit": 0, "domain": "QBO", "sparse": false, "Id": "238", "SyncToken": "0", "MetaData": { "CreateTime": "2015-07-24T10:33:39-07:00", "LastUpdatedTime": "2015-07-24T10:33:39-07:00" }, "CustomField": [{ "DefinitionId": "1", "Name": "Crew #", "Type": "StringType" }], "DocNumber": "1069", "TxnDate": "2015-07-24", "LinkedTxn": [], "Line": [{ "Id": "1", "LineNum": 1, "Amount": 100.0, "DetailType": "SalesItemLineDetail", "SalesItemLineDetail": { "ItemRef": { "value": "1", "name": "Services" }, "TaxCodeRef": { "value": "NON" } } }, { "Amount": 100.0, "DetailType": "SubTotalLineDetail", "SubTotalLineDetail": {} }], "TxnTaxDetail": { "TotalTax": 0 }, "CustomerRef": { "value": "1", "name": "Amy's Bird Sanctuary" }, "BillAddr": { "Id": "2", "Line1": "4581 Finch St.", "City": "Bayshore", "CountrySubDivisionCode": "CA", "PostalCode": "94326", "Lat": "INVALID", "Long": "INVALID" }, "ShipAddr": { "Id": "109", "Line1": "4581 Finch St.", "City": "Bayshore", "CountrySubDivisionCode": "CA", "PostalCode": "94326", "Lat": "INVALID", "Long": "INVALID" }, "DueDate": "2015-08-23", "TotalAmt": 100.0, "ApplyTaxAfterDiscount": false, "PrintStatus": "NeedToPrint", "EmailStatus": "NotSet", "Balance": 100.0 }, "time": "2015-07-24T10:33:39.11-07:00" }

SAMPLE RESPONSE
<IntuitResponse xmlns="http://schema.intuit.com/finance/v3" time="2015-07-24T10:35:08.591-07:00"> <Invoice domain="QBO" sparse="false"> <Id>239</Id> <SyncToken>0</SyncToken> <MetaData> <CreateTime>2015-07-24T10:35:08-07:00</CreateTime> <LastUpdatedTime>2015-07-24T10:35:08-07:00</LastUpdatedTime> </MetaData> <CustomField> <DefinitionId>1</DefinitionId> <Name>Crew #</Name> <Type>StringType</Type> </CustomField> <DocNumber>1070</DocNumber> <TxnDate>2015-07-24</TxnDate> <Line> <Id>1</Id> <LineNum>1</LineNum> <Amount>150.00</Amount> <DetailType>SalesItemLineDetail</DetailType> <SalesItemLineDetail> <ItemRef name="Services">1</ItemRef> <TaxCodeRef>NON</TaxCodeRef> </SalesItemLineDetail> </Line> <Line> <Amount>150.00</Amount> <DetailType>SubTotalLineDetail</DetailType> <SubTotalLineDetail /> </Line> <TxnTaxDetail> <TotalTax>0</TotalTax> </TxnTaxDetail> <CustomerRef name="Amy's Bird Sanctuary">1</CustomerRef> <BillAddr> <Id>2</Id> <Line1>4581 Finch St.</Line1> <City>Bayshore</City> <CountrySubDivisionCode>CA</CountrySubDivisionCode> <PostalCode>94326</PostalCode> <Lat>INVALID</Lat> <Long>INVALID</Long> </BillAddr> <ShipAddr> <Id>109</Id> <Line1>4581 Finch St.</Line1> <City>Bayshore</City> <CountrySubDivisionCode>CA</CountrySubDivisionCode> <PostalCode>94326</PostalCode> <Lat>INVALID</Lat> <Long>INVALID</Long> </ShipAddr> <DueDate>2015-08-23</DueDate> <TotalAmt>150.00</TotalAmt> <ApplyTaxAfterDiscount>false</ApplyTaxAfterDiscount> <PrintStatus>NeedToPrint</PrintStatus> <EmailStatus>NotSet</EmailStatus> <Balance>150.00</Balance> <Deposit>0</Deposit> </Invoice> </IntuitResponse>

The invoice response body.

Id:
required for update
String, filterable, sortable
Unique identifier for this object.
Sort order is ASC by default.
SyncToken:
required for update
String
Version number of the object. It is used to lock an object for use by one app at a time. As soon as an application modifies an object, its SyncToken is incremented. Attempts to modify an object specifying an older SyncToken fails. Only the latest version of the object is maintained by QuickBooks Online.
MetaData:
optional
ModificationMetaData
Descriptive information about the object. The MetaData values are set by Data Services and are read only for all applications.
CustomField [0..3]:
optional
CustomField
Custom field or data extension.
DocNumber:
optional
String, maximum of 21 chars, filterable, sortable
Reference number for the transaction. If not explicitly provided at create time, this field is populated based on the setting of Preferences:CustomTxnNumber as follows:
  • If Preferences:CustomTxnNumber is true a custom value can be provided. If no value is supplied, the resulting DocNumber is null.
  • If Preferences:CustomTxnNumber is false, resulting DocNumber is system generated by incrementing the last number by 1.
If Preferences:CustomTxnNumber is false and a value is supplied, that value is stored even if it is a duplicate. Recommended best practice: check the setting of Preferences:CustomTxnNumber before setting DocNumber.
Sort order is ASC by default.
TxnDate:
optional
Date, filterable, sortable, default is current server date
The date entered by the user when this transaction occurred.
For posting transactions, this is the posting date that affects the financial statements. If the date is not supplied, the current date on the server is used.
Sort order is ASC by default.
DepartmentRef:
optional
ReferenceType, default is null
A reference to a Department object specifying the location of the transaction. Available if Preferences.AccountingInfoPrefs.TrackDepartments is set to true.
Query the Department name list resource to determine the appropriate department object for this reference. Use Department.Id and Department.Name from that object for DepartmentRef.value and DepartmentRef.name, respectively.
PrivateNote:
optional
String, max of 4000 chars
User entered, organization-private note about the transaction. This note does not appear on the invoice to the customer. This field maps to the Statement Memo field on the Invoice form in the QuickBooks Online UI.
LinkedTxn[0..n]:
optional
LinkedTxn
Zero or more related transactions to this Invoice object. The following linked relationships are supported:
  • Links to Estimate and TimeActivity objects can be established directly to this Invoice object with UI or with the API. Create, Read, Update, and Query operations are avaialble at the API level for these types of links.
  • Links to expenses incurred on behalf of the customer are returned in the response with LinkedTxn.TxnType set to ReimburseCharge, ChargeCredit or StatementCharge corresponding to billable customer expenses of type Cash, Delayed Credit, and Delayed Charge, respectively. Links to these types of transactions are established within the QuickBooks UI, only, and are available as read-only at the API level.
  • Links to payments applied to an Invoice object are returned in the response with LinkedTxn.TxnType set to Payment. Links to Payment transactions are established within the QuickBooks UI, only, and are available as read-only at the API level.

Use LinkedTxn.TxnId as the ID in a separate read request for the specific resource to retrieve details of the linked object.
Line [0..n]:
required
Line
Individual line items of a transaction. Valid Line types include:
Sales item line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Group item line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
DetailType:
required
LineDetailTypeEnum
Set to GroupLineDetailfor this type of line.
GroupLineDetail:
required
GroupLineDetail
GroupItemRef:
optional
ReferenceType
Reference to a group item for all the lines that belong to the bundle. Query the Item name list resource to determine the appropriate Item group object (Item.Type=Group) for this reference. Use Item.Id and Item.Name from that object for GroupItemRef.value and GroupItemRef.name, respectively.
Quantity:
optional
Decimal, default is 1
Quantity of the group item.
Line [0..n]:
optional
Line
Individual ItemLine elements that comprise a bundle. Returned in responses.
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Description only (also used for inline Subtotal lines):
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars A string representing one of the following:
  • Free form text description of the line item that appears in the printed record.
  • A subtotal line inline with other lines on the sales form and holds the sum of amounts on all lines above it. This is distinct from the overall transaction subtotal represented with a SubTotal detail line.
    • In create requests, set to Subtotal: (case sensitive) to create the subtotal line; the amount is generated by QuickBooks Online business logic.
    • In read requests, lines with Subtotal: nn.nn returned in this field denote subtotal lines in the object.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to DescriptionOnlyfor this type of line.
DescriptionLineDetail:
optional
DescriptionLineDetail
ServiceDate:
optional
Date
Date when the service is performed.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.

Discount line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation. Not supported for BillPayment, Estimate, Invoice, or Payment objects.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to DiscountLineDetailfor this type of line.
DiscountLineDetail:
optional
DiscountLineDetail
Discount detail type for the entire transaction. This is in contrast to a discount applied to a specific line. The company preference Sales Form Entry | Discounts must be enabled for this type of line to be available.
PercentBased:
optional
Boolean
True if the discount is a percentage; null or false if discount based on amount.
DiscountPercent:
optional
Decimal
Percentage by which the amount due is reduced, from 0% to 100%. To enter a discount of 8.5% use 8.5, not 0.085.
DiscountAccountRef:
optional
ReferenceType
Income account used to track discounts. Query the Account name list resource to determine the appropriate Account object for this reference, where Account.AccountType=Income and Account.AccountSubType=DiscountsRefundsGiven. Use Account.Id and Account.Name from that object for DiscountAccountRef.value and DiscountAccountRef.name, respectively.
ClassRef:
optional
ReferenceType
Reference to the Class associated with this discount. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
TaxCodeRef:
optional
ReferenceType
The TaxCodeassociated with the sales tax for the expense. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.

Subtotal Line (used for the overall transaction)
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to SubtotalLineDetailfor this type of line.
SubtotalLineDetail:
optional
Subtotal LineDetail
ItemRef:
optional
ReferenceType
Reference to the Item. Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively. When a line lacks an ItemRef it is treated as documentation and the Line.Amount attribute is ignored.
For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
TxnTaxDetail:
optional
TxnTaxDetail
This data type provides information for taxes charged on the transaction as a whole. It captures the details sales taxes calculated for the transaction based on the tax codes referenced by the transaction. This can be calculated by QuickBooks business logic or you may supply it when adding a transaction. See Global tax model for more information about this element.
CustomerRef:
required
ReferenceType, filterable
Reference to a customer or job. Query the Customer name list resource to determine the appropriate Customer object for this reference. Use Customer.Id and Customer.DisplayName from that object for CustomerRef.value and CustomerRef.name, respectively.
CustomerMemo:
optional
MemoRef
User-entered message to the customer; this message is visible to end user on their transactions.
BillAddr:
optional
PhysicalAddress
Bill-to address of the Invoice. If BillAddris not specified, and a default Customer:BillingAddr is specified in QuickBooks for this customer, the default bill-to address is used by QuickBooks.
ShipAddr:
optional
PhysicalAddress
Identifies the address where the goods must be shipped. If ShipAddris not specified, and a default Customer:ShippingAddr is specified in QuickBooks for this customer, the default ship-to address will be used by QuickBooks.
ClassRef:
optional
ReferenceType
Reference to the Class associated with the transaction. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerTxn is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
SalesTermRef:
optional
ReferenceType, filterable
Reference to the sales term associated with the transaction. Query the Term name list resource to determine the appropriate Term object for this reference. Use Term.Id and Term.Name from that object for SalesTermRef.value and SalesTermRef.name, respectively.
DueDate:
optional
Date, filterable, sortable
Date when the payment of the transaction is due. If date is not provided, the number of days specified in SalesTermRef added the transaction date will be used.
GlobalTaxCalculation:
optional
GlobalTaxCalculationEnum, default is TaxExcluded
Method in which tax is applied. Allowed values are: TaxExcluded, TaxInclusive, and NotApplicable.
ShipMethodRef:
optional
ReferenceType
Reference to the ShipMethod associated with the transaction. There is no shipping method list. Reference resolves to a string.
ShipDate:
optional
Date, default is null
Date for delivery of goods or services.
TrackingNum:
optional
String
Shipping provider's tracking number for the delivery of the goods associated with the transaction.
TotalAmt:
optional
BigDecimal
Indicates the total amount of the transaction. This includes the total of all the charges, allowances, and taxes. Calculated by QuickBooks business logic; any value you supply is over-written by QuickBooks.
CurrencyRef:
required if multicurrency is enabled for the company
CurrencyRefType
Reference to the currency in which all amounts on the associated transaction are expressed. This must be defined if multicurrency is enabled for the company.
Multicurrency is enabled for the company if Preferences.MultiCurrencyEnabled is set to true. Read more about multicurrency support here.
ExchangeRate:
optional
Decimal, default is 1, applicable if multicurrency is enabled for the company
The number of home currency units it takes to equal one unit of currency specified by CurrencyRef.
HomeTotalAmt:
optional
Decimal, read-only, applicable if multicurrency is enabled for the company
Total amount of the transaction in the home currency. Includes the total of all the charges, allowances and taxes. Calculated by QuickBooks business logic.
Value is valid only when CurrencyRef is specified.
HomeBalance:
optional
minor version 3
Decimal, read-only, applicable if multicurrency is enabled for the company
Convenience field containing the amount in Balance expressed in terms of the home currency. Calculated by QuickBooks business logic.
Value is valid only when CurrencyRef is specified and available when endpoint is evoked with the minorversion=3 query parameter.
ApplyTaxAfterDiscount:
optional
Boolean, default is false
If false or null, calculate the sales tax first, and then apply the discount. If true, subtract the discount first and then calculate the sales tax.
PrintStatus:
optional
String, default is NotSet
; Printing status of the invoice.
Valid values: NotSet, NeedToPrint, PrintComplete .
EmailStatus:
optional
String, default is NotSet
Email status of the invoice.
Valid values: NotSet, NeedToSend, EmailSent
BillEmail:
optional
EmailAddress
Identifies the e-mail address where the invoice is sent. If EmailStatus=NeedToSend, BillEmailis a required input.
BillEmailCc:
optional
minor version 8
EmailAddress
Identifies the carbon copy e-mail address where the invoice is sent. If not specified, this field is populated from that defined in Preferences.SalesFormsPrefs.SalesEmailCc. If this email address is invalid, carbon copy email is not sent.
BillEmailBcc:
optional
minor version 8
EmailAddress
Identifies the blind carbon copy e-mail address where the invoice is sent. If not specified, this field is populated from that defined in Preferences.SalesFormsPrefs.SalesEmailBcc. If this email address is invalid, blind carbon copy email is not sent.
DeliveryInfo:
optional
DeliveryInfo, read-only
Email delivery information. Returned when a request has been made to deliver email with the send operation.
Balance:
optional
Decimal, filterable, sortable, read-only
The balance reflecting any payments made against the transaction. Initially set to the value of TotalAmt. A Balance of 0 indicates the invoice is fully paid. Calculated by QuickBooks business logic; any value you supply is over-written by QuickBooks.
TxnSource:
optional
String
Used internally to specify originating source of a credit card transaction.
Deposit:
optional
Decimal
The deposit made towards this invoice.
TransactionLocationType:
optional
minor version 4
String, default is WithinFrance
The account location. Valid values include:
  • WithinFrance
  • FranceOverseas
  • OutsideFranceWithEU
  • OutsideEU

For France locales, only.

Read an invoice

REQUEST URL
Sandbox Base URL: https://sandbox-quickbooks.api.intuit.com
Production Base URL: https://quickbooks.api.intuit.com

Operation: GET /v3/company/<realmID>/invoice/<invoiceId>

Retrieves the details of an invoice that has been previously created.

Returns
SAMPLE RESPONSE
<IntuitResponse xmlns="http://schema.intuit.com/finance/v3" time="2015-07-24T10:44:52.998-07:00"> <Invoice domain="QBO" sparse="false"> <Id>130</Id> <SyncToken>0</SyncToken> <MetaData> <CreateTime>2014-09-19T13:16:17-07:00</CreateTime> <LastUpdatedTime>2014-09-19T13:16:17-07:00</LastUpdatedTime> </MetaData> <CustomField> <DefinitionId>1</DefinitionId> <Name>Crew #</Name> <Type>StringType</Type> <StringValue>102</StringValue> </CustomField> <DocNumber>1037</DocNumber> <TxnDate>2014-09-19</TxnDate> <LinkedTxn> <TxnId>100</TxnId> <TxnType>Estimate</TxnType> </LinkedTxn> <Line> <Id>1</Id> <LineNum>1</LineNum> <Description>Rock Fountain</Description> <Amount>275.00</Amount> <DetailType>SalesItemLineDetail</DetailType> <SalesItemLineDetail> <ItemRef name="Rock Fountain">5</ItemRef> <UnitPrice>275</UnitPrice> <Qty>1</Qty> <TaxCodeRef>TAX</TaxCodeRef> </SalesItemLineDetail> </Line> <Line> <Id>2</Id> <LineNum>2</LineNum> <Description>Fountain Pump</Description> <Amount>12.75</Amount> <DetailType>SalesItemLineDetail</DetailType> <SalesItemLineDetail> <ItemRef name="Pump">11</ItemRef> <UnitPrice>12.75</UnitPrice> <Qty>1</Qty> <TaxCodeRef>TAX</TaxCodeRef> </SalesItemLineDetail> </Line> <Line> <Id>3</Id> <LineNum>3</LineNum> <Description>Concrete for fountain installation</Description> <Amount>47.50</Amount> <DetailType>SalesItemLineDetail</DetailType> <SalesItemLineDetail> <ItemRef name="Concrete">3</ItemRef> <UnitPrice>9.5</UnitPrice> <Qty>5</Qty> <TaxCodeRef>TAX</TaxCodeRef> </SalesItemLineDetail> </Line> <Line> <Amount>335.25</Amount> <DetailType>SubTotalLineDetail</DetailType> <SubTotalLineDetail /> </Line> <TxnTaxDetail> <TxnTaxCodeRef>2</TxnTaxCodeRef> <TotalTax>26.82</TotalTax> <TaxLine> <Amount>26.82</Amount> <DetailType>TaxLineDetail</DetailType> <TaxLineDetail> <TaxRateRef>3</TaxRateRef> <PercentBased>true</PercentBased> <TaxPercent>8</TaxPercent> <NetAmountTaxable>335.25</NetAmountTaxable> </TaxLineDetail> </TaxLine> </TxnTaxDetail> <CustomerRef name="Sonnenschein Family Store">24</CustomerRef> <CustomerMemo>Thank you for your business and have a great day!</CustomerMemo> <BillAddr> <Id>95</Id> <Line1>Russ Sonnenschein</Line1> <Line2>Sonnenschein Family Store</Line2> <Line3>5647 Cypress Hill Ave.</Line3> <Line4>Middlefield, CA 94303</Line4> <Lat>37.4238562</Lat> <Long>-122.1141681</Long> </BillAddr> <ShipAddr> <Id>25</Id> <Line1>5647 Cypress Hill Ave.</Line1> <City>Middlefield</City> <CountrySubDivisionCode>CA</CountrySubDivisionCode> <PostalCode>94303</PostalCode> <Lat>37.4238562</Lat> <Long>-122.1141681</Long> </ShipAddr> <SalesTermRef>3</SalesTermRef> <DueDate>2014-10-19</DueDate> <TotalAmt>362.07</TotalAmt> <ApplyTaxAfterDiscount>false</ApplyTaxAfterDiscount> <PrintStatus>NeedToPrint</PrintStatus> <EmailStatus>NotSet</EmailStatus> <BillEmail> <Address>Familiystore@intuit.com</Address> </BillEmail> <Balance>362.07</Balance> <Deposit>0</Deposit> </Invoice> </IntuitResponse>

SAMPLE RESPONSE
{ "Invoice": { "Deposit": 0, "domain": "QBO", "sparse": false, "Id": "130", "SyncToken": "0", "MetaData": { "CreateTime": "2014-09-19T13:16:17-07:00", "LastUpdatedTime": "2014-09-19T13:16:17-07:00" }, "CustomField": [{ "DefinitionId": "1", "Name": "Crew #", "Type": "StringType", "StringValue": "102" }], "DocNumber": "1037", "TxnDate": "2014-09-19", "LinkedTxn": [{ "TxnId": "100", "TxnType": "Estimate" }], "Line": [{ "Id": "1", "LineNum": 1, "Description": "Rock Fountain", "Amount": 275.0, "DetailType": "SalesItemLineDetail", "SalesItemLineDetail": { "ItemRef": { "value": "5", "name": "Rock Fountain" }, "UnitPrice": 275, "Qty": 1, "TaxCodeRef": { "value": "TAX" } } }, { "Id": "2", "LineNum": 2, "Description": "Fountain Pump", "Amount": 12.75, "DetailType": "SalesItemLineDetail", "SalesItemLineDetail": { "ItemRef": { "value": "11", "name": "Pump" }, "UnitPrice": 12.75, "Qty": 1, "TaxCodeRef": { "value": "TAX" } } }, { "Id": "3", "LineNum": 3, "Description": "Concrete for fountain installation", "Amount": 47.5, "DetailType": "SalesItemLineDetail", "SalesItemLineDetail": { "ItemRef": { "value": "3", "name": "Concrete" }, "UnitPrice": 9.5, "Qty": 5, "TaxCodeRef": { "value": "TAX" } } }, { "Amount": 335.25, "DetailType": "SubTotalLineDetail", "SubTotalLineDetail": {} }], "TxnTaxDetail": { "TxnTaxCodeRef": { "value": "2" }, "TotalTax": 26.82, "TaxLine": [{ "Amount": 26.82, "DetailType": "TaxLineDetail", "TaxLineDetail": { "TaxRateRef": { "value": "3" }, "PercentBased": true, "TaxPercent": 8, "NetAmountTaxable": 335.25 } }] }, "CustomerRef": { "value": "24", "name": "Sonnenschein Family Store" }, "CustomerMemo": { "value": "Thank you for your business and have a great day!" }, "BillAddr": { "Id": "95", "Line1": "Russ Sonnenschein", "Line2": "Sonnenschein Family Store", "Line3": "5647 Cypress Hill Ave.", "Line4": "Middlefield, CA 94303", "Lat": "37.4238562", "Long": "-122.1141681" }, "ShipAddr": { "Id": "25", "Line1": "5647 Cypress Hill Ave.", "City": "Middlefield", "CountrySubDivisionCode": "CA", "PostalCode": "94303", "Lat": "37.4238562", "Long": "-122.1141681" }, "SalesTermRef": { "value": "3" }, "DueDate": "2014-10-19", "TotalAmt": 362.07, "ApplyTaxAfterDiscount": false, "PrintStatus": "NeedToPrint", "EmailStatus": "NotSet", "BillEmail": { "Address": "Familiystore@intuit.com" }, "Balance": 362.07 }, "time": "2015-07-24T10:48:27.082-07:00" }

The invoice response body.

Id:
required for update
String, filterable, sortable
Unique identifier for this object.
Sort order is ASC by default.
SyncToken:
required for update
String
Version number of the object. It is used to lock an object for use by one app at a time. As soon as an application modifies an object, its SyncToken is incremented. Attempts to modify an object specifying an older SyncToken fails. Only the latest version of the object is maintained by QuickBooks Online.
MetaData:
optional
ModificationMetaData
Descriptive information about the object. The MetaData values are set by Data Services and are read only for all applications.
CustomField [0..3]:
optional
CustomField
Custom field or data extension.
DocNumber:
optional
String, maximum of 21 chars, filterable, sortable
Reference number for the transaction. If not explicitly provided at create time, this field is populated based on the setting of Preferences:CustomTxnNumber as follows:
  • If Preferences:CustomTxnNumber is true a custom value can be provided. If no value is supplied, the resulting DocNumber is null.
  • If Preferences:CustomTxnNumber is false, resulting DocNumber is system generated by incrementing the last number by 1.
If Preferences:CustomTxnNumber is false and a value is supplied, that value is stored even if it is a duplicate. Recommended best practice: check the setting of Preferences:CustomTxnNumber before setting DocNumber.
Sort order is ASC by default.
TxnDate:
optional
Date, filterable, sortable, default is current server date
The date entered by the user when this transaction occurred.
For posting transactions, this is the posting date that affects the financial statements. If the date is not supplied, the current date on the server is used.
Sort order is ASC by default.
DepartmentRef:
optional
ReferenceType, default is null
A reference to a Department object specifying the location of the transaction. Available if Preferences.AccountingInfoPrefs.TrackDepartments is set to true.
Query the Department name list resource to determine the appropriate department object for this reference. Use Department.Id and Department.Name from that object for DepartmentRef.value and DepartmentRef.name, respectively.
PrivateNote:
optional
String, max of 4000 chars
User entered, organization-private note about the transaction. This note does not appear on the invoice to the customer. This field maps to the Statement Memo field on the Invoice form in the QuickBooks Online UI.
LinkedTxn[0..n]:
optional
LinkedTxn
Zero or more related transactions to this Invoice object. The following linked relationships are supported:
  • Links to Estimate and TimeActivity objects can be established directly to this Invoice object with UI or with the API. Create, Read, Update, and Query operations are avaialble at the API level for these types of links.
  • Links to expenses incurred on behalf of the customer are returned in the response with LinkedTxn.TxnType set to ReimburseCharge, ChargeCredit or StatementCharge corresponding to billable customer expenses of type Cash, Delayed Credit, and Delayed Charge, respectively. Links to these types of transactions are established within the QuickBooks UI, only, and are available as read-only at the API level.
  • Links to payments applied to an Invoice object are returned in the response with LinkedTxn.TxnType set to Payment. Links to Payment transactions are established within the QuickBooks UI, only, and are available as read-only at the API level.

Use LinkedTxn.TxnId as the ID in a separate read request for the specific resource to retrieve details of the linked object.
Line [0..n]:
required
Line
Individual line items of a transaction. Valid Line types include:
Sales item line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Group item line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
DetailType:
required
LineDetailTypeEnum
Set to GroupLineDetailfor this type of line.
GroupLineDetail:
required
GroupLineDetail
GroupItemRef:
optional
ReferenceType
Reference to a group item for all the lines that belong to the bundle. Query the Item name list resource to determine the appropriate Item group object (Item.Type=Group) for this reference. Use Item.Id and Item.Name from that object for GroupItemRef.value and GroupItemRef.name, respectively.
Quantity:
optional
Decimal, default is 1
Quantity of the group item.
Line [0..n]:
optional
Line
Individual ItemLine elements that comprise a bundle. Returned in responses.
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Description only (also used for inline Subtotal lines):
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars A string representing one of the following:
  • Free form text description of the line item that appears in the printed record.
  • A subtotal line inline with other lines on the sales form and holds the sum of amounts on all lines above it. This is distinct from the overall transaction subtotal represented with a SubTotal detail line.
    • In create requests, set to Subtotal: (case sensitive) to create the subtotal line; the amount is generated by QuickBooks Online business logic.
    • In read requests, lines with Subtotal: nn.nn returned in this field denote subtotal lines in the object.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to DescriptionOnlyfor this type of line.
DescriptionLineDetail:
optional
DescriptionLineDetail
ServiceDate:
optional
Date
Date when the service is performed.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.

Discount line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation. Not supported for BillPayment, Estimate, Invoice, or Payment objects.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to DiscountLineDetailfor this type of line.
DiscountLineDetail:
optional
DiscountLineDetail
Discount detail type for the entire transaction. This is in contrast to a discount applied to a specific line. The company preference Sales Form Entry | Discounts must be enabled for this type of line to be available.
PercentBased:
optional
Boolean
True if the discount is a percentage; null or false if discount based on amount.
DiscountPercent:
optional
Decimal
Percentage by which the amount due is reduced, from 0% to 100%. To enter a discount of 8.5% use 8.5, not 0.085.
DiscountAccountRef:
optional
ReferenceType
Income account used to track discounts. Query the Account name list resource to determine the appropriate Account object for this reference, where Account.AccountType=Income and Account.AccountSubType=DiscountsRefundsGiven. Use Account.Id and Account.Name from that object for DiscountAccountRef.value and DiscountAccountRef.name, respectively.
ClassRef:
optional
ReferenceType
Reference to the Class associated with this discount. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
TaxCodeRef:
optional
ReferenceType
The TaxCodeassociated with the sales tax for the expense. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.

Subtotal Line (used for the overall transaction)
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to SubtotalLineDetailfor this type of line.
SubtotalLineDetail:
optional
Subtotal LineDetail
ItemRef:
optional
ReferenceType
Reference to the Item. Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively. When a line lacks an ItemRef it is treated as documentation and the Line.Amount attribute is ignored.
For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
TxnTaxDetail:
optional
TxnTaxDetail
This data type provides information for taxes charged on the transaction as a whole. It captures the details sales taxes calculated for the transaction based on the tax codes referenced by the transaction. This can be calculated by QuickBooks business logic or you may supply it when adding a transaction. See Global tax model for more information about this element.
CustomerRef:
required
ReferenceType, filterable
Reference to a customer or job. Query the Customer name list resource to determine the appropriate Customer object for this reference. Use Customer.Id and Customer.DisplayName from that object for CustomerRef.value and CustomerRef.name, respectively.
CustomerMemo:
optional
MemoRef
User-entered message to the customer; this message is visible to end user on their transactions.
BillAddr:
optional
PhysicalAddress
Bill-to address of the Invoice. If BillAddris not specified, and a default Customer:BillingAddr is specified in QuickBooks for this customer, the default bill-to address is used by QuickBooks.
ShipAddr:
optional
PhysicalAddress
Identifies the address where the goods must be shipped. If ShipAddris not specified, and a default Customer:ShippingAddr is specified in QuickBooks for this customer, the default ship-to address will be used by QuickBooks.
ClassRef:
optional
ReferenceType
Reference to the Class associated with the transaction. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerTxn is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
SalesTermRef:
optional
ReferenceType, filterable
Reference to the sales term associated with the transaction. Query the Term name list resource to determine the appropriate Term object for this reference. Use Term.Id and Term.Name from that object for SalesTermRef.value and SalesTermRef.name, respectively.
DueDate:
optional
Date, filterable, sortable
Date when the payment of the transaction is due. If date is not provided, the number of days specified in SalesTermRef added the transaction date will be used.
GlobalTaxCalculation:
optional
GlobalTaxCalculationEnum, default is TaxExcluded
Method in which tax is applied. Allowed values are: TaxExcluded, TaxInclusive, and NotApplicable.
ShipMethodRef:
optional
ReferenceType
Reference to the ShipMethod associated with the transaction. There is no shipping method list. Reference resolves to a string.
ShipDate:
optional
Date, default is null
Date for delivery of goods or services.
TrackingNum:
optional
String
Shipping provider's tracking number for the delivery of the goods associated with the transaction.
TotalAmt:
optional
BigDecimal
Indicates the total amount of the transaction. This includes the total of all the charges, allowances, and taxes. Calculated by QuickBooks business logic; any value you supply is over-written by QuickBooks.
CurrencyRef:
required if multicurrency is enabled for the company
CurrencyRefType
Reference to the currency in which all amounts on the associated transaction are expressed. This must be defined if multicurrency is enabled for the company.
Multicurrency is enabled for the company if Preferences.MultiCurrencyEnabled is set to true. Read more about multicurrency support here.
ExchangeRate:
optional
Decimal, default is 1, applicable if multicurrency is enabled for the company
The number of home currency units it takes to equal one unit of currency specified by CurrencyRef.
HomeTotalAmt:
optional
Decimal, read-only, applicable if multicurrency is enabled for the company
Total amount of the transaction in the home currency. Includes the total of all the charges, allowances and taxes. Calculated by QuickBooks business logic.
Value is valid only when CurrencyRef is specified.
HomeBalance:
optional
minor version 3
Decimal, read-only, applicable if multicurrency is enabled for the company
Convenience field containing the amount in Balance expressed in terms of the home currency. Calculated by QuickBooks business logic.
Value is valid only when CurrencyRef is specified and available when endpoint is evoked with the minorversion=3 query parameter.
ApplyTaxAfterDiscount:
optional
Boolean, default is false
If false or null, calculate the sales tax first, and then apply the discount. If true, subtract the discount first and then calculate the sales tax.
PrintStatus:
optional
String, default is NotSet
; Printing status of the invoice.
Valid values: NotSet, NeedToPrint, PrintComplete .
EmailStatus:
optional
String, default is NotSet
Email status of the invoice.
Valid values: NotSet, NeedToSend, EmailSent
BillEmail:
optional
EmailAddress
Identifies the e-mail address where the invoice is sent. If EmailStatus=NeedToSend, BillEmailis a required input.
BillEmailCc:
optional
minor version 8
EmailAddress
Identifies the carbon copy e-mail address where the invoice is sent. If not specified, this field is populated from that defined in Preferences.SalesFormsPrefs.SalesEmailCc. If this email address is invalid, carbon copy email is not sent.
BillEmailBcc:
optional
minor version 8
EmailAddress
Identifies the blind carbon copy e-mail address where the invoice is sent. If not specified, this field is populated from that defined in Preferences.SalesFormsPrefs.SalesEmailBcc. If this email address is invalid, blind carbon copy email is not sent.
DeliveryInfo:
optional
DeliveryInfo, read-only
Email delivery information. Returned when a request has been made to deliver email with the send operation.
Balance:
optional
Decimal, filterable, sortable, read-only
The balance reflecting any payments made against the transaction. Initially set to the value of TotalAmt. A Balance of 0 indicates the invoice is fully paid. Calculated by QuickBooks business logic; any value you supply is over-written by QuickBooks.
TxnSource:
optional
String
Used internally to specify originating source of a credit card transaction.
Deposit:
optional
Decimal
The deposit made towards this invoice.
TransactionLocationType:
optional
minor version 4
String, default is WithinFrance
The account location. Valid values include:
  • WithinFrance
  • FranceOverseas
  • OutsideFranceWithEU
  • OutsideEU

For France locales, only.

Send an invoice

REQUEST URL
Sandbox Base URL: https://sandbox-quickbooks.api.intuit.com
Production Base URL: https://quickbooks.api.intuit.com

Operation: 

Using email address supplied in Invoice.BillEmail.EmailAddress: 

   POST /v3/company/<realmID>/invoice/<invoiceId>/send
   Content type: application/octet-stream

Specifying an explicit email address: 

   POST /v3/company/<realmID>/invoice/<invoiceId>/send?sendTo=<emailAddr>
   Content type: application/octet-stream

Send the specified invoice object via email. Once email is sent, the following actions happen:

  • The Invoice.EmailStatus parameter is set to EmailSent.
  • The Invoice.DeliveryInfo element is populated with sending information<./li>
  • The Invoice.BillEmail.Address parameter is updated to the address specified with the value of the sendTo query parameter, if specified.
Returns
SAMPLE RESPONSE
Response:<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <IntuitResponse xmlns="http://schema.intuit.com/finance/v3" time="2013-04-23T08:30:39.543-07:00"> <Invoice domain="QBO" sparse="false"> <Id>45</Id> <SyncToken>0</SyncToken> <MetaData> <CreateTime>2013-04-23T08:30:19-07:00</CreateTime> <LastUpdatedTime>2014-11-19T11:56:44-08:00</LastUpdatedTime> </MetaData> <CustomField> <Name>Custom 1</Name> <Type>StringType</Type> </CustomField> <CustomField> <Name>Custom 2</Name> <Type>StringType</Type> </CustomField> <CustomField> <Name>Custom 3</Name> <Type>StringType</Type> </CustomField> <DocNumber>1015</DocNumber> <TxnDate>2012-04-20</TxnDate> <CurrencyRef name="United States Dollar">USD</CurrencyRef> <Line> <Id>1</Id> <LineNum>1</LineNum> <Amount>15.00</Amount> <DetailType>SalesItemLineDetail</DetailType> <SalesItemLineDetail> <ItemRef name="Sales">1</ItemRef> <TaxCodeRef>NON</TaxCodeRef> </SalesItemLineDetail> </Line> <Line> <Amount>15.00</Amount> <DetailType>SubTotalLineDetail</DetailType> <SubTotalLineDetail/> </Line> <TxnTaxDetail> <TotalTax>0</TotalTax> </TxnTaxDetail> <CustomerRef name="QKcTQIuiGo fw8Ps8qlNZ">69</CustomerRef> <BillAddr> <Id>61</Id> <Line1>3500</Line1> <Line2>Flower Avenue</Line2> <City>LosAltos</City> <Lat>INVALID</Lat> <Long>INVALID</Long> </BillAddr> <ShipAddr> <Id>62</Id> <Line1>4500</Line1> <Line2>Lily Place</Line2> <Lat>38.5399041</Lat> <Long>-121.5582189</Long> </ShipAddr> <DueDate>2012-05-20</DueDate> <TotalAmt>15.00</TotalAmt> <ApplyTaxAfterDiscount>false</ApplyTaxAfterDiscount> <PrintStatus>NeedToPrint</PrintStatus> <EmailStatus>EmailSent</EmailStatus> <DeliveryInfo> <DeliveryType>Email</DeliveryType> <DeliveryTime>2014-11-19T11:56:28-08:00</DeliveryTime> </DeliveryInfo> <Balance>15.00</Balance> <Deposit>0</Deposit> </Invoice> </IntuitResponse>

SAMPLE RESPONSE
{ "Invoice": { "Deposit": 12.00, "domain": "QBO", "sparse": false, "Id": "96", "SyncToken": "0", "MetaData": { "CreateTime": "2013-03-14T01:42:16-07:00", "LastUpdatedTime": "2014-12-17T11:50:58-08:00" }, "CustomField": [ { "Name": "Custom 1", "Type": "StringType", "StringValue": "Custom1" }, { "Name": "Custom 2", "Type": "StringType", "StringValue": "Custom2" }, { "Name": "Custom 3", "Type": "StringType", "StringValue": "Custom3" } ], "DocNumber": "Sample_Inv#2", "TxnDate": "2013-03-14", "DepartmentRef": { "value": "1", "name": "Mountain View" }, "CurrencyRef": { "value": "USD", "name": "United States Dollar" }, "PrivateNote": "Summary for sample invoice", "Line": [ { "Id": "1", "LineNum": 1, "Description": "Sample invoice create request", "Amount": 50.00, "DetailType": "SalesItemLineDetail", "SalesItemLineDetail": { "ServiceDate": "2013-03-04", "ItemRef": { "value": "2", "name": "Hours" }, "UnitPrice": 50, "Qty": 1, "TaxCodeRef": { "value": "TAX" } } }, { "Amount": 50.00, "DetailType": "SubTotalLineDetail", "SubTotalLineDetail": {} }, { "Amount": 5.00, "DetailType": "DiscountLineDetail", "DiscountLineDetail": { "PercentBased": true, "DiscountPercent": 10, "DiscountAccountRef": { "value": "30", "name": "Discounts given" } } }, { "Amount": 2.00, "DetailType": "SalesItemLineDetail", "SalesItemLineDetail": { "ItemRef": { "value": "SHIPPING_ITEM_ID" } } } ], "TxnTaxDetail": { "TxnTaxCodeRef": { "value": "5" }, "TotalTax": 5.00, "TaxLine": [ { "Amount": 5.00, "DetailType": "TaxLineDetail", "TaxLineDetail": { "TaxRateRef": { "value": "2" }, "PercentBased": true, "TaxPercent": 10, "NetAmountTaxable": 50.00 } } ] }, "CustomerRef": { "value": "15", "name": "Mr V3 Service Customer Jr2" }, "CustomerMemo": { "value": "This is the customer message" }, "BillAddr": { "Id": "35", "Line1": "Google", "Line2": "Building 1", "Line3": "123 street", "Line4": "Dept 12", "Line5": "Cube 999", "City": "Mountain View", "Country": "USA", "CountrySubDivisionCode": "CA", "PostalCode": "95123", "Lat": "37.2374847", "Long": "-121.8277925" }, "ShipAddr": { "Id": "36", "Line1": "Intuit", "Line2": "Building 1", "Line3": "123 street", "Line4": "Dept 12", "Line5": "Cube 999", "City": "San Jose", "Country": "USA", "CountrySubDivisionCode": "CA", "PostalCode": "95123", "Lat": "37.2374847", "Long": "-121.8277925" }, "ClassRef": { "value": "200900000000000003901", "name": "Class 1" }, "SalesTermRef": { "value": "4" }, "DueDate": "2013-05-13", "ShipMethodRef": { "value": "UPS", "name": "UPS" }, "ShipDate": "2013-03-01", "TrackingNum": "123456789", "TotalAmt": 52.00, "ApplyTaxAfterDiscount": false, "PrintStatus": "NeedToPrint", "EmailStatus": "EmailSent", "DeliveryInfo": { "DeliveryType": "Email", "DeliveryTime": "2014-12-17T11:50:52-08:00" }, "BillEmail": { "Address": "test@intuit.com" }, "Balance": 40.00, "DepositToAccountRef": { "value": "4", "name": "Undeposited Funds" } }, "time": "2013-03-14T13:32:04.895-07:00" }

The invoice response body.

Id:
required for update
String, filterable, sortable
Unique identifier for this object.
Sort order is ASC by default.
SyncToken:
required for update
String
Version number of the object. It is used to lock an object for use by one app at a time. As soon as an application modifies an object, its SyncToken is incremented. Attempts to modify an object specifying an older SyncToken fails. Only the latest version of the object is maintained by QuickBooks Online.
MetaData:
optional
ModificationMetaData
Descriptive information about the object. The MetaData values are set by Data Services and are read only for all applications.
CustomField [0..3]:
optional
CustomField
Custom field or data extension.
DocNumber:
optional
String, maximum of 21 chars, filterable, sortable
Reference number for the transaction. If not explicitly provided at create time, this field is populated based on the setting of Preferences:CustomTxnNumber as follows:
  • If Preferences:CustomTxnNumber is true a custom value can be provided. If no value is supplied, the resulting DocNumber is null.
  • If Preferences:CustomTxnNumber is false, resulting DocNumber is system generated by incrementing the last number by 1.
If Preferences:CustomTxnNumber is false and a value is supplied, that value is stored even if it is a duplicate. Recommended best practice: check the setting of Preferences:CustomTxnNumber before setting DocNumber.
Sort order is ASC by default.
TxnDate:
optional
Date, filterable, sortable, default is current server date
The date entered by the user when this transaction occurred.
For posting transactions, this is the posting date that affects the financial statements. If the date is not supplied, the current date on the server is used.
Sort order is ASC by default.
DepartmentRef:
optional
ReferenceType, default is null
A reference to a Department object specifying the location of the transaction. Available if Preferences.AccountingInfoPrefs.TrackDepartments is set to true.
Query the Department name list resource to determine the appropriate department object for this reference. Use Department.Id and Department.Name from that object for DepartmentRef.value and DepartmentRef.name, respectively.
PrivateNote:
optional
String, max of 4000 chars
User entered, organization-private note about the transaction. This note does not appear on the invoice to the customer. This field maps to the Statement Memo field on the Invoice form in the QuickBooks Online UI.
LinkedTxn[0..n]:
optional
LinkedTxn
Zero or more related transactions to this Invoice object. The following linked relationships are supported:
  • Links to Estimate and TimeActivity objects can be established directly to this Invoice object with UI or with the API. Create, Read, Update, and Query operations are avaialble at the API level for these types of links.
  • Links to expenses incurred on behalf of the customer are returned in the response with LinkedTxn.TxnType set to ReimburseCharge, ChargeCredit or StatementCharge corresponding to billable customer expenses of type Cash, Delayed Credit, and Delayed Charge, respectively. Links to these types of transactions are established within the QuickBooks UI, only, and are available as read-only at the API level.
  • Links to payments applied to an Invoice object are returned in the response with LinkedTxn.TxnType set to Payment. Links to Payment transactions are established within the QuickBooks UI, only, and are available as read-only at the API level.

Use LinkedTxn.TxnId as the ID in a separate read request for the specific resource to retrieve details of the linked object.
Line [0..n]:
required
Line
Individual line items of a transaction. Valid Line types include:
Sales item line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Group item line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
DetailType:
required
LineDetailTypeEnum
Set to GroupLineDetailfor this type of line.
GroupLineDetail:
required
GroupLineDetail
GroupItemRef:
optional
ReferenceType
Reference to a group item for all the lines that belong to the bundle. Query the Item name list resource to determine the appropriate Item group object (Item.Type=Group) for this reference. Use Item.Id and Item.Name from that object for GroupItemRef.value and GroupItemRef.name, respectively.
Quantity:
optional
Decimal, default is 1
Quantity of the group item.
Line [0..n]:
optional
Line
Individual ItemLine elements that comprise a bundle. Returned in responses.
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Description only (also used for inline Subtotal lines):
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars A string representing one of the following:
  • Free form text description of the line item that appears in the printed record.
  • A subtotal line inline with other lines on the sales form and holds the sum of amounts on all lines above it. This is distinct from the overall transaction subtotal represented with a SubTotal detail line.
    • In create requests, set to Subtotal: (case sensitive) to create the subtotal line; the amount is generated by QuickBooks Online business logic.
    • In read requests, lines with Subtotal: nn.nn returned in this field denote subtotal lines in the object.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to DescriptionOnlyfor this type of line.
DescriptionLineDetail:
optional
DescriptionLineDetail
ServiceDate:
optional
Date
Date when the service is performed.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.

Discount line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation. Not supported for BillPayment, Estimate, Invoice, or Payment objects.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to DiscountLineDetailfor this type of line.
DiscountLineDetail:
optional
DiscountLineDetail
Discount detail type for the entire transaction. This is in contrast to a discount applied to a specific line. The company preference Sales Form Entry | Discounts must be enabled for this type of line to be available.
PercentBased:
optional
Boolean
True if the discount is a percentage; null or false if discount based on amount.
DiscountPercent:
optional
Decimal
Percentage by which the amount due is reduced, from 0% to 100%. To enter a discount of 8.5% use 8.5, not 0.085.
DiscountAccountRef:
optional
ReferenceType
Income account used to track discounts. Query the Account name list resource to determine the appropriate Account object for this reference, where Account.AccountType=Income and Account.AccountSubType=DiscountsRefundsGiven. Use Account.Id and Account.Name from that object for DiscountAccountRef.value and DiscountAccountRef.name, respectively.
ClassRef:
optional
ReferenceType
Reference to the Class associated with this discount. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
TaxCodeRef:
optional
ReferenceType
The TaxCodeassociated with the sales tax for the expense. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.

Subtotal Line (used for the overall transaction)
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to SubtotalLineDetailfor this type of line.
SubtotalLineDetail:
optional
Subtotal LineDetail
ItemRef:
optional
ReferenceType
Reference to the Item. Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively. When a line lacks an ItemRef it is treated as documentation and the Line.Amount attribute is ignored.
For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
TxnTaxDetail:
optional
TxnTaxDetail
This data type provides information for taxes charged on the transaction as a whole. It captures the details sales taxes calculated for the transaction based on the tax codes referenced by the transaction. This can be calculated by QuickBooks business logic or you may supply it when adding a transaction. See Global tax model for more information about this element.
CustomerRef:
required
ReferenceType, filterable
Reference to a customer or job. Query the Customer name list resource to determine the appropriate Customer object for this reference. Use Customer.Id and Customer.DisplayName from that object for CustomerRef.value and CustomerRef.name, respectively.
CustomerMemo:
optional
MemoRef
User-entered message to the customer; this message is visible to end user on their transactions.
BillAddr:
optional
PhysicalAddress
Bill-to address of the Invoice. If BillAddris not specified, and a default Customer:BillingAddr is specified in QuickBooks for this customer, the default bill-to address is used by QuickBooks.
ShipAddr:
optional
PhysicalAddress
Identifies the address where the goods must be shipped. If ShipAddris not specified, and a default Customer:ShippingAddr is specified in QuickBooks for this customer, the default ship-to address will be used by QuickBooks.
ClassRef:
optional
ReferenceType
Reference to the Class associated with the transaction. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerTxn is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
SalesTermRef:
optional
ReferenceType, filterable
Reference to the sales term associated with the transaction. Query the Term name list resource to determine the appropriate Term object for this reference. Use Term.Id and Term.Name from that object for SalesTermRef.value and SalesTermRef.name, respectively.
DueDate:
optional
Date, filterable, sortable
Date when the payment of the transaction is due. If date is not provided, the number of days specified in SalesTermRef added the transaction date will be used.
GlobalTaxCalculation:
optional
GlobalTaxCalculationEnum, default is TaxExcluded
Method in which tax is applied. Allowed values are: TaxExcluded, TaxInclusive, and NotApplicable.
ShipMethodRef:
optional
ReferenceType
Reference to the ShipMethod associated with the transaction. There is no shipping method list. Reference resolves to a string.
ShipDate:
optional
Date, default is null
Date for delivery of goods or services.
TrackingNum:
optional
String
Shipping provider's tracking number for the delivery of the goods associated with the transaction.
TotalAmt:
optional
BigDecimal
Indicates the total amount of the transaction. This includes the total of all the charges, allowances, and taxes. Calculated by QuickBooks business logic; any value you supply is over-written by QuickBooks.
CurrencyRef:
required if multicurrency is enabled for the company
CurrencyRefType
Reference to the currency in which all amounts on the associated transaction are expressed. This must be defined if multicurrency is enabled for the company.
Multicurrency is enabled for the company if Preferences.MultiCurrencyEnabled is set to true. Read more about multicurrency support here.
ExchangeRate:
optional
Decimal, default is 1, applicable if multicurrency is enabled for the company
The number of home currency units it takes to equal one unit of currency specified by CurrencyRef.
HomeTotalAmt:
optional
Decimal, read-only, applicable if multicurrency is enabled for the company
Total amount of the transaction in the home currency. Includes the total of all the charges, allowances and taxes. Calculated by QuickBooks business logic.
Value is valid only when CurrencyRef is specified.
HomeBalance:
optional
minor version 3
Decimal, read-only, applicable if multicurrency is enabled for the company
Convenience field containing the amount in Balance expressed in terms of the home currency. Calculated by QuickBooks business logic.
Value is valid only when CurrencyRef is specified and available when endpoint is evoked with the minorversion=3 query parameter.
ApplyTaxAfterDiscount:
optional
Boolean, default is false
If false or null, calculate the sales tax first, and then apply the discount. If true, subtract the discount first and then calculate the sales tax.
PrintStatus:
optional
String, default is NotSet
; Printing status of the invoice.
Valid values: NotSet, NeedToPrint, PrintComplete .
EmailStatus:
optional
String, default is NotSet
Email status of the invoice.
Valid values: NotSet, NeedToSend, EmailSent
BillEmail:
optional
EmailAddress
Identifies the e-mail address where the invoice is sent. If EmailStatus=NeedToSend, BillEmailis a required input.
BillEmailCc:
optional
minor version 8
EmailAddress
Identifies the carbon copy e-mail address where the invoice is sent. If not specified, this field is populated from that defined in Preferences.SalesFormsPrefs.SalesEmailCc. If this email address is invalid, carbon copy email is not sent.
BillEmailBcc:
optional
minor version 8
EmailAddress
Identifies the blind carbon copy e-mail address where the invoice is sent. If not specified, this field is populated from that defined in Preferences.SalesFormsPrefs.SalesEmailBcc. If this email address is invalid, blind carbon copy email is not sent.
DeliveryInfo:
optional
DeliveryInfo, read-only
Email delivery information. Returned when a request has been made to deliver email with the send operation.
Balance:
optional
Decimal, filterable, sortable, read-only
The balance reflecting any payments made against the transaction. Initially set to the value of TotalAmt. A Balance of 0 indicates the invoice is fully paid. Calculated by QuickBooks business logic; any value you supply is over-written by QuickBooks.
TxnSource:
optional
String
Used internally to specify originating source of a credit card transaction.
Deposit:
optional
Decimal
The deposit made towards this invoice.
TransactionLocationType:
optional
minor version 4
String, default is WithinFrance
The account location. Valid values include:
  • WithinFrance
  • FranceOverseas
  • OutsideFranceWithEU
  • OutsideEU

For France locales, only.

Get an invoice as PDF

REQUEST URL
Sandbox Base URL: https://sandbox-quickbooks.api.intuit.com
Production Base URL: https://quickbooks.api.intuit.com

Operation: 

GET /v3/company/<realmID>/invoice/<invoiceId>/pdf
Content type: application/pdf

Returns

This resource returns the specified object in the response body as an Adobe Portable Document Format (PDF) file. The resulting PDF file is formatted according to custom form styles in the company settings.

SAMPLE RESPONSE
%PDF-1.4 ... %%EOF

SAMPLE RESPONSE
%PDF-1.4 ... %%EOF

Delete an invoice

REQUEST URL
Sandbox Base URL: https://sandbox-quickbooks.api.intuit.com
Production Base URL: https://quickbooks.api.intuit.com

Operation: POST /v3/company/<realmID>/invoice?operation=delete
Content type: application/json or application/xml

This operation deletes the invoice object specified in the request body. Include a minimum of Invoice.Id and Invoice.SyncToken in the request body. You must unlink any linked transactions associated with the invoice object before deleting it.

Request Body

SAMPLE REQUEST
{ "Id": "33", "SyncToken": "3" }

SAMPLE REQUEST
<Invoice xmlns='http://schema.intuit.com/finance/v3' domain="QBO" sparse="false"> <Id>863</Id> <SyncToken>0</SyncToken> </Invoice>

Id:
required for update
String, filterable, sortable
Unique identifier for this object.
Sort order is ASC by default.
SyncToken:
required for update
String
Version number of the object. It is used to lock an object for use by one app at a time. As soon as an application modifies an object, its SyncToken is incremented. Attempts to modify an object specifying an older SyncToken fails. Only the latest version of the object is maintained by QuickBooks Online.
MetaData:
optional
ModificationMetaData
Descriptive information about the object. The MetaData values are set by Data Services and are read only for all applications.
CustomField [0..3]:
optional
CustomField
Custom field or data extension.
DocNumber:
optional
String, maximum of 21 chars, filterable, sortable
Reference number for the transaction. If not explicitly provided at create time, this field is populated based on the setting of Preferences:CustomTxnNumber as follows:
  • If Preferences:CustomTxnNumber is true a custom value can be provided. If no value is supplied, the resulting DocNumber is null.
  • If Preferences:CustomTxnNumber is false, resulting DocNumber is system generated by incrementing the last number by 1.
If Preferences:CustomTxnNumber is false and a value is supplied, that value is stored even if it is a duplicate. Recommended best practice: check the setting of Preferences:CustomTxnNumber before setting DocNumber.
Sort order is ASC by default.
TxnDate:
optional
Date, filterable, sortable, default is current server date
The date entered by the user when this transaction occurred.
For posting transactions, this is the posting date that affects the financial statements. If the date is not supplied, the current date on the server is used.
Sort order is ASC by default.
DepartmentRef:
optional
ReferenceType, default is null
A reference to a Department object specifying the location of the transaction. Available if Preferences.AccountingInfoPrefs.TrackDepartments is set to true.
Query the Department name list resource to determine the appropriate department object for this reference. Use Department.Id and Department.Name from that object for DepartmentRef.value and DepartmentRef.name, respectively.
PrivateNote:
optional
String, max of 4000 chars
User entered, organization-private note about the transaction. This note does not appear on the invoice to the customer. This field maps to the Statement Memo field on the Invoice form in the QuickBooks Online UI.
LinkedTxn[0..n]:
optional
LinkedTxn
Zero or more related transactions to this Invoice object. The following linked relationships are supported:
  • Links to Estimate and TimeActivity objects can be established directly to this Invoice object with UI or with the API. Create, Read, Update, and Query operations are avaialble at the API level for these types of links.
  • Links to expenses incurred on behalf of the customer are returned in the response with LinkedTxn.TxnType set to ReimburseCharge, ChargeCredit or StatementCharge corresponding to billable customer expenses of type Cash, Delayed Credit, and Delayed Charge, respectively. Links to these types of transactions are established within the QuickBooks UI, only, and are available as read-only at the API level.
  • Links to payments applied to an Invoice object are returned in the response with LinkedTxn.TxnType set to Payment. Links to Payment transactions are established within the QuickBooks UI, only, and are available as read-only at the API level.

Use LinkedTxn.TxnId as the ID in a separate read request for the specific resource to retrieve details of the linked object.
Line [0..n]:
required
Line
Individual line items of a transaction. Valid Line types include:
Sales item line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Group item line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
DetailType:
required
LineDetailTypeEnum
Set to GroupLineDetailfor this type of line.
GroupLineDetail:
required
GroupLineDetail
GroupItemRef:
optional
ReferenceType
Reference to a group item for all the lines that belong to the bundle. Query the Item name list resource to determine the appropriate Item group object (Item.Type=Group) for this reference. Use Item.Id and Item.Name from that object for GroupItemRef.value and GroupItemRef.name, respectively.
Quantity:
optional
Decimal, default is 1
Quantity of the group item.
Line [0..n]:
optional
Line
Individual ItemLine elements that comprise a bundle. Returned in responses.
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Description only (also used for inline Subtotal lines):
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars A string representing one of the following:
  • Free form text description of the line item that appears in the printed record.
  • A subtotal line inline with other lines on the sales form and holds the sum of amounts on all lines above it. This is distinct from the overall transaction subtotal represented with a SubTotal detail line.
    • In create requests, set to Subtotal: (case sensitive) to create the subtotal line; the amount is generated by QuickBooks Online business logic.
    • In read requests, lines with Subtotal: nn.nn returned in this field denote subtotal lines in the object.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to DescriptionOnlyfor this type of line.
DescriptionLineDetail:
optional
DescriptionLineDetail
ServiceDate:
optional
Date
Date when the service is performed.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.

Discount line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation. Not supported for BillPayment, Estimate, Invoice, or Payment objects.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to DiscountLineDetailfor this type of line.
DiscountLineDetail:
optional
DiscountLineDetail
Discount detail type for the entire transaction. This is in contrast to a discount applied to a specific line. The company preference Sales Form Entry | Discounts must be enabled for this type of line to be available.
PercentBased:
optional
Boolean
True if the discount is a percentage; null or false if discount based on amount.
DiscountPercent:
optional
Decimal
Percentage by which the amount due is reduced, from 0% to 100%. To enter a discount of 8.5% use 8.5, not 0.085.
DiscountAccountRef:
optional
ReferenceType
Income account used to track discounts. Query the Account name list resource to determine the appropriate Account object for this reference, where Account.AccountType=Income and Account.AccountSubType=DiscountsRefundsGiven. Use Account.Id and Account.Name from that object for DiscountAccountRef.value and DiscountAccountRef.name, respectively.
ClassRef:
optional
ReferenceType
Reference to the Class associated with this discount. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
TaxCodeRef:
optional
ReferenceType
The TaxCodeassociated with the sales tax for the expense. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.

Subtotal Line (used for the overall transaction)
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to SubtotalLineDetailfor this type of line.
SubtotalLineDetail:
optional
Subtotal LineDetail
ItemRef:
optional
ReferenceType
Reference to the Item. Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively. When a line lacks an ItemRef it is treated as documentation and the Line.Amount attribute is ignored.
For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
TxnTaxDetail:
optional
TxnTaxDetail
This data type provides information for taxes charged on the transaction as a whole. It captures the details sales taxes calculated for the transaction based on the tax codes referenced by the transaction. This can be calculated by QuickBooks business logic or you may supply it when adding a transaction. See Global tax model for more information about this element.
CustomerRef:
required
ReferenceType, filterable
Reference to a customer or job. Query the Customer name list resource to determine the appropriate Customer object for this reference. Use Customer.Id and Customer.DisplayName from that object for CustomerRef.value and CustomerRef.name, respectively.
CustomerMemo:
optional
MemoRef
User-entered message to the customer; this message is visible to end user on their transactions.
BillAddr:
optional
PhysicalAddress
Bill-to address of the Invoice. If BillAddris not specified, and a default Customer:BillingAddr is specified in QuickBooks for this customer, the default bill-to address is used by QuickBooks.
ShipAddr:
optional
PhysicalAddress
Identifies the address where the goods must be shipped. If ShipAddris not specified, and a default Customer:ShippingAddr is specified in QuickBooks for this customer, the default ship-to address will be used by QuickBooks.
ClassRef:
optional
ReferenceType
Reference to the Class associated with the transaction. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerTxn is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
SalesTermRef:
optional
ReferenceType, filterable
Reference to the sales term associated with the transaction. Query the Term name list resource to determine the appropriate Term object for this reference. Use Term.Id and Term.Name from that object for SalesTermRef.value and SalesTermRef.name, respectively.
DueDate:
optional
Date, filterable, sortable
Date when the payment of the transaction is due. If date is not provided, the number of days specified in SalesTermRef added the transaction date will be used.
GlobalTaxCalculation:
optional
GlobalTaxCalculationEnum, default is TaxExcluded
Method in which tax is applied. Allowed values are: TaxExcluded, TaxInclusive, and NotApplicable.
ShipMethodRef:
optional
ReferenceType
Reference to the ShipMethod associated with the transaction. There is no shipping method list. Reference resolves to a string.
ShipDate:
optional
Date, default is null
Date for delivery of goods or services.
TrackingNum:
optional
String
Shipping provider's tracking number for the delivery of the goods associated with the transaction.
TotalAmt:
optional
BigDecimal
Indicates the total amount of the transaction. This includes the total of all the charges, allowances, and taxes. Calculated by QuickBooks business logic; any value you supply is over-written by QuickBooks.
CurrencyRef:
required if multicurrency is enabled for the company
CurrencyRefType
Reference to the currency in which all amounts on the associated transaction are expressed. This must be defined if multicurrency is enabled for the company.
Multicurrency is enabled for the company if Preferences.MultiCurrencyEnabled is set to true. Read more about multicurrency support here.
ExchangeRate:
optional
Decimal, default is 1, applicable if multicurrency is enabled for the company
The number of home currency units it takes to equal one unit of currency specified by CurrencyRef.
HomeTotalAmt:
optional
Decimal, read-only, applicable if multicurrency is enabled for the company
Total amount of the transaction in the home currency. Includes the total of all the charges, allowances and taxes. Calculated by QuickBooks business logic.
Value is valid only when CurrencyRef is specified.
HomeBalance:
optional
minor version 3
Decimal, read-only, applicable if multicurrency is enabled for the company
Convenience field containing the amount in Balance expressed in terms of the home currency. Calculated by QuickBooks business logic.
Value is valid only when CurrencyRef is specified and available when endpoint is evoked with the minorversion=3 query parameter.
ApplyTaxAfterDiscount:
optional
Boolean, default is false
If false or null, calculate the sales tax first, and then apply the discount. If true, subtract the discount first and then calculate the sales tax.
PrintStatus:
optional
String, default is NotSet
; Printing status of the invoice.
Valid values: NotSet, NeedToPrint, PrintComplete .
EmailStatus:
optional
String, default is NotSet
Email status of the invoice.
Valid values: NotSet, NeedToSend, EmailSent
BillEmail:
optional
EmailAddress
Identifies the e-mail address where the invoice is sent. If EmailStatus=NeedToSend, BillEmailis a required input.
BillEmailCc:
optional
minor version 8
EmailAddress
Identifies the carbon copy e-mail address where the invoice is sent. If not specified, this field is populated from that defined in Preferences.SalesFormsPrefs.SalesEmailCc. If this email address is invalid, carbon copy email is not sent.
BillEmailBcc:
optional
minor version 8
EmailAddress
Identifies the blind carbon copy e-mail address where the invoice is sent. If not specified, this field is populated from that defined in Preferences.SalesFormsPrefs.SalesEmailBcc. If this email address is invalid, blind carbon copy email is not sent.
DeliveryInfo:
optional
DeliveryInfo, read-only
Email delivery information. Returned when a request has been made to deliver email with the send operation.
Balance:
optional
Decimal, filterable, sortable, read-only
The balance reflecting any payments made against the transaction. Initially set to the value of TotalAmt. A Balance of 0 indicates the invoice is fully paid. Calculated by QuickBooks business logic; any value you supply is over-written by QuickBooks.
TxnSource:
optional
String
Used internally to specify originating source of a credit card transaction.
Deposit:
optional
Decimal
The deposit made towards this invoice.
TransactionLocationType:
optional
minor version 4
String, default is WithinFrance
The account location. Valid values include:
  • WithinFrance
  • FranceOverseas
  • OutsideFranceWithEU
  • OutsideEU

For France locales, only.
Returns
SAMPLE RESPONSE
{ "Invoice": { "domain": "QBO", "status": "Deleted", "Id": "33" }, "time": "2013-03-15T00:18:15.322-07:00" }

SAMPLE RESPONSE
<IntuitResponse xmlns="http://schema.intuit.com/finance/v3" time="2013-04-23T08:30:33.626-07:00"> <Invoice domain="QBO" status="Deleted"> <Id>41</Id> </Invoice> </IntuitResponse>

Returns the delete response.

Full update an invoice

REQUEST URL
Sandbox Base URL: https://sandbox-quickbooks.api.intuit.com
Production Base URL: https://quickbooks.api.intuit.com

Operation: POST /v3/company/<realmID>/invoice
Content type: application/json

Use this operation to update any of the writable fields of an existing invoice object. The request body must include all writable fields of the existing object as returned in a read response. Writable fields omitted from the request body are set to NULL. The ID of the object to update is specified in the request body.

Request body

SAMPLE REQUEST
{ "Deposit": 0, "domain": "QBO", "sparse": false, "Id": "239", "SyncToken": "0", "MetaData": { "CreateTime": "2015-07-24T10:35:08-07:00", "LastUpdatedTime": "2015-07-24T10:35:08-07:00" }, "CustomField": [{ "DefinitionId": "1", "Name": "Crew #", "Type": "StringType" }], "DocNumber": "1070", "TxnDate": "2015-07-24", "LinkedTxn": [], "Line": [{ "Id": "1", "LineNum": 1, "Amount": 150.0, "DetailType": "SalesItemLineDetail", "SalesItemLineDetail": { "ItemRef": { "value": "1", "name": "Services" }, "TaxCodeRef": { "value": "NON" } } }, { "Amount": 150.0, "DetailType": "SubTotalLineDetail", "SubTotalLineDetail": {} }], "TxnTaxDetail": { "TotalTax": 0 }, "CustomerRef": { "value": "1", "name": "Amy's Bird Sanctuary" }, "CustomerMemo": { "value": "Added customer memo." }, "BillAddr": { "Id": "2", "Line1": "4581 Finch St.", "City": "Bayshore", "CountrySubDivisionCode": "CA", "PostalCode": "94326", "Lat": "INVALID", "Long": "INVALID" }, "ShipAddr": { "Id": "109", "Line1": "4581 Finch St.", "City": "Bayshore", "CountrySubDivisionCode": "CA", "PostalCode": "94326", "Lat": "INVALID", "Long": "INVALID" }, "DueDate": "2015-08-23", "TotalAmt": 150.0, "ApplyTaxAfterDiscount": false, "PrintStatus": "NeedToPrint", "EmailStatus": "NotSet", "Balance": 150.0 }

SAMPLE REQUEST
<Invoice xmlns="http://schema.intuit.com/finance/v3" domain="QBO" sparse="false"> <Id>147</Id> <SyncToken>0</SyncToken> <MetaData> <CreateTime>2014-10-15T14:13:24-07:00</CreateTime> <LastUpdatedTime>2014-10-15T14:13:24-07:00</LastUpdatedTime> </MetaData> <PrivateNote>Invoice update</PrivateNote> <CustomField> <DefinitionId>1</DefinitionId> <Name>Crew #</Name> <Type>StringType</Type> </CustomField> <DocNumber>1040</DocNumber> <TxnDate>2014-10-15</TxnDate> <Line> <Id>1</Id> <LineNum>1</LineNum> <Amount>15.00</Amount> <DetailType>SalesItemLineDetail</DetailType> <SalesItemLineDetail> <ItemRef name="Concrete">3</ItemRef> <TaxCodeRef>NON</TaxCodeRef> </SalesItemLineDetail> </Line> <Line> <Amount>15.00</Amount> <DetailType>SubTotalLineDetail</DetailType> <SubTotalLineDetail /> </Line> <TxnTaxDetail> <TotalTax>0</TotalTax> </TxnTaxDetail> <CustomerRef name="Weiskopf Consulting">29</CustomerRef> <BillAddr> <Id>98</Id> <Line1>645</Line1> <Line2>Park Avenue</Line2> <City>San Jose</City> </BillAddr> <ShipAddr> <Id>99</Id> <Line1>2314</Line1> <Line2>Gladstone Street</Line2> <City>San Francisco</City> </ShipAddr> <DueDate>2014-11-14</DueDate> <TotalAmt>15.00</TotalAmt> <ApplyTaxAfterDiscount>false</ApplyTaxAfterDiscount> <PrintStatus>NeedToPrint</PrintStatus> <EmailStatus>NotSet</EmailStatus> <Balance>15.00</Balance> <Deposit>0</Deposit> </Invoice>

Line [0..n]:
required
Invoice line object
The minimum line item required for the request is one of the following.
Sales item line type:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Group item line type:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
DetailType:
required
LineDetailTypeEnum
Set to GroupLineDetailfor this type of line.
GroupLineDetail:
required
GroupLineDetail
GroupItemRef:
optional
ReferenceType
Reference to a group item for all the lines that belong to the bundle. Query the Item name list resource to determine the appropriate Item group object (Item.Type=Group) for this reference. Use Item.Id and Item.Name from that object for GroupItemRef.value and GroupItemRef.name, respectively.
Quantity:
optional
Decimal, default is 1
Quantity of the group item.
Line [0..n]:
optional
Line
Individual ItemLine elements that comprise a bundle. Returned in responses.
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Inline subtotal using Description line type:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars A string representing one of the following:
  • Free form text description of the line item that appears in the printed record.
  • A subtotal line inline with other lines on the sales form and holds the sum of amounts on all lines above it. This is distinct from the overall transaction subtotal represented with a SubTotal detail line.
    • In create requests, set to Subtotal: (case sensitive) to create the subtotal line; the amount is generated by QuickBooks Online business logic.
    • In read requests, lines with Subtotal: nn.nn returned in this field denote subtotal lines in the object.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to DescriptionOnlyfor this type of line.
DescriptionLineDetail:
optional
DescriptionLineDetail
ServiceDate:
optional
Date
Date when the service is performed.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
CustomerRef:
required
ReferenceType, filterable
Reference to a customer or job. Query the Customer name list resource to determine the appropriate Customer object for this reference. Use Customer.Id and Customer.DisplayName from that object for CustomerRef.value and CustomerRef.name, respectively.
CurrencyRef:
required if multicurrency is enabled for the company
CurrencyRefType
Reference to the currency in which all amounts on the associated transaction are expressed. This must be defined if multicurrency is enabled for the company.
Multicurrency is enabled for the company if Preferences.MultiCurrencyEnabled is set to true. Read more about multicurrency support here.

Returns

The invoice response body.

SAMPLE RESPONSE
{ "Invoice": { "Deposit": 0, "domain": "QBO", "sparse": false, "Id": "239", "SyncToken": "1", "MetaData": { "CreateTime": "2015-07-24T10:35:08-07:00", "LastUpdatedTime": "2015-07-24T10:53:39-07:00" }, "CustomField": [{ "DefinitionId": "1", "Name": "Crew #", "Type": "StringType" }], "DocNumber": "1070", "TxnDate": "2015-07-24", "LinkedTxn": [], "Line": [{ "Id": "1", "LineNum": 1, "Amount": 150.0, "DetailType": "SalesItemLineDetail", "SalesItemLineDetail": { "ItemRef": { "value": "1", "name": "Services" }, "TaxCodeRef": { "value": "NON" } } }, { "Amount": 150.0, "DetailType": "SubTotalLineDetail", "SubTotalLineDetail": {} }], "TxnTaxDetail": { "TotalTax": 0 }, "CustomerRef": { "value": "1", "name": "Amy's Bird Sanctuary" }, "CustomerMemo": { "value": "Added customer memo." }, "BillAddr": { "Id": "117", "Line1": "4581 Finch St.", "City": "Bayshore", "CountrySubDivisionCode": "CA", "PostalCode": "94326" }, "ShipAddr": { "Id": "118", "Line1": "4581 Finch St.", "City": "Bayshore", "CountrySubDivisionCode": "CA", "PostalCode": "94326" }, "DueDate": "2015-08-23", "TotalAmt": 150.0, "ApplyTaxAfterDiscount": false, "PrintStatus": "NeedToPrint", "EmailStatus": "NotSet", "Balance": 150.0 }, "time": "2015-07-24T10:53:39.287-07:00" }

SAMPLE RESPONSE
<IntuitResponse xmlns="http://schema.intuit.com/finance/v3" time="2014-10-15T15:32:38.807-07:00"> <Invoice domain="QBO" sparse="false"> <Id>147</Id> <SyncToken>1</SyncToken> <MetaData> <CreateTime>2014-10-15T14:13:24-07:00</CreateTime> <LastUpdatedTime>2014-10-15T15:32:38-07:00</LastUpdatedTime> </MetaData> <CustomField> <DefinitionId>1</DefinitionId> <Name>Crew #</Name> <Type>StringType</Type> </CustomField> <DocNumber>1040</DocNumber> <TxnDate>2014-10-15</TxnDate> <PrivateNote>Invoice update</PrivateNote> <Line> <Id>1</Id> <LineNum>1</LineNum> <Amount>15.00</Amount> <DetailType>SalesItemLineDetail</DetailType> <SalesItemLineDetail> <ItemRef name="Concrete">3</ItemRef> <TaxCodeRef>NON</TaxCodeRef> </SalesItemLineDetail> </Line> <Line> <Amount>15.00</Amount> <DetailType>SubTotalLineDetail</DetailType> <SubTotalLineDetail /> </Line> <TxnTaxDetail> <TotalTax>0</TotalTax> </TxnTaxDetail> <CustomerRef name="Weiskopf Consulting">29</CustomerRef> <BillAddr> <Id>98</Id> <Line1>645</Line1> <Line2>Park Avenue</Line2> <City>San Jose</City> </BillAddr> <ShipAddr> <Id>99</Id> <Line1>2314</Line1> <Line2>Gladstone Street</Line2> <City>San Francisco</City> </ShipAddr> <DueDate>2014-11-14</DueDate> <TotalAmt>15.00</TotalAmt> <ApplyTaxAfterDiscount>false</ApplyTaxAfterDiscount> <PrintStatus>NeedToPrint</PrintStatus> <EmailStatus>NotSet</EmailStatus> <Balance>15.00</Balance> <Deposit>0</Deposit> </Invoice> </IntuitResponse>

Id:
required for update
String, filterable, sortable
Unique identifier for this object.
Sort order is ASC by default.
SyncToken:
required for update
String
Version number of the object. It is used to lock an object for use by one app at a time. As soon as an application modifies an object, its SyncToken is incremented. Attempts to modify an object specifying an older SyncToken fails. Only the latest version of the object is maintained by QuickBooks Online.
MetaData:
optional
ModificationMetaData
Descriptive information about the object. The MetaData values are set by Data Services and are read only for all applications.
CustomField [0..3]:
optional
CustomField
Custom field or data extension.
DocNumber:
optional
String, maximum of 21 chars, filterable, sortable
Reference number for the transaction. If not explicitly provided at create time, this field is populated based on the setting of Preferences:CustomTxnNumber as follows:
  • If Preferences:CustomTxnNumber is true a custom value can be provided. If no value is supplied, the resulting DocNumber is null.
  • If Preferences:CustomTxnNumber is false, resulting DocNumber is system generated by incrementing the last number by 1.
If Preferences:CustomTxnNumber is false and a value is supplied, that value is stored even if it is a duplicate. Recommended best practice: check the setting of Preferences:CustomTxnNumber before setting DocNumber.
Sort order is ASC by default.
TxnDate:
optional
Date, filterable, sortable, default is current server date
The date entered by the user when this transaction occurred.
For posting transactions, this is the posting date that affects the financial statements. If the date is not supplied, the current date on the server is used.
Sort order is ASC by default.
DepartmentRef:
optional
ReferenceType, default is null
A reference to a Department object specifying the location of the transaction. Available if Preferences.AccountingInfoPrefs.TrackDepartments is set to true.
Query the Department name list resource to determine the appropriate department object for this reference. Use Department.Id and Department.Name from that object for DepartmentRef.value and DepartmentRef.name, respectively.
PrivateNote:
optional
String, max of 4000 chars
User entered, organization-private note about the transaction. This note does not appear on the invoice to the customer. This field maps to the Statement Memo field on the Invoice form in the QuickBooks Online UI.
LinkedTxn[0..n]:
optional
LinkedTxn
Zero or more related transactions to this Invoice object. The following linked relationships are supported:
  • Links to Estimate and TimeActivity objects can be established directly to this Invoice object with UI or with the API. Create, Read, Update, and Query operations are avaialble at the API level for these types of links.
  • Links to expenses incurred on behalf of the customer are returned in the response with LinkedTxn.TxnType set to ReimburseCharge, ChargeCredit or StatementCharge corresponding to billable customer expenses of type Cash, Delayed Credit, and Delayed Charge, respectively. Links to these types of transactions are established within the QuickBooks UI, only, and are available as read-only at the API level.
  • Links to payments applied to an Invoice object are returned in the response with LinkedTxn.TxnType set to Payment. Links to Payment transactions are established within the QuickBooks UI, only, and are available as read-only at the API level.

Use LinkedTxn.TxnId as the ID in a separate read request for the specific resource to retrieve details of the linked object.
Line [0..n]:
required
Line
Individual line items of a transaction. Valid Line types include:
Sales item line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Group item line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
DetailType:
required
LineDetailTypeEnum
Set to GroupLineDetailfor this type of line.
GroupLineDetail:
required
GroupLineDetail
GroupItemRef:
optional
ReferenceType
Reference to a group item for all the lines that belong to the bundle. Query the Item name list resource to determine the appropriate Item group object (Item.Type=Group) for this reference. Use Item.Id and Item.Name from that object for GroupItemRef.value and GroupItemRef.name, respectively.
Quantity:
optional
Decimal, default is 1
Quantity of the group item.
Line [0..n]:
optional
Line
Individual ItemLine elements that comprise a bundle. Returned in responses.
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Description only (also used for inline Subtotal lines):
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars A string representing one of the following:
  • Free form text description of the line item that appears in the printed record.
  • A subtotal line inline with other lines on the sales form and holds the sum of amounts on all lines above it. This is distinct from the overall transaction subtotal represented with a SubTotal detail line.
    • In create requests, set to Subtotal: (case sensitive) to create the subtotal line; the amount is generated by QuickBooks Online business logic.
    • In read requests, lines with Subtotal: nn.nn returned in this field denote subtotal lines in the object.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to DescriptionOnlyfor this type of line.
DescriptionLineDetail:
optional
DescriptionLineDetail
ServiceDate:
optional
Date
Date when the service is performed.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.

Discount line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation. Not supported for BillPayment, Estimate, Invoice, or Payment objects.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to DiscountLineDetailfor this type of line.
DiscountLineDetail:
optional
DiscountLineDetail
Discount detail type for the entire transaction. This is in contrast to a discount applied to a specific line. The company preference Sales Form Entry | Discounts must be enabled for this type of line to be available.
PercentBased:
optional
Boolean
True if the discount is a percentage; null or false if discount based on amount.
DiscountPercent:
optional
Decimal
Percentage by which the amount due is reduced, from 0% to 100%. To enter a discount of 8.5% use 8.5, not 0.085.
DiscountAccountRef:
optional
ReferenceType
Income account used to track discounts. Query the Account name list resource to determine the appropriate Account object for this reference, where Account.AccountType=Income and Account.AccountSubType=DiscountsRefundsGiven. Use Account.Id and Account.Name from that object for DiscountAccountRef.value and DiscountAccountRef.name, respectively.
ClassRef:
optional
ReferenceType
Reference to the Class associated with this discount. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
TaxCodeRef:
optional
ReferenceType
The TaxCodeassociated with the sales tax for the expense. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.

Subtotal Line (used for the overall transaction)
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to SubtotalLineDetailfor this type of line.
SubtotalLineDetail:
optional
Subtotal LineDetail
ItemRef:
optional
ReferenceType
Reference to the Item. Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively. When a line lacks an ItemRef it is treated as documentation and the Line.Amount attribute is ignored.
For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
TxnTaxDetail:
optional
TxnTaxDetail
This data type provides information for taxes charged on the transaction as a whole. It captures the details sales taxes calculated for the transaction based on the tax codes referenced by the transaction. This can be calculated by QuickBooks business logic or you may supply it when adding a transaction. See Global tax model for more information about this element.
CustomerRef:
required
ReferenceType, filterable
Reference to a customer or job. Query the Customer name list resource to determine the appropriate Customer object for this reference. Use Customer.Id and Customer.DisplayName from that object for CustomerRef.value and CustomerRef.name, respectively.
CustomerMemo:
optional
MemoRef
User-entered message to the customer; this message is visible to end user on their transactions.
BillAddr:
optional
PhysicalAddress
Bill-to address of the Invoice. If BillAddris not specified, and a default Customer:BillingAddr is specified in QuickBooks for this customer, the default bill-to address is used by QuickBooks.
ShipAddr:
optional
PhysicalAddress
Identifies the address where the goods must be shipped. If ShipAddris not specified, and a default Customer:ShippingAddr is specified in QuickBooks for this customer, the default ship-to address will be used by QuickBooks.
ClassRef:
optional
ReferenceType
Reference to the Class associated with the transaction. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerTxn is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
SalesTermRef:
optional
ReferenceType, filterable
Reference to the sales term associated with the transaction. Query the Term name list resource to determine the appropriate Term object for this reference. Use Term.Id and Term.Name from that object for SalesTermRef.value and SalesTermRef.name, respectively.
DueDate:
optional
Date, filterable, sortable
Date when the payment of the transaction is due. If date is not provided, the number of days specified in SalesTermRef added the transaction date will be used.
GlobalTaxCalculation:
optional
GlobalTaxCalculationEnum, default is TaxExcluded
Method in which tax is applied. Allowed values are: TaxExcluded, TaxInclusive, and NotApplicable.
ShipMethodRef:
optional
ReferenceType
Reference to the ShipMethod associated with the transaction. There is no shipping method list. Reference resolves to a string.
ShipDate:
optional
Date, default is null
Date for delivery of goods or services.
TrackingNum:
optional
String
Shipping provider's tracking number for the delivery of the goods associated with the transaction.
TotalAmt:
optional
BigDecimal
Indicates the total amount of the transaction. This includes the total of all the charges, allowances, and taxes. Calculated by QuickBooks business logic; any value you supply is over-written by QuickBooks.
CurrencyRef:
required if multicurrency is enabled for the company
CurrencyRefType
Reference to the currency in which all amounts on the associated transaction are expressed. This must be defined if multicurrency is enabled for the company.
Multicurrency is enabled for the company if Preferences.MultiCurrencyEnabled is set to true. Read more about multicurrency support here.
ExchangeRate:
optional
Decimal, default is 1, applicable if multicurrency is enabled for the company
The number of home currency units it takes to equal one unit of currency specified by CurrencyRef.
HomeTotalAmt:
optional
Decimal, read-only, applicable if multicurrency is enabled for the company
Total amount of the transaction in the home currency. Includes the total of all the charges, allowances and taxes. Calculated by QuickBooks business logic.
Value is valid only when CurrencyRef is specified.
HomeBalance:
optional
minor version 3
Decimal, read-only, applicable if multicurrency is enabled for the company
Convenience field containing the amount in Balance expressed in terms of the home currency. Calculated by QuickBooks business logic.
Value is valid only when CurrencyRef is specified and available when endpoint is evoked with the minorversion=3 query parameter.
ApplyTaxAfterDiscount:
optional
Boolean, default is false
If false or null, calculate the sales tax first, and then apply the discount. If true, subtract the discount first and then calculate the sales tax.
PrintStatus:
optional
String, default is NotSet
; Printing status of the invoice.
Valid values: NotSet, NeedToPrint, PrintComplete .
EmailStatus:
optional
String, default is NotSet
Email status of the invoice.
Valid values: NotSet, NeedToSend, EmailSent
BillEmail:
optional
EmailAddress
Identifies the e-mail address where the invoice is sent. If EmailStatus=NeedToSend, BillEmailis a required input.
BillEmailCc:
optional
minor version 8
EmailAddress
Identifies the carbon copy e-mail address where the invoice is sent. If not specified, this field is populated from that defined in Preferences.SalesFormsPrefs.SalesEmailCc. If this email address is invalid, carbon copy email is not sent.
BillEmailBcc:
optional
minor version 8
EmailAddress
Identifies the blind carbon copy e-mail address where the invoice is sent. If not specified, this field is populated from that defined in Preferences.SalesFormsPrefs.SalesEmailBcc. If this email address is invalid, blind carbon copy email is not sent.
DeliveryInfo:
optional
DeliveryInfo, read-only
Email delivery information. Returned when a request has been made to deliver email with the send operation.
Balance:
optional
Decimal, filterable, sortable, read-only
The balance reflecting any payments made against the transaction. Initially set to the value of TotalAmt. A Balance of 0 indicates the invoice is fully paid. Calculated by QuickBooks business logic; any value you supply is over-written by QuickBooks.
TxnSource:
optional
String
Used internally to specify originating source of a credit card transaction.
Deposit:
optional
Decimal
The deposit made towards this invoice.
TransactionLocationType:
optional
minor version 4
String, default is WithinFrance
The account location. Valid values include:
  • WithinFrance
  • FranceOverseas
  • OutsideFranceWithEU
  • OutsideEU

For France locales, only.

Sparse update an invoice

REQUEST URL
Sandbox Base URL: https://sandbox-quickbooks.api.intuit.com
Production Base URL: https://quickbooks.api.intuit.com

Operation: POST /v3/company/<realmID>/invoice
Content type: application/json

Sparse updating provides the ability to update a subset of properties for a given object; only elements specified in the request are updated. Missing elements are left untouched. The ID of the object to update is specified in the request body.​

Request body

SAMPLE REQUEST
{ "sparse": true, "Id": "238", "SyncToken": "0", "DueDate": "2015-09-30" }

SAMPLE REQUEST
<Invoice xmlns="http://schema.intuit.com/finance/v3" domain="QBO" sparse="true"> <Id>130</Id> <SyncToken>0</SyncToken> <MetaData> <CreateTime>2014-09-19T13:16:17-07:00</CreateTime> <LastUpdatedTime>2014-09-19T13:16:17-07:00</LastUpdatedTime> </MetaData> <TxnDate>2014-09-30</TxnDate> </Invoice>

Id:
required for update
String, filterable, sortable
Unique identifier for this object.
Sort order is ASC by default.
SyncToken:
required for update
String
Version number of the object. It is used to lock an object for use by one app at a time. As soon as an application modifies an object, its SyncToken is incremented. Attempts to modify an object specifying an older SyncToken fails. Only the latest version of the object is maintained by QuickBooks Online.
MetaData:
optional
ModificationMetaData
Descriptive information about the object. The MetaData values are set by Data Services and are read only for all applications.
CustomField [0..3]:
optional
CustomField
Custom field or data extension.
DocNumber:
optional
String, maximum of 21 chars, filterable, sortable
Reference number for the transaction. If not explicitly provided at create time, this field is populated based on the setting of Preferences:CustomTxnNumber as follows:
  • If Preferences:CustomTxnNumber is true a custom value can be provided. If no value is supplied, the resulting DocNumber is null.
  • If Preferences:CustomTxnNumber is false, resulting DocNumber is system generated by incrementing the last number by 1.
If Preferences:CustomTxnNumber is false and a value is supplied, that value is stored even if it is a duplicate. Recommended best practice: check the setting of Preferences:CustomTxnNumber before setting DocNumber.
Sort order is ASC by default.
TxnDate:
optional
Date, filterable, sortable, default is current server date
The date entered by the user when this transaction occurred.
For posting transactions, this is the posting date that affects the financial statements. If the date is not supplied, the current date on the server is used.
Sort order is ASC by default.
DepartmentRef:
optional
ReferenceType, default is null
A reference to a Department object specifying the location of the transaction. Available if Preferences.AccountingInfoPrefs.TrackDepartments is set to true.
Query the Department name list resource to determine the appropriate department object for this reference. Use Department.Id and Department.Name from that object for DepartmentRef.value and DepartmentRef.name, respectively.
PrivateNote:
optional
String, max of 4000 chars
User entered, organization-private note about the transaction. This note does not appear on the invoice to the customer. This field maps to the Statement Memo field on the Invoice form in the QuickBooks Online UI.
LinkedTxn[0..n]:
optional
LinkedTxn
Zero or more related transactions to this Invoice object. The following linked relationships are supported:
  • Links to Estimate and TimeActivity objects can be established directly to this Invoice object with UI or with the API. Create, Read, Update, and Query operations are avaialble at the API level for these types of links.
  • Links to expenses incurred on behalf of the customer are returned in the response with LinkedTxn.TxnType set to ReimburseCharge, ChargeCredit or StatementCharge corresponding to billable customer expenses of type Cash, Delayed Credit, and Delayed Charge, respectively. Links to these types of transactions are established within the QuickBooks UI, only, and are available as read-only at the API level.
  • Links to payments applied to an Invoice object are returned in the response with LinkedTxn.TxnType set to Payment. Links to Payment transactions are established within the QuickBooks UI, only, and are available as read-only at the API level.

Use LinkedTxn.TxnId as the ID in a separate read request for the specific resource to retrieve details of the linked object.
Line [0..n]:
required
Line
Individual line items of a transaction. Valid Line types include:
Sales item line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Group item line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
DetailType:
required
LineDetailTypeEnum
Set to GroupLineDetailfor this type of line.
GroupLineDetail:
required
GroupLineDetail
GroupItemRef:
optional
ReferenceType
Reference to a group item for all the lines that belong to the bundle. Query the Item name list resource to determine the appropriate Item group object (Item.Type=Group) for this reference. Use Item.Id and Item.Name from that object for GroupItemRef.value and GroupItemRef.name, respectively.
Quantity:
optional
Decimal, default is 1
Quantity of the group item.
Line [0..n]:
optional
Line
Individual ItemLine elements that comprise a bundle. Returned in responses.
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Description only (also used for inline Subtotal lines):
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars A string representing one of the following:
  • Free form text description of the line item that appears in the printed record.
  • A subtotal line inline with other lines on the sales form and holds the sum of amounts on all lines above it. This is distinct from the overall transaction subtotal represented with a SubTotal detail line.
    • In create requests, set to Subtotal: (case sensitive) to create the subtotal line; the amount is generated by QuickBooks Online business logic.
    • In read requests, lines with Subtotal: nn.nn returned in this field denote subtotal lines in the object.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to DescriptionOnlyfor this type of line.
DescriptionLineDetail:
optional
DescriptionLineDetail
ServiceDate:
optional
Date
Date when the service is performed.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.

Discount line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation. Not supported for BillPayment, Estimate, Invoice, or Payment objects.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to DiscountLineDetailfor this type of line.
DiscountLineDetail:
optional
DiscountLineDetail
Discount detail type for the entire transaction. This is in contrast to a discount applied to a specific line. The company preference Sales Form Entry | Discounts must be enabled for this type of line to be available.
PercentBased:
optional
Boolean
True if the discount is a percentage; null or false if discount based on amount.
DiscountPercent:
optional
Decimal
Percentage by which the amount due is reduced, from 0% to 100%. To enter a discount of 8.5% use 8.5, not 0.085.
DiscountAccountRef:
optional
ReferenceType
Income account used to track discounts. Query the Account name list resource to determine the appropriate Account object for this reference, where Account.AccountType=Income and Account.AccountSubType=DiscountsRefundsGiven. Use Account.Id and Account.Name from that object for DiscountAccountRef.value and DiscountAccountRef.name, respectively.
ClassRef:
optional
ReferenceType
Reference to the Class associated with this discount. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
TaxCodeRef:
optional
ReferenceType
The TaxCodeassociated with the sales tax for the expense. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.

Subtotal Line (used for the overall transaction)
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to SubtotalLineDetailfor this type of line.
SubtotalLineDetail:
optional
Subtotal LineDetail
ItemRef:
optional
ReferenceType
Reference to the Item. Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively. When a line lacks an ItemRef it is treated as documentation and the Line.Amount attribute is ignored.
For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
TxnTaxDetail:
optional
TxnTaxDetail
This data type provides information for taxes charged on the transaction as a whole. It captures the details sales taxes calculated for the transaction based on the tax codes referenced by the transaction. This can be calculated by QuickBooks business logic or you may supply it when adding a transaction. See Global tax model for more information about this element.
CustomerRef:
required
ReferenceType, filterable
Reference to a customer or job. Query the Customer name list resource to determine the appropriate Customer object for this reference. Use Customer.Id and Customer.DisplayName from that object for CustomerRef.value and CustomerRef.name, respectively.
CustomerMemo:
optional
MemoRef
User-entered message to the customer; this message is visible to end user on their transactions.
BillAddr:
optional
PhysicalAddress
Bill-to address of the Invoice. If BillAddris not specified, and a default Customer:BillingAddr is specified in QuickBooks for this customer, the default bill-to address is used by QuickBooks.
ShipAddr:
optional
PhysicalAddress
Identifies the address where the goods must be shipped. If ShipAddris not specified, and a default Customer:ShippingAddr is specified in QuickBooks for this customer, the default ship-to address will be used by QuickBooks.
ClassRef:
optional
ReferenceType
Reference to the Class associated with the transaction. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerTxn is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
SalesTermRef:
optional
ReferenceType, filterable
Reference to the sales term associated with the transaction. Query the Term name list resource to determine the appropriate Term object for this reference. Use Term.Id and Term.Name from that object for SalesTermRef.value and SalesTermRef.name, respectively.
DueDate:
optional
Date, filterable, sortable
Date when the payment of the transaction is due. If date is not provided, the number of days specified in SalesTermRef added the transaction date will be used.
GlobalTaxCalculation:
optional
GlobalTaxCalculationEnum, default is TaxExcluded
Method in which tax is applied. Allowed values are: TaxExcluded, TaxInclusive, and NotApplicable.
ShipMethodRef:
optional
ReferenceType
Reference to the ShipMethod associated with the transaction. There is no shipping method list. Reference resolves to a string.
ShipDate:
optional
Date, default is null
Date for delivery of goods or services.
TrackingNum:
optional
String
Shipping provider's tracking number for the delivery of the goods associated with the transaction.
TotalAmt:
optional
BigDecimal
Indicates the total amount of the transaction. This includes the total of all the charges, allowances, and taxes. Calculated by QuickBooks business logic; any value you supply is over-written by QuickBooks.
CurrencyRef:
required if multicurrency is enabled for the company
CurrencyRefType
Reference to the currency in which all amounts on the associated transaction are expressed. This must be defined if multicurrency is enabled for the company.
Multicurrency is enabled for the company if Preferences.MultiCurrencyEnabled is set to true. Read more about multicurrency support here.
ExchangeRate:
optional
Decimal, default is 1, applicable if multicurrency is enabled for the company
The number of home currency units it takes to equal one unit of currency specified by CurrencyRef.
HomeTotalAmt:
optional
Decimal, read-only, applicable if multicurrency is enabled for the company
Total amount of the transaction in the home currency. Includes the total of all the charges, allowances and taxes. Calculated by QuickBooks business logic.
Value is valid only when CurrencyRef is specified.
HomeBalance:
optional
minor version 3
Decimal, read-only, applicable if multicurrency is enabled for the company
Convenience field containing the amount in Balance expressed in terms of the home currency. Calculated by QuickBooks business logic.
Value is valid only when CurrencyRef is specified and available when endpoint is evoked with the minorversion=3 query parameter.
ApplyTaxAfterDiscount:
optional
Boolean, default is false
If false or null, calculate the sales tax first, and then apply the discount. If true, subtract the discount first and then calculate the sales tax.
PrintStatus:
optional
String, default is NotSet
; Printing status of the invoice.
Valid values: NotSet, NeedToPrint, PrintComplete .
EmailStatus:
optional
String, default is NotSet
Email status of the invoice.
Valid values: NotSet, NeedToSend, EmailSent
BillEmail:
optional
EmailAddress
Identifies the e-mail address where the invoice is sent. If EmailStatus=NeedToSend, BillEmailis a required input.
BillEmailCc:
optional
minor version 8
EmailAddress
Identifies the carbon copy e-mail address where the invoice is sent. If not specified, this field is populated from that defined in Preferences.SalesFormsPrefs.SalesEmailCc. If this email address is invalid, carbon copy email is not sent.
BillEmailBcc:
optional
minor version 8
EmailAddress
Identifies the blind carbon copy e-mail address where the invoice is sent. If not specified, this field is populated from that defined in Preferences.SalesFormsPrefs.SalesEmailBcc. If this email address is invalid, blind carbon copy email is not sent.
DeliveryInfo:
optional
DeliveryInfo, read-only
Email delivery information. Returned when a request has been made to deliver email with the send operation.
Balance:
optional
Decimal, filterable, sortable, read-only
The balance reflecting any payments made against the transaction. Initially set to the value of TotalAmt. A Balance of 0 indicates the invoice is fully paid. Calculated by QuickBooks business logic; any value you supply is over-written by QuickBooks.
TxnSource:
optional
String
Used internally to specify originating source of a credit card transaction.
Deposit:
optional
Decimal
The deposit made towards this invoice.
TransactionLocationType:
optional
minor version 4
String, default is WithinFrance
The account location. Valid values include:
  • WithinFrance
  • FranceOverseas
  • OutsideFranceWithEU
  • OutsideEU

For France locales, only.
Returns
SAMPLE RESPONSE
{ "Invoice": { "Deposit": 0, "domain": "QBO", "sparse": false, "Id": "238", "SyncToken": "1", "MetaData": { "CreateTime": "2015-07-24T10:33:39-07:00", "LastUpdatedTime": "2015-07-24T11:03:26-07:00" }, "CustomField": [{ "DefinitionId": "1", "Name": "Crew #", "Type": "StringType" }], "DocNumber": "1069", "TxnDate": "2015-07-24", "LinkedTxn": [], "Line": [{ "Id": "1", "LineNum": 1, "Amount": 100.0, "DetailType": "SalesItemLineDetail", "SalesItemLineDetail": { "ItemRef": { "value": "1", "name": "Services" }, "TaxCodeRef": { "value": "NON" } } }, { "Amount": 100.0, "DetailType": "SubTotalLineDetail", "SubTotalLineDetail": {} }], "TxnTaxDetail": { "TotalTax": 0 }, "CustomerRef": { "value": "1", "name": "Amy's Bird Sanctuary" }, "BillAddr": { "Id": "2", "Line1": "4581 Finch St.", "City": "Bayshore", "CountrySubDivisionCode": "CA", "PostalCode": "94326", "Lat": "INVALID", "Long": "INVALID" }, "ShipAddr": { "Id": "109", "Line1": "4581 Finch St.", "City": "Bayshore", "CountrySubDivisionCode": "CA", "PostalCode": "94326", "Lat": "INVALID", "Long": "INVALID" }, "DueDate": "2015-09-30", "TotalAmt": 100.0, "ApplyTaxAfterDiscount": false, "PrintStatus": "NeedToPrint", "EmailStatus": "NotSet", "Balance": 100.0 }, "time": "2015-07-24T11:03:26.674-07:00" }

SAMPLE RESPONSE
<IntuitResponse xmlns="http://schema.intuit.com/finance/v3" time="2015-07-24T11:06:15.952-07:00"> <Invoice domain="QBO" sparse="false"> <Id>130</Id> <SyncToken>1</SyncToken> <MetaData> <CreateTime>2014-09-19T13:16:17-07:00</CreateTime> <LastUpdatedTime>2015-07-24T11:06:16-07:00</LastUpdatedTime> </MetaData> <CustomField> <DefinitionId>1</DefinitionId> <Name>Crew #</Name> <Type>StringType</Type> <StringValue>102</StringValue> </CustomField> <DocNumber>1037</DocNumber> <TxnDate>2014-09-30</TxnDate> <LinkedTxn> <TxnId>100</TxnId> <TxnType>Estimate</TxnType> </LinkedTxn> <Line> <Id>1</Id> <LineNum>1</LineNum> <Description>Rock Fountain</Description> <Amount>275.00</Amount> <DetailType>SalesItemLineDetail</DetailType> <SalesItemLineDetail> <ItemRef name="Rock Fountain">5</ItemRef> <UnitPrice>275</UnitPrice> <Qty>1</Qty> <TaxCodeRef>TAX</TaxCodeRef> </SalesItemLineDetail> </Line> <Line> <Id>2</Id> <LineNum>2</LineNum> <Description>Fountain Pump</Description> <Amount>12.75</Amount> <DetailType>SalesItemLineDetail</DetailType> <SalesItemLineDetail> <ItemRef name="Pump">11</ItemRef> <UnitPrice>12.75</UnitPrice> <Qty>1</Qty> <TaxCodeRef>TAX</TaxCodeRef> </SalesItemLineDetail> </Line> <Line> <Id>3</Id> <LineNum>3</LineNum> <Description>Concrete for fountain installation</Description> <Amount>47.50</Amount> <DetailType>SalesItemLineDetail</DetailType> <SalesItemLineDetail> <ItemRef name="Concrete">3</ItemRef> <UnitPrice>9.5</UnitPrice> <Qty>5</Qty> <TaxCodeRef>TAX</TaxCodeRef> </SalesItemLineDetail> </Line> <Line> <Amount>335.25</Amount> <DetailType>SubTotalLineDetail</DetailType> <SubTotalLineDetail /> </Line> <TxnTaxDetail> <TxnTaxCodeRef>2</TxnTaxCodeRef> <TotalTax>26.82</TotalTax> <TaxLine> <Amount>26.82</Amount> <DetailType>TaxLineDetail</DetailType> <TaxLineDetail> <TaxRateRef>3</TaxRateRef> <PercentBased>true</PercentBased> <TaxPercent>8</TaxPercent> <NetAmountTaxable>335.25</NetAmountTaxable> </TaxLineDetail> </TaxLine> </TxnTaxDetail> <CustomerRef name="Sonnenschein Family Store">24</CustomerRef> <CustomerMemo>Thank you for your business and have a great day!</CustomerMemo> <BillAddr> <Id>95</Id> <Line1>Russ Sonnenschein</Line1> <Line2>Sonnenschein Family Store</Line2> <Line3>5647 Cypress Hill Ave.</Line3> <Line4>Middlefield, CA 94303</Line4> <Lat>37.4238562</Lat> <Long>-122.1141681</Long> </BillAddr> <ShipAddr> <Id>25</Id> <Line1>5647 Cypress Hill Ave.</Line1> <City>Middlefield</City> <CountrySubDivisionCode>CA</CountrySubDivisionCode> <PostalCode>94303</PostalCode> <Lat>37.4238562</Lat> <Long>-122.1141681</Long> </ShipAddr> <SalesTermRef>3</SalesTermRef> <DueDate>2014-10-19</DueDate> <TotalAmt>362.07</TotalAmt> <ApplyTaxAfterDiscount>false</ApplyTaxAfterDiscount> <PrintStatus>NeedToPrint</PrintStatus> <EmailStatus>NotSet</EmailStatus> <BillEmail> <Address>Familiystore@intuit.com</Address> </BillEmail> <Balance>362.07</Balance> <Deposit>0</Deposit> </Invoice> </IntuitResponse>

The invoice response body.

Id:
required for update
String, filterable, sortable
Unique identifier for this object.
Sort order is ASC by default.
SyncToken:
required for update
String
Version number of the object. It is used to lock an object for use by one app at a time. As soon as an application modifies an object, its SyncToken is incremented. Attempts to modify an object specifying an older SyncToken fails. Only the latest version of the object is maintained by QuickBooks Online.
MetaData:
optional
ModificationMetaData
Descriptive information about the object. The MetaData values are set by Data Services and are read only for all applications.
CustomField [0..3]:
optional
CustomField
Custom field or data extension.
DocNumber:
optional
String, maximum of 21 chars, filterable, sortable
Reference number for the transaction. If not explicitly provided at create time, this field is populated based on the setting of Preferences:CustomTxnNumber as follows:
  • If Preferences:CustomTxnNumber is true a custom value can be provided. If no value is supplied, the resulting DocNumber is null.
  • If Preferences:CustomTxnNumber is false, resulting DocNumber is system generated by incrementing the last number by 1.
If Preferences:CustomTxnNumber is false and a value is supplied, that value is stored even if it is a duplicate. Recommended best practice: check the setting of Preferences:CustomTxnNumber before setting DocNumber.
Sort order is ASC by default.
TxnDate:
optional
Date, filterable, sortable, default is current server date
The date entered by the user when this transaction occurred.
For posting transactions, this is the posting date that affects the financial statements. If the date is not supplied, the current date on the server is used.
Sort order is ASC by default.
DepartmentRef:
optional
ReferenceType, default is null
A reference to a Department object specifying the location of the transaction. Available if Preferences.AccountingInfoPrefs.TrackDepartments is set to true.
Query the Department name list resource to determine the appropriate department object for this reference. Use Department.Id and Department.Name from that object for DepartmentRef.value and DepartmentRef.name, respectively.
PrivateNote:
optional
String, max of 4000 chars
User entered, organization-private note about the transaction. This note does not appear on the invoice to the customer. This field maps to the Statement Memo field on the Invoice form in the QuickBooks Online UI.
LinkedTxn[0..n]:
optional
LinkedTxn
Zero or more related transactions to this Invoice object. The following linked relationships are supported:
  • Links to Estimate and TimeActivity objects can be established directly to this Invoice object with UI or with the API. Create, Read, Update, and Query operations are avaialble at the API level for these types of links.
  • Links to expenses incurred on behalf of the customer are returned in the response with LinkedTxn.TxnType set to ReimburseCharge, ChargeCredit or StatementCharge corresponding to billable customer expenses of type Cash, Delayed Credit, and Delayed Charge, respectively. Links to these types of transactions are established within the QuickBooks UI, only, and are available as read-only at the API level.
  • Links to payments applied to an Invoice object are returned in the response with LinkedTxn.TxnType set to Payment. Links to Payment transactions are established within the QuickBooks UI, only, and are available as read-only at the API level.

Use LinkedTxn.TxnId as the ID in a separate read request for the specific resource to retrieve details of the linked object.
Line [0..n]:
required
Line
Individual line items of a transaction. Valid Line types include:
Sales item line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Group item line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
DetailType:
required
LineDetailTypeEnum
Set to GroupLineDetailfor this type of line.
GroupLineDetail:
required
GroupLineDetail
GroupItemRef:
optional
ReferenceType
Reference to a group item for all the lines that belong to the bundle. Query the Item name list resource to determine the appropriate Item group object (Item.Type=Group) for this reference. Use Item.Id and Item.Name from that object for GroupItemRef.value and GroupItemRef.name, respectively.
Quantity:
optional
Decimal, default is 1
Quantity of the group item.
Line [0..n]:
optional
Line
Individual ItemLine elements that comprise a bundle. Returned in responses.
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Description only (also used for inline Subtotal lines):
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars A string representing one of the following:
  • Free form text description of the line item that appears in the printed record.
  • A subtotal line inline with other lines on the sales form and holds the sum of amounts on all lines above it. This is distinct from the overall transaction subtotal represented with a SubTotal detail line.
    • In create requests, set to Subtotal: (case sensitive) to create the subtotal line; the amount is generated by QuickBooks Online business logic.
    • In read requests, lines with Subtotal: nn.nn returned in this field denote subtotal lines in the object.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to DescriptionOnlyfor this type of line.
DescriptionLineDetail:
optional
DescriptionLineDetail
ServiceDate:
optional
Date
Date when the service is performed.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.

Discount line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation. Not supported for BillPayment, Estimate, Invoice, or Payment objects.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to DiscountLineDetailfor this type of line.
DiscountLineDetail:
optional
DiscountLineDetail
Discount detail type for the entire transaction. This is in contrast to a discount applied to a specific line. The company preference Sales Form Entry | Discounts must be enabled for this type of line to be available.
PercentBased:
optional
Boolean
True if the discount is a percentage; null or false if discount based on amount.
DiscountPercent:
optional
Decimal
Percentage by which the amount due is reduced, from 0% to 100%. To enter a discount of 8.5% use 8.5, not 0.085.
DiscountAccountRef:
optional
ReferenceType
Income account used to track discounts. Query the Account name list resource to determine the appropriate Account object for this reference, where Account.AccountType=Income and Account.AccountSubType=DiscountsRefundsGiven. Use Account.Id and Account.Name from that object for DiscountAccountRef.value and DiscountAccountRef.name, respectively.
ClassRef:
optional
ReferenceType
Reference to the Class associated with this discount. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
TaxCodeRef:
optional
ReferenceType
The TaxCodeassociated with the sales tax for the expense. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.

Subtotal Line (used for the overall transaction)
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to SubtotalLineDetailfor this type of line.
SubtotalLineDetail:
optional
Subtotal LineDetail
ItemRef:
optional
ReferenceType
Reference to the Item. Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively. When a line lacks an ItemRef it is treated as documentation and the Line.Amount attribute is ignored.
For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
TxnTaxDetail:
optional
TxnTaxDetail
This data type provides information for taxes charged on the transaction as a whole. It captures the details sales taxes calculated for the transaction based on the tax codes referenced by the transaction. This can be calculated by QuickBooks business logic or you may supply it when adding a transaction. See Global tax model for more information about this element.
CustomerRef:
required
ReferenceType, filterable
Reference to a customer or job. Query the Customer name list resource to determine the appropriate Customer object for this reference. Use Customer.Id and Customer.DisplayName from that object for CustomerRef.value and CustomerRef.name, respectively.
CustomerMemo:
optional
MemoRef
User-entered message to the customer; this message is visible to end user on their transactions.
BillAddr:
optional
PhysicalAddress
Bill-to address of the Invoice. If BillAddris not specified, and a default Customer:BillingAddr is specified in QuickBooks for this customer, the default bill-to address is used by QuickBooks.
ShipAddr:
optional
PhysicalAddress
Identifies the address where the goods must be shipped. If ShipAddris not specified, and a default Customer:ShippingAddr is specified in QuickBooks for this customer, the default ship-to address will be used by QuickBooks.
ClassRef:
optional
ReferenceType
Reference to the Class associated with the transaction. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerTxn is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
SalesTermRef:
optional
ReferenceType, filterable
Reference to the sales term associated with the transaction. Query the Term name list resource to determine the appropriate Term object for this reference. Use Term.Id and Term.Name from that object for SalesTermRef.value and SalesTermRef.name, respectively.
DueDate:
optional
Date, filterable, sortable
Date when the payment of the transaction is due. If date is not provided, the number of days specified in SalesTermRef added the transaction date will be used.
GlobalTaxCalculation:
optional
GlobalTaxCalculationEnum, default is TaxExcluded
Method in which tax is applied. Allowed values are: TaxExcluded, TaxInclusive, and NotApplicable.
ShipMethodRef:
optional
ReferenceType
Reference to the ShipMethod associated with the transaction. There is no shipping method list. Reference resolves to a string.
ShipDate:
optional
Date, default is null
Date for delivery of goods or services.
TrackingNum:
optional
String
Shipping provider's tracking number for the delivery of the goods associated with the transaction.
TotalAmt:
optional
BigDecimal
Indicates the total amount of the transaction. This includes the total of all the charges, allowances, and taxes. Calculated by QuickBooks business logic; any value you supply is over-written by QuickBooks.
CurrencyRef:
required if multicurrency is enabled for the company
CurrencyRefType
Reference to the currency in which all amounts on the associated transaction are expressed. This must be defined if multicurrency is enabled for the company.
Multicurrency is enabled for the company if Preferences.MultiCurrencyEnabled is set to true. Read more about multicurrency support here.
ExchangeRate:
optional
Decimal, default is 1, applicable if multicurrency is enabled for the company
The number of home currency units it takes to equal one unit of currency specified by CurrencyRef.
HomeTotalAmt:
optional
Decimal, read-only, applicable if multicurrency is enabled for the company
Total amount of the transaction in the home currency. Includes the total of all the charges, allowances and taxes. Calculated by QuickBooks business logic.
Value is valid only when CurrencyRef is specified.
HomeBalance:
optional
minor version 3
Decimal, read-only, applicable if multicurrency is enabled for the company
Convenience field containing the amount in Balance expressed in terms of the home currency. Calculated by QuickBooks business logic.
Value is valid only when CurrencyRef is specified and available when endpoint is evoked with the minorversion=3 query parameter.
ApplyTaxAfterDiscount:
optional
Boolean, default is false
If false or null, calculate the sales tax first, and then apply the discount. If true, subtract the discount first and then calculate the sales tax.
PrintStatus:
optional
String, default is NotSet
; Printing status of the invoice.
Valid values: NotSet, NeedToPrint, PrintComplete .
EmailStatus:
optional
String, default is NotSet
Email status of the invoice.
Valid values: NotSet, NeedToSend, EmailSent
BillEmail:
optional
EmailAddress
Identifies the e-mail address where the invoice is sent. If EmailStatus=NeedToSend, BillEmailis a required input.
BillEmailCc:
optional
minor version 8
EmailAddress
Identifies the carbon copy e-mail address where the invoice is sent. If not specified, this field is populated from that defined in Preferences.SalesFormsPrefs.SalesEmailCc. If this email address is invalid, carbon copy email is not sent.
BillEmailBcc:
optional
minor version 8
EmailAddress
Identifies the blind carbon copy e-mail address where the invoice is sent. If not specified, this field is populated from that defined in Preferences.SalesFormsPrefs.SalesEmailBcc. If this email address is invalid, blind carbon copy email is not sent.
DeliveryInfo:
optional
DeliveryInfo, read-only
Email delivery information. Returned when a request has been made to deliver email with the send operation.
Balance:
optional
Decimal, filterable, sortable, read-only
The balance reflecting any payments made against the transaction. Initially set to the value of TotalAmt. A Balance of 0 indicates the invoice is fully paid. Calculated by QuickBooks business logic; any value you supply is over-written by QuickBooks.
TxnSource:
optional
String
Used internally to specify originating source of a credit card transaction.
Deposit:
optional
Decimal
The deposit made towards this invoice.
TransactionLocationType:
optional
minor version 4
String, default is WithinFrance
The account location. Valid values include:
  • WithinFrance
  • FranceOverseas
  • OutsideFranceWithEU
  • OutsideEU

For France locales, only.

Void an invoice

REQUEST URL
Sandbox Base URL: https://sandbox-quickbooks.api.intuit.com
Production Base URL: https://quickbooks.api.intuit.com

Operation: POST /v3/company/<realmID>/invoice?operation=void
Content type: application/json

Use this operation to void an existing invoice object; include a minimum of Invoice.Id and the current Invoice.SyncToken. The transaction remains active but all amounts and quantities are zeroed and the string, Voided, is injected into Invoice.PrivateNote, prepended to existing text if present.

Request body
SAMPLE REQUEST
{ "Id": "129", "SyncToken": "0" }

SAMPLE REQUEST
<Invoice xmlns='http://schema.intuit.com/finance/v3' domain="QBO" sparse="false"> <Id>863</Id> <SyncToken>0</SyncToken> </Invoice>

Id:
required for update
String, filterable, sortable
Unique identifier for this object.
Sort order is ASC by default.
SyncToken:
required for update
String
Version number of the object. It is used to lock an object for use by one app at a time. As soon as an application modifies an object, its SyncToken is incremented. Attempts to modify an object specifying an older SyncToken fails. Only the latest version of the object is maintained by QuickBooks Online.
MetaData:
optional
ModificationMetaData
Descriptive information about the object. The MetaData values are set by Data Services and are read only for all applications.
CustomField [0..3]:
optional
CustomField
Custom field or data extension.
DocNumber:
optional
String, maximum of 21 chars, filterable, sortable
Reference number for the transaction. If not explicitly provided at create time, this field is populated based on the setting of Preferences:CustomTxnNumber as follows:
  • If Preferences:CustomTxnNumber is true a custom value can be provided. If no value is supplied, the resulting DocNumber is null.
  • If Preferences:CustomTxnNumber is false, resulting DocNumber is system generated by incrementing the last number by 1.
If Preferences:CustomTxnNumber is false and a value is supplied, that value is stored even if it is a duplicate. Recommended best practice: check the setting of Preferences:CustomTxnNumber before setting DocNumber.
Sort order is ASC by default.
TxnDate:
optional
Date, filterable, sortable, default is current server date
The date entered by the user when this transaction occurred.
For posting transactions, this is the posting date that affects the financial statements. If the date is not supplied, the current date on the server is used.
Sort order is ASC by default.
DepartmentRef:
optional
ReferenceType, default is null
A reference to a Department object specifying the location of the transaction. Available if Preferences.AccountingInfoPrefs.TrackDepartments is set to true.
Query the Department name list resource to determine the appropriate department object for this reference. Use Department.Id and Department.Name from that object for DepartmentRef.value and DepartmentRef.name, respectively.
PrivateNote:
optional
String, max of 4000 chars
User entered, organization-private note about the transaction. This note does not appear on the invoice to the customer. This field maps to the Statement Memo field on the Invoice form in the QuickBooks Online UI.
LinkedTxn[0..n]:
optional
LinkedTxn
Zero or more related transactions to this Invoice object. The following linked relationships are supported:
  • Links to Estimate and TimeActivity objects can be established directly to this Invoice object with UI or with the API. Create, Read, Update, and Query operations are avaialble at the API level for these types of links.
  • Links to expenses incurred on behalf of the customer are returned in the response with LinkedTxn.TxnType set to ReimburseCharge, ChargeCredit or StatementCharge corresponding to billable customer expenses of type Cash, Delayed Credit, and Delayed Charge, respectively. Links to these types of transactions are established within the QuickBooks UI, only, and are available as read-only at the API level.
  • Links to payments applied to an Invoice object are returned in the response with LinkedTxn.TxnType set to Payment. Links to Payment transactions are established within the QuickBooks UI, only, and are available as read-only at the API level.

Use LinkedTxn.TxnId as the ID in a separate read request for the specific resource to retrieve details of the linked object.
Line [0..n]:
required
Line
Individual line items of a transaction. Valid Line types include:
Sales item line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Group item line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
DetailType:
required
LineDetailTypeEnum
Set to GroupLineDetailfor this type of line.
GroupLineDetail:
required
GroupLineDetail
GroupItemRef:
optional
ReferenceType
Reference to a group item for all the lines that belong to the bundle. Query the Item name list resource to determine the appropriate Item group object (Item.Type=Group) for this reference. Use Item.Id and Item.Name from that object for GroupItemRef.value and GroupItemRef.name, respectively.
Quantity:
optional
Decimal, default is 1
Quantity of the group item.
Line [0..n]:
optional
Line
Individual ItemLine elements that comprise a bundle. Returned in responses.
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Description only (also used for inline Subtotal lines):
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars A string representing one of the following:
  • Free form text description of the line item that appears in the printed record.
  • A subtotal line inline with other lines on the sales form and holds the sum of amounts on all lines above it. This is distinct from the overall transaction subtotal represented with a SubTotal detail line.
    • In create requests, set to Subtotal: (case sensitive) to create the subtotal line; the amount is generated by QuickBooks Online business logic.
    • In read requests, lines with Subtotal: nn.nn returned in this field denote subtotal lines in the object.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to DescriptionOnlyfor this type of line.
DescriptionLineDetail:
optional
DescriptionLineDetail
ServiceDate:
optional
Date
Date when the service is performed.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.

Discount line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation. Not supported for BillPayment, Estimate, Invoice, or Payment objects.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to DiscountLineDetailfor this type of line.
DiscountLineDetail:
optional
DiscountLineDetail
Discount detail type for the entire transaction. This is in contrast to a discount applied to a specific line. The company preference Sales Form Entry | Discounts must be enabled for this type of line to be available.
PercentBased:
optional
Boolean
True if the discount is a percentage; null or false if discount based on amount.
DiscountPercent:
optional
Decimal
Percentage by which the amount due is reduced, from 0% to 100%. To enter a discount of 8.5% use 8.5, not 0.085.
DiscountAccountRef:
optional
ReferenceType
Income account used to track discounts. Query the Account name list resource to determine the appropriate Account object for this reference, where Account.AccountType=Income and Account.AccountSubType=DiscountsRefundsGiven. Use Account.Id and Account.Name from that object for DiscountAccountRef.value and DiscountAccountRef.name, respectively.
ClassRef:
optional
ReferenceType
Reference to the Class associated with this discount. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
TaxCodeRef:
optional
ReferenceType
The TaxCodeassociated with the sales tax for the expense. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.

Subtotal Line (used for the overall transaction)
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to SubtotalLineDetailfor this type of line.
SubtotalLineDetail:
optional
Subtotal LineDetail
ItemRef:
optional
ReferenceType
Reference to the Item. Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively. When a line lacks an ItemRef it is treated as documentation and the Line.Amount attribute is ignored.
For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
TxnTaxDetail:
optional
TxnTaxDetail
This data type provides information for taxes charged on the transaction as a whole. It captures the details sales taxes calculated for the transaction based on the tax codes referenced by the transaction. This can be calculated by QuickBooks business logic or you may supply it when adding a transaction. See Global tax model for more information about this element.
CustomerRef:
required
ReferenceType, filterable
Reference to a customer or job. Query the Customer name list resource to determine the appropriate Customer object for this reference. Use Customer.Id and Customer.DisplayName from that object for CustomerRef.value and CustomerRef.name, respectively.
CustomerMemo:
optional
MemoRef
User-entered message to the customer; this message is visible to end user on their transactions.
BillAddr:
optional
PhysicalAddress
Bill-to address of the Invoice. If BillAddris not specified, and a default Customer:BillingAddr is specified in QuickBooks for this customer, the default bill-to address is used by QuickBooks.
ShipAddr:
optional
PhysicalAddress
Identifies the address where the goods must be shipped. If ShipAddris not specified, and a default Customer:ShippingAddr is specified in QuickBooks for this customer, the default ship-to address will be used by QuickBooks.
ClassRef:
optional
ReferenceType
Reference to the Class associated with the transaction. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerTxn is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
SalesTermRef:
optional
ReferenceType, filterable
Reference to the sales term associated with the transaction. Query the Term name list resource to determine the appropriate Term object for this reference. Use Term.Id and Term.Name from that object for SalesTermRef.value and SalesTermRef.name, respectively.
DueDate:
optional
Date, filterable, sortable
Date when the payment of the transaction is due. If date is not provided, the number of days specified in SalesTermRef added the transaction date will be used.
GlobalTaxCalculation:
optional
GlobalTaxCalculationEnum, default is TaxExcluded
Method in which tax is applied. Allowed values are: TaxExcluded, TaxInclusive, and NotApplicable.
ShipMethodRef:
optional
ReferenceType
Reference to the ShipMethod associated with the transaction. There is no shipping method list. Reference resolves to a string.
ShipDate:
optional
Date, default is null
Date for delivery of goods or services.
TrackingNum:
optional
String
Shipping provider's tracking number for the delivery of the goods associated with the transaction.
TotalAmt:
optional
BigDecimal
Indicates the total amount of the transaction. This includes the total of all the charges, allowances, and taxes. Calculated by QuickBooks business logic; any value you supply is over-written by QuickBooks.
CurrencyRef:
required if multicurrency is enabled for the company
CurrencyRefType
Reference to the currency in which all amounts on the associated transaction are expressed. This must be defined if multicurrency is enabled for the company.
Multicurrency is enabled for the company if Preferences.MultiCurrencyEnabled is set to true. Read more about multicurrency support here.
ExchangeRate:
optional
Decimal, default is 1, applicable if multicurrency is enabled for the company
The number of home currency units it takes to equal one unit of currency specified by CurrencyRef.
HomeTotalAmt:
optional
Decimal, read-only, applicable if multicurrency is enabled for the company
Total amount of the transaction in the home currency. Includes the total of all the charges, allowances and taxes. Calculated by QuickBooks business logic.
Value is valid only when CurrencyRef is specified.
HomeBalance:
optional
minor version 3
Decimal, read-only, applicable if multicurrency is enabled for the company
Convenience field containing the amount in Balance expressed in terms of the home currency. Calculated by QuickBooks business logic.
Value is valid only when CurrencyRef is specified and available when endpoint is evoked with the minorversion=3 query parameter.
ApplyTaxAfterDiscount:
optional
Boolean, default is false
If false or null, calculate the sales tax first, and then apply the discount. If true, subtract the discount first and then calculate the sales tax.
PrintStatus:
optional
String, default is NotSet
; Printing status of the invoice.
Valid values: NotSet, NeedToPrint, PrintComplete .
EmailStatus:
optional
String, default is NotSet
Email status of the invoice.
Valid values: NotSet, NeedToSend, EmailSent
BillEmail:
optional
EmailAddress
Identifies the e-mail address where the invoice is sent. If EmailStatus=NeedToSend, BillEmailis a required input.
BillEmailCc:
optional
minor version 8
EmailAddress
Identifies the carbon copy e-mail address where the invoice is sent. If not specified, this field is populated from that defined in Preferences.SalesFormsPrefs.SalesEmailCc. If this email address is invalid, carbon copy email is not sent.
BillEmailBcc:
optional
minor version 8
EmailAddress
Identifies the blind carbon copy e-mail address where the invoice is sent. If not specified, this field is populated from that defined in Preferences.SalesFormsPrefs.SalesEmailBcc. If this email address is invalid, blind carbon copy email is not sent.
DeliveryInfo:
optional
DeliveryInfo, read-only
Email delivery information. Returned when a request has been made to deliver email with the send operation.
Balance:
optional
Decimal, filterable, sortable, read-only
The balance reflecting any payments made against the transaction. Initially set to the value of TotalAmt. A Balance of 0 indicates the invoice is fully paid. Calculated by QuickBooks business logic; any value you supply is over-written by QuickBooks.
TxnSource:
optional
String
Used internally to specify originating source of a credit card transaction.
Deposit:
optional
Decimal
The deposit made towards this invoice.
TransactionLocationType:
optional
minor version 4
String, default is WithinFrance
The account location. Valid values include:
  • WithinFrance
  • FranceOverseas
  • OutsideFranceWithEU
  • OutsideEU

For France locales, only.
Returns
SAMPLE RESPONSE
{ "Invoice": { "Deposit": 0, "AllowIPNPayment": false, "AllowOnlinePayment": false, "AllowOnlineCreditCardPayment": false, "AllowOnlineACHPayment": false, "domain": "QBO", "sparse": false, "Id": "129", "SyncToken": "1", "MetaData": { "CreateTime": "2014-11-09T13:15:36-08:00", "LastUpdatedTime": "2016-03-16T12:27:10-07:00" }, "CustomField": [{ "DefinitionId": "1", "Name": "Crew #", "Type": "STRING_TYPE", "StringValue": "105" }], "DocNumber": "1036", "TxnDate": "2014-11-09", "PrivateNote": "Voided", "LinkedTxn": [], "Line": [{ "Id": "1", "LineNum": 1, "Description": "Sod", "Amount": 0, "DetailType": "SALES_ITEM_LINE_DETAIL", "SalesItemLineDetail": { "ItemRef": { "value": "14", "name": "Sod" }, "Qty": 0, "TaxCodeRef": { "value": "TAX" } } }, { "Id": "2", "LineNum": 2, "Description": "2 cubic ft. bag", "Amount": 0, "DetailType": "SALES_ITEM_LINE_DETAIL", "SalesItemLineDetail": { "ItemRef": { "value": "15", "name": "Soil" }, "Qty": 0, "TaxCodeRef": { "value": "TAX" } } }, { "Id": "3", "LineNum": 3, "Description": "Weekly Gardening Service", "Amount": 0, "DetailType": "SALES_ITEM_LINE_DETAIL", "SalesItemLineDetail": { "ItemRef": { "value": "6", "name": "Gardening" }, "Qty": 0, "TaxCodeRef": { "value": "NON" } } }, { "Id": "4", "LineNum": 4, "Description": "Rock Fountain", "Amount": 0, "DetailType": "SALES_ITEM_LINE_DETAIL", "SalesItemLineDetail": { "ItemRef": { "value": "5", "name": "Rock Fountain" }, "Qty": 0, "TaxCodeRef": { "value": "TAX" } } }, { "Id": "5", "LineNum": 5, "Description": "Fountain Pump", "Amount": 0, "DetailType": "SALES_ITEM_LINE_DETAIL", "SalesItemLineDetail": { "ItemRef": { "value": "11", "name": "Pump" }, "Qty": 0, "TaxCodeRef": { "value": "TAX" } } }, { "Amount": 0, "DetailType": "SUB_TOTAL_LINE_DETAIL", "SubTotalLineDetail": {} }], "TxnTaxDetail": { "TotalTax": 0 }, "CustomerRef": { "value": "8", "name": "0969 Ocean View Road" }, "CustomerMemo": { "value": "Thank you for your business and have a great day!" }, "BillAddr": { "Id": "94", "Line1": "Sasha Tillou", "Line2": "Freeman Sporting Goods", "Line3": "370 Easy St.", "Line4": "Middlefield, CA 94482", "Lat": "INVALID", "Long": "INVALID" }, "ShipAddr": { "Id": "8", "Line1": "370 Easy St.", "City": "Middlefield", "CountrySubDivisionCode": "CA", "PostalCode": "94482", "Lat": "37.4031672", "Long": "-122.0642815" }, "SalesTermRef": { "value": "3" }, "DueDate": "2014-12-09", "TotalAmt": 0, "ApplyTaxAfterDiscount": false, "PrintStatus": "NEED_TO_PRINT", "EmailStatus": "NOT_SET", "BillEmail": { "Address": "Sporting_goods@intuit.com" }, "Balance": 0 }, "time": "2016-03-16T12:27:10.711-07:00" }

SAMPLE RESPONSE
<IntuitResponse xmlns="http://schema.intuit.com/finance/v3" time="2013-04-23T08:30:33.626-07:00"> <Invoice domain="QBO" status="Deleted"> <Id>41</Id> </Invoice> </IntuitResponse>

The Invoice response body.

Id:
required for update
String, filterable, sortable
Unique identifier for this object.
Sort order is ASC by default.
SyncToken:
required for update
String
Version number of the object. It is used to lock an object for use by one app at a time. As soon as an application modifies an object, its SyncToken is incremented. Attempts to modify an object specifying an older SyncToken fails. Only the latest version of the object is maintained by QuickBooks Online.
MetaData:
optional
ModificationMetaData
Descriptive information about the object. The MetaData values are set by Data Services and are read only for all applications.
CustomField [0..3]:
optional
CustomField
Custom field or data extension.
DocNumber:
optional
String, maximum of 21 chars, filterable, sortable
Reference number for the transaction. If not explicitly provided at create time, this field is populated based on the setting of Preferences:CustomTxnNumber as follows:
  • If Preferences:CustomTxnNumber is true a custom value can be provided. If no value is supplied, the resulting DocNumber is null.
  • If Preferences:CustomTxnNumber is false, resulting DocNumber is system generated by incrementing the last number by 1.
If Preferences:CustomTxnNumber is false and a value is supplied, that value is stored even if it is a duplicate. Recommended best practice: check the setting of Preferences:CustomTxnNumber before setting DocNumber.
Sort order is ASC by default.
TxnDate:
optional
Date, filterable, sortable, default is current server date
The date entered by the user when this transaction occurred.
For posting transactions, this is the posting date that affects the financial statements. If the date is not supplied, the current date on the server is used.
Sort order is ASC by default.
DepartmentRef:
optional
ReferenceType, default is null
A reference to a Department object specifying the location of the transaction. Available if Preferences.AccountingInfoPrefs.TrackDepartments is set to true.
Query the Department name list resource to determine the appropriate department object for this reference. Use Department.Id and Department.Name from that object for DepartmentRef.value and DepartmentRef.name, respectively.
PrivateNote:
optional
String, max of 4000 chars
User entered, organization-private note about the transaction. This note does not appear on the invoice to the customer. This field maps to the Statement Memo field on the Invoice form in the QuickBooks Online UI.
LinkedTxn[0..n]:
optional
LinkedTxn
Zero or more related transactions to this Invoice object. The following linked relationships are supported:
  • Links to Estimate and TimeActivity objects can be established directly to this Invoice object with UI or with the API. Create, Read, Update, and Query operations are avaialble at the API level for these types of links.
  • Links to expenses incurred on behalf of the customer are returned in the response with LinkedTxn.TxnType set to ReimburseCharge, ChargeCredit or StatementCharge corresponding to billable customer expenses of type Cash, Delayed Credit, and Delayed Charge, respectively. Links to these types of transactions are established within the QuickBooks UI, only, and are available as read-only at the API level.
  • Links to payments applied to an Invoice object are returned in the response with LinkedTxn.TxnType set to Payment. Links to Payment transactions are established within the QuickBooks UI, only, and are available as read-only at the API level.

Use LinkedTxn.TxnId as the ID in a separate read request for the specific resource to retrieve details of the linked object.
Line [0..n]:
required
Line
Individual line items of a transaction. Valid Line types include:
Sales item line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Group item line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
DetailType:
required
LineDetailTypeEnum
Set to GroupLineDetailfor this type of line.
GroupLineDetail:
required
GroupLineDetail
GroupItemRef:
optional
ReferenceType
Reference to a group item for all the lines that belong to the bundle. Query the Item name list resource to determine the appropriate Item group object (Item.Type=Group) for this reference. Use Item.Id and Item.Name from that object for GroupItemRef.value and GroupItemRef.name, respectively.
Quantity:
optional
Decimal, default is 1
Quantity of the group item.
Line [0..n]:
optional
Line
Individual ItemLine elements that comprise a bundle. Returned in responses.
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
For Invoice objects in global locales: when updating Amount, remove the TxnTaxDetail element in the object before submitting it in the update request payload.
DetailType:
required
LineDetailTypeEnum
Set to SalesItemLineDetailfor this type of line.
SalesItemLineDetail:
optional
SalesItemLineDetail
ItemRef:
optional
ReferenceType
Reference to an Item object.
  • Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively.
  • Set ItemRef.value to SHIPPING_ITEM_ID when Line.amount represents transaction-wide shipping charges. Valid when Preferences.SalesFormsPrefs.AllowShipping is set to true.
  • When a line lacks an ItemRef it is treated as documentation and the Line.Amountattribute is ignored.
  • Applicable to invoice objects, only, and when linktxn specifies a ReimburseCharge. When Item.Id is set to 1, ItemAccountRef refers to reimburse expense account Id.

For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
ClassRef:
optional
ReferenceType
Reference to the Class for the line item. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
UnitPrice:
optional
Decimal
Unit price of the subject item as referenced by ItemRef. Corresponds to the Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item.
If used for unit price, the monetary value of the service or product, as expressed in the home currency. You can override the unit price of the subject item by supplying a new value with create or update operations.
If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax.
MarkupInfo:
optional
MarkupInfo
Used to define markup when this line represents a billable expense on the invoice. Markup information for the billable expense line.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent:
optional
Decimal
Markup amount expressed as a percent of charges already entered in the current transaction. To enter a rate of 10% use 10.0, not 0.01.
PriceLevelRef:
optional
ReferenceType
Reference to a PriceLevel for the markup. Support for this element will be available in the coming months.
MarkkupAccountRef:
optional
ReferenceType, read-only, system-generated
The account associated with the markup. Available with invoice objects, only, and when linktxn specified a ReimburseCharge.
Qty:
optional
Decimal
Number of items for the line.
ItemAccountRef:
optional
ReferenceType, read-only, system-generated
Available with invoice objects, only, and when there is a linkedtxn of type ReimburseCharge for this object. When ItemRef.Id is set to 1, ItemAccountRef maps to the reimbursable charge account.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.
ServiceDate:
optional
Date
Date when the service is performed.
TaxInclusiveAmt:
optional
Decimal
The total amount of the line item including tax.
Constraints: Available when endpoint is evoked with the minorversion=1query parameter.

Description only (also used for inline Subtotal lines):
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars A string representing one of the following:
  • Free form text description of the line item that appears in the printed record.
  • A subtotal line inline with other lines on the sales form and holds the sum of amounts on all lines above it. This is distinct from the overall transaction subtotal represented with a SubTotal detail line.
    • In create requests, set to Subtotal: (case sensitive) to create the subtotal line; the amount is generated by QuickBooks Online business logic.
    • In read requests, lines with Subtotal: nn.nn returned in this field denote subtotal lines in the object.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to DescriptionOnlyfor this type of line.
DescriptionLineDetail:
optional
DescriptionLineDetail
ServiceDate:
optional
Date
Date when the service is performed.
TaxCodeRef:
optional
ReferenceType
Reference to the TaxCodefor this item. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.

Discount line:
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation. Not supported for BillPayment, Estimate, Invoice, or Payment objects.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to DiscountLineDetailfor this type of line.
DiscountLineDetail:
optional
DiscountLineDetail
Discount detail type for the entire transaction. This is in contrast to a discount applied to a specific line. The company preference Sales Form Entry | Discounts must be enabled for this type of line to be available.
PercentBased:
optional
Boolean
True if the discount is a percentage; null or false if discount based on amount.
DiscountPercent:
optional
Decimal
Percentage by which the amount due is reduced, from 0% to 100%. To enter a discount of 8.5% use 8.5, not 0.085.
DiscountAccountRef:
optional
ReferenceType
Income account used to track discounts. Query the Account name list resource to determine the appropriate Account object for this reference, where Account.AccountType=Income and Account.AccountSubType=DiscountsRefundsGiven. Use Account.Id and Account.Name from that object for DiscountAccountRef.value and DiscountAccountRef.name, respectively.
ClassRef:
optional
ReferenceType
Reference to the Class associated with this discount. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
TaxCodeRef:
optional
ReferenceType
The TaxCodeassociated with the sales tax for the expense. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for TaxCodeRef.value and TaxCodeRef.name, respectively.

Subtotal Line (used for the overall transaction)
Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to SubtotalLineDetailfor this type of line.
SubtotalLineDetail:
optional
Subtotal LineDetail
ItemRef:
optional
ReferenceType
Reference to the Item. Query the Item name list resource to determine the appropriate Item object for this reference. Use Item.Id and Item.Name from that object for ItemRef.value and ItemRef.name, respectively. When a line lacks an ItemRef it is treated as documentation and the Line.Amount attribute is ignored.
For France locales: The account associated with the referenced Item object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then the item account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
TxnTaxDetail:
optional
TxnTaxDetail
This data type provides information for taxes charged on the transaction as a whole. It captures the details sales taxes calculated for the transaction based on the tax codes referenced by the transaction. This can be calculated by QuickBooks business logic or you may supply it when adding a transaction. See Global tax model for more information about this element.
CustomerRef:
required
ReferenceType, filterable
Reference to a customer or job. Query the Customer name list resource to determine the appropriate Customer object for this reference. Use Customer.Id and Customer.DisplayName from that object for CustomerRef.value and CustomerRef.name, respectively.
CustomerMemo:
optional
MemoRef
User-entered message to the customer; this message is visible to end user on their transactions.
BillAddr:
optional
PhysicalAddress
Bill-to address of the Invoice. If BillAddris not specified, and a default Customer:BillingAddr is specified in QuickBooks for this customer, the default bill-to address is used by QuickBooks.
ShipAddr:
optional
PhysicalAddress
Identifies the address where the goods must be shipped. If ShipAddris not specified, and a default Customer:ShippingAddr is specified in QuickBooks for this customer, the default ship-to address will be used by QuickBooks.
ClassRef:
optional
ReferenceType
Reference to the Class associated with the transaction. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerTxn is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
SalesTermRef:
optional
ReferenceType, filterable
Reference to the sales term associated with the transaction. Query the Term name list resource to determine the appropriate Term object for this reference. Use Term.Id and Term.Name from that object for SalesTermRef.value and SalesTermRef.name, respectively.
DueDate:
optional
Date, filterable, sortable
Date when the payment of the transaction is due. If date is not provided, the number of days specified in SalesTermRef added the transaction date will be used.
GlobalTaxCalculation:
optional
GlobalTaxCalculationEnum, default is TaxExcluded
Method in which tax is applied. Allowed values are: TaxExcluded, TaxInclusive, and NotApplicable.
ShipMethodRef:
optional
ReferenceType
Reference to the ShipMethod associated with the transaction. There is no shipping method list. Reference resolves to a string.
ShipDate:
optional
Date, default is null
Date for delivery of goods or services.
TrackingNum:
optional
String
Shipping provider's tracking number for the delivery of the goods associated with the transaction.
TotalAmt:
optional
BigDecimal
Indicates the total amount of the transaction. This includes the total of all the charges, allowances, and taxes. Calculated by QuickBooks business logic; any value you supply is over-written by QuickBooks.
CurrencyRef:
required if multicurrency is enabled for the company
CurrencyRefType
Reference to the currency in which all amounts on the associated transaction are expressed. This must be defined if multicurrency is enabled for the company.
Multicurrency is enabled for the company if Preferences.MultiCurrencyEnabled is set to true. Read more about multicurrency support here.
ExchangeRate:
optional
Decimal, default is 1, applicable if multicurrency is enabled for the company
The number of home currency units it takes to equal one unit of currency specified by CurrencyRef.
HomeTotalAmt:
optional
Decimal, read-only, applicable if multicurrency is enabled for the company
Total amount of the transaction in the home currency. Includes the total of all the charges, allowances and taxes. Calculated by QuickBooks business logic.
Value is valid only when CurrencyRef is specified.
HomeBalance:
optional
minor version 3
Decimal, read-only, applicable if multicurrency is enabled for the company
Convenience field containing the amount in Balance expressed in terms of the home currency. Calculated by QuickBooks business logic.
Value is valid only when CurrencyRef is specified and available when endpoint is evoked with the minorversion=3 query parameter.
ApplyTaxAfterDiscount:
optional
Boolean, default is false
If false or null, calculate the sales tax first, and then apply the discount. If true, subtract the discount first and then calculate the sales tax.
PrintStatus:
optional
String, default is NotSet
; Printing status of the invoice.
Valid values: NotSet, NeedToPrint, PrintComplete .
EmailStatus:
optional
String, default is NotSet
Email status of the invoice.
Valid values: NotSet, NeedToSend, EmailSent
BillEmail:
optional
EmailAddress
Identifies the e-mail address where the invoice is sent. If EmailStatus=NeedToSend, BillEmailis a required input.
BillEmailCc:
optional
minor version 8
EmailAddress
Identifies the carbon copy e-mail address where the invoice is sent. If not specified, this field is populated from that defined in Preferences.SalesFormsPrefs.SalesEmailCc. If this email address is invalid, carbon copy email is not sent.
BillEmailBcc:
optional
minor version 8
EmailAddress
Identifies the blind carbon copy e-mail address where the invoice is sent. If not specified, this field is populated from that defined in Preferences.SalesFormsPrefs.SalesEmailBcc. If this email address is invalid, blind carbon copy email is not sent.
DeliveryInfo:
optional
DeliveryInfo, read-only
Email delivery information. Returned when a request has been made to deliver email with the send operation.
Balance:
optional
Decimal, filterable, sortable, read-only
The balance reflecting any payments made against the transaction. Initially set to the value of TotalAmt. A Balance of 0 indicates the invoice is fully paid. Calculated by QuickBooks business logic; any value you supply is over-written by QuickBooks.
TxnSource:
optional
String
Used internally to specify originating source of a credit card transaction.
Deposit:
optional
Decimal
The deposit made towards this invoice.
TransactionLocationType:
optional
minor version 4
String, default is WithinFrance
The account location. Valid values include:
  • WithinFrance
  • FranceOverseas
  • OutsideFranceWithEU
  • OutsideEU

For France locales, only.

Query an invoice

REQUEST URL
Sandbox Base URL: https://sandbox-quickbooks.api.intuit.com
Production Base URL: https://quickbooks.api.intuit.com

Operation: GET /v3/company/<realmID>/query?query=<selectStatement>
Content type: application/text

Sample queries

SAMPLE QUERY
select * from Invoice where id = '239'

SAMPLE QUERY
select * from Invoice where id = '239'

Returns

Returns the results of the query.

All complex types are listed below.

accountrequest

Name:
required
String, required, max 100 characters
User recognizable name for the Account. Account.Name attribute must not contain double quotes (") or colon (:).
AccountType:
required if AccountSubType is not specified
AccountTypeEnum,required if AccountSubType is not specified, filterable
A detailed account classification that specifies the use of this account. The type is based on the Classification.
AccountSubType:
required if AccountType is not specified
String, required if AccountType is not specified, filterable
AThe account sub-type classification and is based on the AccountType value.
AcctNum:
required for France locales
String, default is null
User-defined account number to help the user in identifying the account within the chart-of-accounts and in deciding what should be posted to the account. The Account.AcctNum attribute must not contain colon (:).
For France locales:
  • Name must be unique.
  • Length must be between 6 and 15 characters
  • Must start with the account number from the master category list.
  • Name limited to alpha-numeric characters.
TaxCodeRef:
required for France locales
minor version 3
ReferenceType
Reference to the default tax code used by this account. Tax codes are referenced by the TaxCode.Id in the TaxCode object. Available when endpoint is invoked with the minorversion=3 query parameter. For global locales, only.

accountresponse

Id:
required for update
String, filterable, sortable
Unique identifier for this object.
Sort order is ASC by default.
SyncToken:
required for update
String
Version number of the object. It is used to lock an object for use by one app at a time. As soon as an application modifies an object, its SyncToken is incremented. Attempts to modify an object specifying an older SyncToken fails. Only the latest version of the object is maintained by QuickBooks Online.
MetaData:
optional
ModificationMetaData
Descriptive information about the object. The MetaData values are set by Data Services and are read only for all applications.
Name:
required
String, max 100 characters
User recognizable name for the Account. Account.Name attribute must not contain double quotes (") or colon (:).
SubAccount:
optional
Boolean, system generated, filterable, sortable, read-only
Specifies whether this object represents a parent (false) or subaccount (true).
ParentRef:
optional
ReferenceType, filterable, sortable, default is null
Specifies the Parent AccountId if this represents a SubAccount.
Description:
optional
String, maximum of 100 chars, filterable, sortable, default is null
User entered description for the account, which may include user entered information to guide bookkeepers/accountants in deciding what journal entries to post to the account.
FullyQualifiedName:
optional
String, system generated, filterable, sortable, read-only
Fully qualified name of the object; derived from Name and ParentRef. The fully qualified name prepends the topmost parent, followed by each subaccount separated by colons and takes the form of Parent:Account1:SubAccount1:SubAccount2. System generated. Limited to 5 levels.
Active:
optional
Boolean, filterable, default is true
Whether or not active inactive accounts may be hidden from most display purposes and may not be posted to.
Classification:
optional
String, filterable, default is derived from AccountType and AccountSubtype
The classification of an account. Not supported for non-posting accounts.
Valid values include: Asset, Equity, Expense, Liability, Revenue
AccountType:
required if AccountSubType is not specified
AccountTypeEnum, filterable
A detailed account classification that specifies the use of this account. The type is based on the Classification.
AccountSubType:
required if AccountType is not specified
String, filterable
The account sub-type classification and is based on the AccountType value.
AcctNum:
required for France locales
String, default is null
User-defined account number to help the user in identifying the account within the chart-of-accounts and in deciding what should be posted to the account. The Account.AcctNum attribute must not contain colon (:).
For France locales:
  • Name must be unique.
  • Length must be between 6 and 15 characters
  • Must start with the account number from the master category list.
  • Name limited to alpha-numeric characters.
CurrentBalance:
optional
Decimal, filterable, sortable, read-only
Specifies the balance amount for the current Account. Valid for Balance Sheet accounts.
CurrentBalanceWithSubAccounts:
optional
Decimal, filterable, sortable, read-only
Specifies the cumulative balance amount for the current Account and all its sub-accounts.
CurrencyRef:
optional
CurrencyRef
Reference to the currency in which this account holds amounts.
TaxCodeRef:
minor version 3
ReferenceType, default is null
Reference to the default tax code used by this account. Tax codes are referenced by the TaxCode.Id in the TaxCode object. Available when endpoint is invoked with the minorversion=3 query parameter. For global locales, only.
AccountAlias:
minor version 5
String, default is value of Account.Name
A user friendly name for the account. It must be unique across all account categories. For France locales, only.
For example, if an account is created under category 211 with AccountAlias of Terrains, then the system does not allow creation of an account with same AccountAlias of Terrains for any other category except 211. In other words, 211001 and 215001 accounts cannot have same AccountAlias because both belong to different account category.
For France locales, only.
TxnLocationType
minor version 5
String, default is WithinFrance
The account location. Valid values include:
  • WithinFrance
  • FranceOverseas
  • OutsideFranceWithEU
  • OutsideEU

For France locales, only.

attachablerequest

AttachableRef [0..n]:
optional
AttachableRef
Specifies the transaction object to which this attachable file is to be linked.
FileName:
required for file attachments
String, maximum 1000 chars, filterable, sortable, default is null
FileName of the attachment.
Note:
required for note attachments
String, max 2000 chars, filterable, sortable
The note is either related to the attachment specified with the FileName attribute, or as a standalone note.

attachableresponse

Id:
required for update
IdType, filterable, sortable
Unique Identifier for an Intuit entity (object).
Required for the update operation.
SyncToken:
required for update
String, read-only
Version number of the entity.
Required for the update operation.
MetaData:
optional
ModificationMetaData
Descriptive information about the entity. The MetaData values are set by Data Services and are read only for all applications.
AttachableRef [0..n]:
optional
AttachableRef
Specifies the transaction object to which this attachable file is to be linked.
FileName:
required for file attachments
String, maximum 1000 chars, filterable, sortable, default is null
FileName of the attachment.
Note:
required for standalone notes
String, max 2000 chars, filterable, sortable
This note is either related to the attachment specified by FileName or is a standalone note.
FileAccessUri:
optional
String, read-only, default is null
FullPath FileAccess URI of the attachment. Returned for file attachments.
TempDownloadUri:
optional
String, read-only, default is null
TempDownload URI which can be directly downloaded by clients. Returned for file attachments.
Size:
optional
Decimal, filterable, sortable, default is null
Size of the attachment. Returned for file attachments.
ContentType:
optional
String, max 100 chars, filterable, sortable, default is null
ContentType of the attachment. Returned for file attachments.
Category:
optional
String, max 100 chars, filterable, sortable, default is null
Category of the attachment. Valid values include (case sensitive): Contact Photo, Document, Image, Receipt, Signature, Sound, Other.
Lat:
optional
String, max 100 chars, filterable, sortable, default is null
Latitude from where the attachment was requested.
Long:
optional
String, max 100 chars, filterable, sortable, default is null
Longitude from where the attachment was requested.
PlaceName:
optional
String, max 2000 chars, filterable, sortable, default is null
PlaceName from where the attachment was requested.
Tag:
optional
String, max 2000 chars, filterable, sortable, default is null
Tag name for the requested attachment.
ThumbnailFileAccessUri:
optional
String, read-only, default is null
FullPath FileAccess URI of the attachment thumbnail if the attachment file is of a content type with thumbnail support. Returned for file attachments.
ThumbnailTempDownloadUri:
optional
String, read-only, filterable, sortable
Thumbnail TempDownload URI which can be directly downloaded by clients. This is only available if the attachment file is of a content type with thumbnail support. Returned for file attachments.

accounttypes

Classification

AccountType

AccountSubType

Asset Bank CashOnHand (default)
Checking
MoneyMarket
RentsHeldInTrust
Savings
TrustAccounts
Other Current Asset AllowanceForBadDebts
DevelopmentCosts
EmployeeCashAdvances (default)
OtherCurrentAssets
Inventory
Investment_MortgageRealEstateLoans
Investment_Other
Investment_TaxExemptSecurities
Investment_USGovernmentObligations
LoansToOfficers
LoansToOthers
LoansToStockholders
PrepaidExpenses
Retainage
UndepositedFunds
Fixed Asset AccumulatedDepletion
AccumulatedDepreciation
DepletableAssets
FurnitureAndFixtures (default)
Land
LeaseholdImprovements
OtherFixedAssets
AccumulatedAmortization
Buildings
IntangibleAssets
MachineryAndEquipment
Vehicles
Other Asset LeaseBuyout
OtherLongTermAssets
SecurityDeposits
AccumulatedAmortizationOfOtherAssets
Goodwill
Licenses (default)
OrganizationalCosts
Accounts Receivable AccountsReceivable
Equity Equity OpeningBalanceEquity (default)
PartnersEquity
RetainedEarnings
AccumulatedAdjustment
OwnersEquity
PaidInCapitalOrSurplus
​PartnerContributions
PartnerDistributions
PreferredStock
CommonStock
TreasuryStock
Expense Expense AdvertisingPromotional
BadDebts
BankCharges
CharitableContributions
Entertainment
EntertainmentMeals
EquipmentRental
FinanceCosts
GlobalTaxExpense
Insurance
InterestPaid
LegalProfessionalFees
OfficeGeneralAdministrativeExpenses
OtherMiscellaneousServiceCost
PromotionalMeals
RentOrLeaseOfBuildings
RepairMaintenance
ShippingFreightDelivery
SuppliesMaterials
Travel (default)
TravelMeals
Utilities
Auto
CostOfLabor
DuesSubscriptions
PayrollExpenses
TaxesPaid
UnappliedCashBillPaymentExpense
OtherExpense Depreciation (default)
ExchangeGainOrLoss
OtherMiscellaneousExpense
PenaltiesSettlements
Amortization
CostOfGoodsSold EquipmentRentalCos
OtherCostsOfServiceCos
ShippingFreightDeliveryCos
SuppliesMaterialsCogs
CostOfLaborCos (default)
Liability Accounts Payable AccountsPayable
CreditCard CreditCard
LongTermLiability NotesPayable (default)
OtherLongTermLiabilities
ShareholderNotesPayable
OtherCurrentLiability DirectDepositPayable
LineOfCredit
LoanPayable
GlobalTaxPayable
GlobalTaxSuspense
OtherCurrentLiabilities (default)
PayrollClearing
PayrollTaxPayable
PrepaidExpensesPayable
RentsInTrustLiability
TrustAccountsLiabilities
FederalIncomeTaxPayable
InsurancePayable
SalesTaxPayable
StateLocalIncomeTaxPayable
Revenue Income NonProfitIncome
OtherPrimaryIncome (default)
SalesOfProductIncome
ServiceFeeIncome
DiscountsRefundsGiven
UnappliedCashPaymentIncome
OtherIncome DividendIncome
InterestEarned
OtherInvestmentIncome (default)
OtherMiscellaneousIncome
TaxExemptInterest

accountbasedexpenseline

Id:
required for update
String
The Id of the line item. Its use in requests is as folllows:
  • If Idis greater than zero and exists for the company, the request is considered an update operation for a line item.
  • If no Idis provided, the Idprovided is less than or equal to zero, or the Idprovided is greater than zero and does not exist for the company then the request is considered a create operation for a line item.
Available in all objects that use lines and support the update operation.
LineNum:
optional
Decimal, positive integer
Specifies the position of the line in the collection of transaction lines.
Description:
optional
String, max 4000 chars
Free form text description of the line item that appears in the printed record.
Amount:
required
Decimal, max 15 digits in 10.5 format
The amount of the line item.
DetailType:
required
LineDetailTypeEnum
Set to AccountBasedExpenseLineDetailfor this type of line.
AccountBasedExpenseLineDetail:
optional
AccountBasedExpense LineDetail
CustomerRef:
optional
ReferenceType
​Reference to the Customer associated with the expense. Query the Customer name list resource to determine the appropriate Customer object for this reference. Use Customer.Id and Customer.DisplayName from that object for CustomerRef.value and CustomerRef.name, respectively.
ClassRef:
optional
ReferenceType
Reference to the Class associated with the expense. Available if Preferences.AccountingInfoPrefs.ClassTrackingPerLine is set to true. Query the Class name list resource to determine the appropriate Class object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name, respectively.
AccountRef:
optional
ReferenceType
Reference to the Expense account associated with this item. Query the Account name list resource to determine the appropriate Account object for this reference, where Account.AccountType=Expense. Use Account.Id and Account.Name from that object for AccountRef.value and AccountRef.name, respectively.
For France locales: The account associated with the referenced Account object is looked up in the account category list.
  • If this account has same location as specified in the transaction by the TransactionLocationType attribute and the same VAT as in the line item TaxCodeRef attribute, then this account is used.
  • If there is a mismatch, then the account from the account category list that matches the transaction location and VAT is used.
  • If this account is not present in the account category list, then a new account is created with the new location, new VAT code, and all other attributes as in the default account.
BillableStatus:
optional
String
The billable status of the expense.
Constraints: Valid values: Billable, NotBillable, HasBeenBilled
MarkupInfo:
optional
MarkupInfo
Markup information for the expense.
PercentBased:
optional
Boolean
True if the markup is expressed as a percentage.
Value:
optional
Decimal
Markup value.
Percent: