Quickbooks Online Invoice XML

Tasks

XML

The Import Invoices task allows you to create and update invoices in QuickBooks. Any fields not documented below are not currently supported by our upload.

Sample import file for creating a basic invoice:

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfInvoice
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <RecordOfInvoice>
    <ExternalId>7440</ExternalId>
    <Data
      domain="QBO"
      xmlns="http://schema.intuit.com/finance/v3">
      <AutoDocNumber>true</AutoDocNumber>
      <Line>
        <Amount>50</Amount>
        <DetailType>SalesItemLineDetail</DetailType>
        <SalesItemLineDetail>
          <ItemRef name="Catering"></ItemRef>
          <UnitPrice>50</UnitPrice>
          <Qty>1</Qty>
          <TaxCodeRef name="20.0% S"></TaxCodeRef>
        </SalesItemLineDetail>
      </Line>
      <CustomerRef name="Zynk Software"></CustomerRef>
    </Data>
  </RecordOfInvoice>
</ArrayOfInvoice>

In each of the following sections most of the XML has been omitted to make the samples easier to read, you will need to provide the above as a minimum to create an invoice. The whole structure from the root element down is shown in the samples below as a reference of where elements should appear in the object model.

Invoice Details

XML Field	QuickBooks Field	Example	Field Type	Field Length	Input	Notes
Id	-	1234	integer	-	Optional	Used for matching to existing invoices.
ExternalId	-	7440	string	255	Optional	Used for matching to existing invoices, and duplicate prevention. The value provided will be stored in Zynk's truth table, and used to lookup the Id of the invoice.
DocNumber	Invoice No.	1001	string	21	Dependant	Used for matching to existing invoices. Can be auto generated when creating new invoices, by setting AutoDocNumber to true (requires custom transaction numbers to be disabled in QuickBooks).
AutoDocNumber	-	false	boolean	-	Optional	Set to true to generate a DocNumber automatically if not specified in the XML. AutoDocNumber will default to false if not specified.
TxnDate	Invoice Date	2016-07-15	date	-	Optional	Will default to the current date if not provided.
CustomerRef	Customer	1	integer	-	Required	If you don't know the customer ID, you can specify their name using the name attribute, and the task will perform a lookup.
DepartmentRef	Department	1	integer	-	Optional	Can only be set if department tracking is enabled in QuickBooks. If you don't know the department ID, you can specify the name using the name attribute, and the task will perform a lookup.
ExchangeRate	Exchange Rate	1.345	decimal	-	Optional	Defaults to 1 if not specified. Can only be set if multi currency is enabled in QuickBooks.
PrivateNote	Statement Memo	Example memo	string	4000	Optional
CustomerMemo	Message displayed on invoice	Example memo	string	1000	Optional
BillAddr	Billing Address	-	-	-	Optional	Will default to the customer's default bill-to address if not specified.
BillAddr > Line 1	Billing Address	Zynk Software	string	500	Optional
BillAddr > Line 2	Billing Address	Nelson House	string	500	Optional
BillAddr > Line 3	Billing Address	Jesmond	string	500	Optional
BillAddr > Line 4	Billing Address	string	500	Optional
BillAddr > Line 5	Billing Address	string	500	Optional
BillAddr > City	Billing Address	Newcastle	string	255	Optional
BillAddr > Country	Billing Address	England	string	255	Optional
BillAddr > CountrySubDivisionCode	Billing Address	Tyne & Wear	string	255	Optional
BillAddr > PostalCode	Billing Address	NE2 3AE	string	31	Optional
ShipAddr	Shipping Address	-	-	-	Optional	Will default to the customer's default ship-to address if not specified.
ShipAddr > Line 1	Shipping Address	Zynk Software	string	500	Optional
ShipAddr > Line 2	Shipping Address	Nelson House	string	500	Optional
ShipAddr > Line 3	Shipping Address	Jesmond	string	500	Optional
ShipAddr > Line 4	Shipping Address	string	500	Optional
ShipAddr > Line 5	Shipping Address	string	500	Optional
ShipAddr > City	Shipping Address	Newcastle	string	255	Optional
ShipAddr > Country	Shipping Address	England	string	255	Optional
ShipAddr > CountrySubDivisionCode	Shipping Address	Tyne & Wear	string	255	Optional
ShipAddr > PostalCode	Shipping Address	NE2 3AE	string	31	Optional
SalesTermRef	Terms	1	integer	-	Optional	If you don't know the sales term ID, you can specify the name using the name attribute, and the task will perform a lookup.
DueDate	Due Date	2016-07-15	date	-	Optional	Will be set based on the SalesTermRef of not specified.
GlobalTaxCalculation	Amounts are	TaxExcluded	enum	-	Optional	Allowed values are TaxExcluded, TaxInclusive and NotApplicable.
ShipMethodRef	Ship Via	1	integer	-	Optional	If you don't know the shipping method ID, you can specify the name using the name attribute, and the task will perform a lookup.
ShipDate	Ship Date	2016-07-15	date	-	Optional
TrackingNum	Tracking No.	DH0012-4251	string	31	Optional
ApplyTaxAfterDiscount	-	false	boolean	-	Optional	Only applicable to US version of QuickBooks. Defaults to false.
PrintStatus	-	NeedToPrint	enum	-	Optional	Allowed values are NotSet, NeedToPrint and PrintComplete. Defaults to NotSet if not provided.
EmailStatus	-	NeedToSend	enum	-	Optional	Allowed values are NotSet, NeedToSend and EmailSent. Defaults to NotSet if not provided.
BillEmail > Address	Email	[email protected]	string	100	Dependant	Must be provided if EmailStatus is set to NeedToSend.
Deposit	Deposit	10.99	decimal	-	Optional

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfInvoice
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <RecordOfInvoice>
    <ExternalId>7440</ExternalId>
    <Data
      domain="QBO"
      xmlns="http://schema.intuit.com/finance/v3">
      <Id>1234</Id>
      <DocNumber>1001</DocNumber>
      <AutoDocNumber>false</AutoDocNumber>
      <TxnDate>2016-07-15</TxnDate>
      <CustomerRef name="Zynk Software">1</CustomerRef>
      <DepartmentRef name="Sales">1</DepartmentRef>
      <ExchangeRate>1.345</ExchangeRate>
      <PrivateNote>Example memo</PrivateNote>
      <CustomerMemo>Example memo</CustomerMemo>
      <BillAddr>
        <Line1>Zynk Software</Line1>
        <Line2>Nelson House</Line2>
        <Line3>Jesmond</Line3>
        <Line4></Line4>
        <Line5></Line5>
        <City>Newcastle</City>
        <Country>England</Country>
        <CountrySubDivisionCode>Tyne &mp; Wear</CountrySubDivisionCode>
        <PostalCode>NE2 3AE</PostalCode>
      </BillAddr>
      <ShipAddr>
        <Line1>Zynk Software</Line1>
        <Line2>Nelson House</Line2>
        <Line3>Jesmond</Line3>
        <Line4></Line4>
        <Line5></Line5>
        <City>Newcastle</City>
        <Country>England</Country>
        <CountrySubDivisionCode>Tyne &mp; Wear</CountrySubDivisionCode>
        <PostalCode>NE2 3AE</PostalCode>
      </ShipAddr>
      <SalesTermRef name="Due on receipt">1</SalesTermRef>
      <DueDate>2016-07-15</DueDate>
      <GlobalTaxCalculation>TaxExcluded</GlobalTaxCalculation>
      <ShipMethodRef name="DHL">1</ShipMethodRef>
      <ShipDate>2016-07-15</ShipDate>
      <TrackingNum>DH0012-4251</TrackingNum>
      <ApplyTaxAfterDiscount>false</ApplyTaxAfterDiscount>
      <PrintStatus>NeedToPrint</PrintStatus>
      <EmailStatus>NeedToSend</EmailStatus>
      <BillEmail>
        <Address>[email protected]</Address>
      </BillEmail>
      <Deposit>10.99</Deposit>
    </Data>
  </RecordOfInvoice>
</ArrayOfInvoice>

Invoice Details - Items

There are several different types of item that can be added to an invoice, as shown below. The item type is specified by the DetailType element in the XML.

Sales Item Line

XML Field	QuickBooks Field	Example	Field Type	Field Length	Input	Notes
Id	-	1234	integer	-	Dependant	Used for matching to existing line items. Required when updating an existing item line.
LineNum	-	1	integer	-	Optional	Specifies the position of the line.
Description	Description	Catering	string	4000	Optional
Amount	Amount	50	decimal	-	Required	The total amount for the line.
DetailType	-	SalesItemLineDetail	enum	-	Required	Set to SalesItemLineDetail for this item type.
SalesItemLineDetail > ItemRef	Product/Service	1	integer	-	Required	If you don't know the item ID, you can specify the SKU or name using the name attribute, and the task will perform a lookup.
SalesItemLineDetail > UnitPrice	Rate	50	decimal	-	Optional
SalesItemLineDetail > Qty	Qty	1	decimal	-	Required
SalesItemLineDetail > TaxCodeRef	Vat	1	integer	-	Optional	If you don't know the tax code ID, you can specify the name using the name attribute, and the task will perform a lookup.
SalesItemLineDetail > ServiceDate	Service Date	2016-07-15	date	-	Optional	Can only be set if service dates are enabled in QuickBooks.

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfInvoice
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <RecordOfInvoice>
    <Data
      domain="QBO"
      xmlns="http://schema.intuit.com/finance/v3">
      <Line>
        <Id>1234</Id>
        <LineNum>1</LineNum>
        <Description>Catering</Description>
        <Amount>50</Amount>
        <DetailType>SalesItemLineDetail</DetailType>
        <SalesItemLineDetail>
          <ItemRef name="Catering">3</ItemRef>
          <UnitPrice>50</UnitPrice>
          <Qty>1</Qty>
          <TaxCodeRef name="20.0% S">3</TaxCodeRef>
          <ServiceDate>2016-07-15</ServiceDate>
        </SalesItemLineDetail>
      </Line>
    </Data>
  </RecordOfInvoice>
</ArrayOfInvoice>

Group Item Line

XML Field	QuickBooks Field	Example	Field Type	Field Length	Input	Notes
Id	-	1234	integer	-	Dependant	Used for matching to existing line items. Required when updating an existing item line.
LineNum	-	1	integer	-	Optional	Specifies the position of the line.
Description	Description	Group	string	4000	Optional
DetailType	-	GroupLineDetail	enum	-	Required	Set to GroupLineDetail for this item type.
GroupLineDetail > GroupItemRef	Product/Service	1	integer	-	Required	If you don't know the group item ID, you can specify the SKU or name using the name attribute, and the task will perform a lookup. The chosen item must have the type 'Group'.
GroupLineDetail > UnitPrice	Rate	50	decimal	-	Optional
GroupLineDetail > Quantity	Qty	1	decimal	-	Required
GroupLineDetail > Line	Product/Service	-	Item	-	Required	The collection of items in the group.

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfInvoice
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <RecordOfInvoice>
    <Data
      domain="QBO"
      xmlns="http://schema.intuit.com/finance/v3">
      <Line>
        <Id>1234</Id>
        <LineNum>1</LineNum>
        <Description>A Bundle Product</Description>
        <DetailType>GroupLineDetail</DetailType>
        <GroupLineDetail>
          <GroupItemRef name="Bundle Product">22</GroupItemRef>
          <Quantity>1</Quantity>
          <Line>
            <Id>4</Id>
            <LineNum>2</LineNum>
            <Description>Catering -- food &amp; beverage</Description>
            <Amount>0</Amount>
            <DetailType>SalesItemLineDetail</DetailType>
            <SalesItemLineDetail>
              <ItemRef name="Catering">3</ItemRef>
              <UnitPrice>0</UnitPrice>
              <Qty>1</Qty>
              <TaxCodeRef name="20.0% S">3</TaxCodeRef>
            </SalesItemLineDetail>
          </Line>
          <Line>
            <Id>5</Id>
            <LineNum>3</LineNum>
            <Description>Entertainment for the event</Description>
            <Amount>0</Amount>
            <DetailType>SalesItemLineDetail</DetailType>
            <SalesItemLineDetail>
              <ItemRef name="Entertainment">6</ItemRef>
              <UnitPrice>0</UnitPrice>
              <Qty>1</Qty>
              <TaxCodeRef name="20.0% S">3</TaxCodeRef>
            </SalesItemLineDetail>
          </Line>
        </GroupLineDetail>
      </Line>
    </Data>
  </RecordOfInvoice>
</ArrayOfInvoice>

Description Only Item Line

The description only item is also used for setting inline subtotals.

XML Field	QuickBooks Field	Example	Field Type	Field Length	Input	Notes
Id	-	1234	integer	-	Dependant	Used for matching to existing line items. Required when updating an existing item line.
LineNum	-	1	integer	-	Optional	Specifies the position of the line.
Description	Description	An item	string	4000	Optional	To create a subtotal line, set this to 'Subtotal:'. QuickBooks will calculate the subtotal amount automatically.
Amount	Amount	50	decimal	-	Dependant	Not required when creating a subtotal line.
DetailType	-	DescriptionOnly	enum	-	Required	Set to DescriptionOnly for this item type.
GroupLineDetail > ServiceDate	Service Date	2016-07-15	date	-	Optional	Can only be set if service dates are enabled in QuickBooks.
GroupLineDetail > TaxCodeRef	Vat	1	integer	-	Optional	If you don't know the tax code ID, you can specify the name using the name attribute, and the task will perform a lookup.

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfInvoice
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <RecordOfInvoice>
    <Data
      domain="QBO"
      xmlns="http://schema.intuit.com/finance/v3">
      <Line>
        <Id>1234</Id>
        <LineNum>1</LineNum>
        <Description>An item</Description>
        <Amount>50</Amount>
        <DetailType>DescriptionOnly</DetailType>
        <DescriptionLineDetail>
          <ServiceDate>2016-07-15</ServiceDate>
          <TaxCodeRef name="20.0% S">3</TaxCodeRef>
        </DescriptionLineDetail>
      </Line>
      <!-- Inline subtotal -->
      <Line>
        <Id>2</Id>
        <LineNum>2</LineNum>
        <Description>Subtotal:</Description>
        <DetailType>DescriptionOnly</DetailType>
        <DescriptionLineDetail />
      </Line>
    </Data>
  </RecordOfInvoice>
</ArrayOfInvoice>

Discount Line

Specifies a discount to apply to the whole transaction. Discount Lines can only be added if discounts are enabled in QuickBooks.

XML Field	QuickBooks Field	Example	Field Type	Field Length	Input	Notes
Amount	Amount	10.5	decimal	-	Required	The total amount for the line.
DetailType	-	DiscountLineDetail	enum	-	Required	Set to DiscountLineDetail for this item type.
DiscountLineDetail > PercentBased	Discount percent / Discount value	false	bool	-	Required	Set to true if the discount is a percentage discount, or false if it is a discount amount.
DiscountLineDetail > DiscountPercent	Rate	10.5	decimal	-	Optional
DiscountLineDetail > DiscountAccountRef	-	1	integer	-	Optional	If you don't know the account ID, you can specify the name using the name attribute, and the task will perform a lookup. The chosen account must have the Type 'Income' and Sub Type 'DiscountsRefundsGiven'.

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfInvoice
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <RecordOfInvoice>
    <Data
      domain="QBO"
      xmlns="http://schema.intuit.com/finance/v3">
      <Line>
        <Amount>10.5</Amount>
        <DetailType>DiscountLineDetail</DetailType>
        <DiscountLineDetail>
          <PercentBased>false</PercentBased>
          <DiscountPercent>10.5</DiscountPercent>
          <DiscountAccountRef name="Discounts given">1</DiscountAccountRef>
        </DiscountLineDetail>
      </Line>
    </Data>
  </RecordOfInvoice>
</ArrayOfInvoice>

Custom Fields

QuickBooks supports up to 3 custom fields, which can be set as described below. The custom field must already exist in QuickBooks, the task will not automatically create custom fields.

XML Field	QuickBooks Field	Example	Field Type	Field Length	Input	Notes
DefinitionId	Name	1	integer	-	Dependant	This is the number of the custom field, used for matching. Will be either 1, 2 or 3. Required if Name is not specified.
Name	Name	Sales Rep	string	15	Dependant	The name of the custom field, used for matching. Required if DefinitionId is not specified.
StringValue	Value	John Smith	string	31	Optional

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfInvoice
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <RecordOfInvoice>
    <Data
      domain="QBO"
      xmlns="http://schema.intuit.com/finance/v3">
      <CustomField>
        <DefinitionId>1</DefinitionId>
        <Name>Sales Rep</Name>
        <StringValue>John Smith</StringValue>
      </CustomField>
    </Data>
  </RecordOfInvoice>
</ArrayOfInvoice>