Quickbooks Online Bill XML

Tasks

XML

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

Sample import file for creating a basic bill:

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfBill 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <RecordOfBill>
    <ExternalId>7440</ExternalId>
    <Data domain="QBO"  
      xmlns="http://schema.intuit.com/finance/v3">
      <CurrencyRef>GBP</CurrencyRef>
      <Line>
        <LineNum>1</LineNum>
        <Description>Catering -- food &amp; beverage</Description>
        <Amount>10</Amount>
        <DetailType>ItemBasedExpenseLineDetail</DetailType>
        <ItemBasedExpenseLineDetail>
          <ItemRef name="Catering">3</ItemRef>
          <UnitPrice>10</UnitPrice>
          <Qty>1</Qty>
          <TaxCodeRef>3</TaxCodeRef>
          <BillableStatus>NotBillable</BillableStatus>
        </ItemBasedExpenseLineDetail>
      </Line>
      <VendorRef name="Andrew Haberbosch"></VendorRef>
    </Data>
  </RecordOfBill>
</ArrayOfBill>

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 a bill. 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.

Bill Details

XML Field	QuickBooks Field	Example	Field Type	Field Length	Input	Notes
Id	-	1234	integer	-	Optional	Used for matching to existing bills.
ExternalId	-	7440	string	255	Optional	Used for matching to existing bills, and duplicate prevention. The value provided will be stored in Zynk's truth table, and used to lookup the Id of the bill.
DocNumber	Bill No.	1001	string	21	Optional	Used for matching to existing bills.
TxnDate	Bill Date	2016-07-15	date	-	Optional	Will default to the current date if not provided.
VendorRef	Supplier	1	integer	-	Required	If you don't know the supplier ID, you can specify their name using the name attribute, and the task will perform a lookup.
DepartmentRef	Department	1	integer	-	Optional	If you don't know the department ID, you can specify the name using the name attribute, and the task will perform a lookup.
CurrencyRef	Currency	GBP	string	3	Dependant	Must be provided if multi currency is enabled in Quickbooks.
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	Memo	Example memo	string	4000	Optional
Memo	Your Message To Supplier	Example memo	string	1000	Optional
APAccountRef	Account	1	integer	-	Required	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 classification 'Liability' and sub type 'Accounts Payable'.
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.

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfBill
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <RecordOfBill>
    <ExternalId>7440</ExternalId>
    <Data
      domain="QBO"
      xmlns="http://schema.intuit.com/finance/v3">
      <Id>1234</Id>
      <DocNumber>1001</DocNumber>
      <TxnDate>2016-07-15</TxnDate>
      <VendorRef name="Zynk Software Vendor">1</VendorRef>
      <DepartmentRef name="Sales">1</DepartmentRef>
      <CurrencyRef name="British Pound Sterling">GBP</CurrencyRef>
      <ExchangeRate>1.345</ExchangeRate>
      <PrivateNote>Example memo</PrivateNote>
      <Memo>Example memo</Memo>
      <APAccountRef name="Creditors">71</APAccountRef>
      <SalesTermRef name="Due on receipt">1</SalesTermRef>
      <DueDate>2016-07-15</DueDate>
      <GlobalTaxCalculation>TaxExcluded</GlobalTaxCalculation>
    </Data>
  </RecordOfBill>
</ArrayOfBill>

Bill Details - Items

There are two types of item that can be added to a bill, as shown below. The item type is specified by the DetailType element in the XML.

Item Based Expense 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	Water bottles	string	4000	Optional
Amount	Amount	661.71	decimal	-	Required	The total amount for the line.
DetailType	-	ItemBasedExpenseLineDetail	enum	-	Required	Set to ItemBasedExpenseLineDetail for this item type.
ItemBasedExpenseLineDetail > ItemRef	Product/Service	1	integer	-	Optional	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. If an item ref is not provided, it is treated as documentation and the Amount will be ignored.
ItemBasedExpenseLineDetail > UnitPrice	Rate	66.1717023	decimal	-	Optional
ItemBasedExpenseLineDetail > MarkupInfo > PercentBased	-	true	boolean	-	Optional
ItemBasedExpenseLineDetail > MarkupInfo > Value	-	40	decimal	-	Optional
ItemBasedExpenseLineDetail > MarkupInfo > Percent	-	80	decimal	-	Optional
ItemBasedExpenseLineDetail > Qty	Qty	10	decimal	-	Required
ItemBasedExpenseLineDetail > TaxCodeRef	Vat	13.24	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.
ItemBasedExpenseLineDetail > CustomerRef	Customer	1	integer	-	Optional	If you don't know the customer ID, you can specify the name using the name attribute, and the task will perform a lookup.
ItemBasedExpenseLineDetail > Billable Status	-	Billable	enum	-	Optional	Allowed values are Billable, NotBillable and HasBeenBill.

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfBill
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <RecordOfBill>
    <Data
      domain="QBO"
      xmlns="http://schema.intuit.com/finance/v3">
      <Line>
        <Id>1234</Id>
        <LineNum>1</LineNum>
        <Description>Water bottles</Description>
        <Amount>661.71</Amount>
        <DetailType>ItemBasedExpenseLineDetail</DetailType>
        <ItemBasedExpenseLineDetail>
          <ItemRef name="Water Bottles"></ItemRef>
          <UnitPrice>66.1717023</UnitPrice>
          <MarkupInfo>
            <PercentBased>true</PercentBased>
            <Value>52.9373618</Value>
            <Percent>80</Percent>
          </MarkupInfo>
          <Qty>10</Qty>
          <TaxCodeRef name="20.0% S">1</TaxCodeRef>
          <CustomerRef name="Zynk Software">1</CustomerRef>
          <BillableStatus>Billable</BillableStatus>
        </ItemBasedExpenseLineDetail>
      </Line>
    </Data>
  </RecordOfBill>
</ArrayOfBill>

Account Based Expense 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	Expense	string	4000	Optional
Amount	Amount	200.00	decimal	-	Required	The total amount for the line.
DetailType	-	AccountBasedExpenseLineDetail	enum	-	Required	Set to AccountBasedExpenseLineDetail for this item type.
AccountBasedExpenseLineDetail > AccountRef	Account	1	decimal	-	Required	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 'Expense'.
ItemBasedExpenseLineDetail > MarkupInfo > PercentBased	-	true	boolean	-	Optional
ItemBasedExpenseLineDetail > MarkupInfo > Value	-	150.00	decimal	-	Dependant	Required when PercentBased is set to false.
ItemBasedExpenseLineDetail > MarkupInfo > Percent	-	75	decimal	-	Dependant	Required when PercentBased is set to true.
ItemBasedExpenseLineDetail > TaxAmount	Vat	40	decimal	-	Optional
ItemBasedExpenseLineDetail > 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.
ItemBasedExpenseLineDetail > CustomerRef	Customer	1	integer	-	Optional	If you don't know the customer ID, you can specify the name using the name attribute, and the task will perform a lookup.
ItemBasedExpenseLineDetail > Billable Status	-	Billable	enum	-	Optional	Allowed values are Billable, NotBillable and HasBeenBill.

<?xml version="1.0" encoding="utf-8"?>
<ArrayOfBill
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <RecordOfBill>
    <Data
      domain="QBO"
      xmlns="http://schema.intuit.com/finance/v3">
      <Line>
        <Id>1234</Id>
        <Description>Expense</Description>
        <Amount>200.00</Amount>
        <DetailType>AccountBasedExpenseLineDetail</DetailType>
        <AccountBasedExpenseLineDetail>
          <AccountRef name="Dues and Subscriptions">1</AccountRef>
          <TaxAmount>40</TaxAmount>
          <MarkupInfo>
            <PercentBased>true</PercentBased>
            <Value>150.00</Value>
            <Percent>75</Percent>
          </MarkupInfo>
          <TaxCodeRef name="20.0% S">1</TaxCodeRef>
          <CustomerRef name="Zynk Software">1</CustomerRef>
          <BillableStatus>Billable</BillableStatus>
        </AccountBasedExpenseLineDetail>
      </Line>
    </Data>
  </RecordOfBill>
</ArrayOfBill>

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"?>
<ArrayOfBill
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <RecordOfBill>
    <Data
      domain="QBO"
      xmlns="http://schema.intuit.com/finance/v3">
      <CustomField>
        <DefinitionId>1</DefinitionId>
        <Name>Sales Rep</Name>
        <StringValue>John Smith</StringValue>
      </CustomField>
    </Data>
  </RecordOfBill>
</ArrayOfBill>