Custom Fields in Sales Transaction APIs now require a Definition ID

Here is a summary of the change introduced to the Sales Transaction APIs that use Custom Fields; this change was part of the QBO v76 release (7/25/2014):

Prior to the v76 release, the Custom Field “Name” attribute was used to uniquely identify each Custom Field in Sales Transaction APIs. However, we found an issue with this approach: when the name of the Custom Field was updated via the UI, any subsequent API calls would need to reference the updated name. More than likely the application is unaware of this change that has happened through the UI unless a call was made to fetch the data prior to creating/updating the transaction . If a create/update transaction API call is issued with the old name, then the new custom field value is not updated in QBO.

In this release, we have fixed this issue by introducing an id attribute for Custom Fields – all Custom Fields used in the Sales Transactions APIs will now need this “Definition Id”. The Definition Id represents the order of the Custom Field (as defined in the Company Settings page in the QBO UI) and takes the value 1, 2 or 3. (Note: There were no changes to the XSD)
Important functionality changes:

• If a Sales Transaction is created without the Definition Id then the Custom Field is ignored and is not returned in the response. In the QBO UI, the transaction will be available, but the custom field will not be present.
• If a Sales Transaction is updated without the Definition Id, then the new value is ignored and the old value of the Custom Field is returned in the response. 

Example of an Invoice Create request with Custom Fields:

Request XML:

<Invoice xmlns=”http://schema.intuit.com/finance/v3″>
<CustomField>
<DefinitionId>1</DefinitionId>
<Name>CustomField1</Name>
<Type>StringType</Type>
<StringValue>Test1</StringValue>
</CustomField>
<CustomField>
<DefinitionId>2</DefinitionId>
<Name>CustomField2</Name>
<Type>StringType</Type>
<StringValue>Test2</StringValue>
</CustomField>
<CustomField>
<DefinitionId>3</DefinitionId>
<Name>CustomField3</Name>
<Type>StringType</Type>
<StringValue>Test3</StringValue>
</CustomField>
<Line>
<Amount>15</Amount>
<DetailType>SalesItemLineDetail</DetailType>
<SalesItemLineDetail>
<ItemRef>1</ItemRef>
</SalesItemLineDetail>
</Line>
<CustomerRef>67</CustomerRef>
</Invoice>

Response XML:

<IntuitResponse xmlns=”http://schema.intuit.com/finance/v3″ time=”2014-08-04T13:37:56.379-07:00″>
<Invoice domain=”QBO” sparse=”false”>
<Id>2546</Id>
<SyncToken>0</SyncToken>
<MetaData>
<CreateTime>2014-08-04T13:37:56-07:00</CreateTime>
<LastUpdatedTime>2014-08-04T13:37:56-07:00</LastUpdatedTime>
</MetaData>
<CustomField>
<DefinitionId>1</DefinitionId>
<Name>Customfield1</Name>
<Type>StringType</Type>
<StringValue>Test1</StringValue>
</CustomField>
<CustomField>
<DefinitionId>2</DefinitionId>
<Name>Customfield2</Name>
<Type>StringType</Type>
<StringValue>Test2</StringValue>
</CustomField>
<CustomField>
<DefinitionId>3</DefinitionId>
<Name>Customfield3</Name>
<Type>StringType</Type>
<StringValue>Test3</StringValue>
</CustomField>
<DocNumber>1293</DocNumber>
<TxnDate>2014-08-04</TxnDate>
<Line>
<Id>1</Id>
<LineNum>1</LineNum>
<Amount>15.00</Amount>
<DetailType>SalesItemLineDetail</DetailType>
<SalesItemLineDetail>
<ItemRef name=”Services”>1</ItemRef>
<TaxCodeRef>NON</TaxCodeRef>
</SalesItemLineDetail>
</Line>
<Line>
<Amount>15.00</Amount>
<DetailType>SubTotalLineDetail</DetailType>
<SubTotalLineDetail />
</Line>
<TxnTaxDetail>
<TotalTax>0</TotalTax>
</TxnTaxDetail>
<CustomerRef name=”Name131021134027462″>67</CustomerRef>
<BillAddr>
<Id>68</Id>
<Line1>Line1131021134027463</Line1>
<Line2>Line2131021134027464</Line2>
<City>New York</City>
<CountrySubDivisionCode>State</CountrySubDivisionCode>
<PostalCode>569878</PostalCode>
<Lat>INVALID</Lat>
<Long>INVALID</Long>
</BillAddr>
<ShipAddr>
<Id>68</Id>
<Line1>Line1131021134027463</Line1>
<Line2>Line2131021134027464</Line2>
<City>New York</City>
<CountrySubDivisionCode>State</CountrySubDivisionCode>
<PostalCode>569878</PostalCode>
<Lat>INVALID</Lat>
<Long>INVALID</Long>
</ShipAddr>
<DueDate>2014-09-03</DueDate>
<TotalAmt>15.00</TotalAmt>
<ApplyTaxAfterDiscount>false</ApplyTaxAfterDiscount>
<PrintStatus>NeedToPrint</PrintStatus>
<EmailStatus>NotSet</EmailStatus>
<Balance>15.00</Balance>
<Deposit>0</Deposit>
<AllowIPNPayment>false</AllowIPNPayment>
<AllowOnlinePayment>false</AllowOnlinePayment>
<AllowOnlineCreditCardPayment>false</AllowOnlineCreditCardPayment>
<AllowOnlineACHPayment>false</AllowOnlineACHPayment>
</Invoice>
</IntuitResponse>

To ensure backward compatibility, the server does not return an error when Definition Ids are not present in the request. 

For more details on Custom fields please refer to our documentation –
https://developer.intuit.com/docs/0025_quickbooksapi/0050_data_services/020_key_concepts/0200_custom_fields