Change data capture

The change data capture (CDC) operation returns a list of objects that have changed since a specified time. The app can periodically poll data services with a CDC request operation to receive the full payload for objects changed within the specified look-back period. The app, in turn, refreshes its local copy of the objects to maintain consistency with online data. The app calls the CDC operation, specifying a list of object types and a date-time specifying how far to look back.

  • The QuickBooks API returns all objects specified in the object list that have changed since the specified look-back time. 
  • Deleted objects include a status attribute set to deleted.
  • The look-back time can be up to 30 days. 
  • A given CDC request returns a maximum of 1000 objects. It is suggested to query with a look-back time shorter than 30 days that can ensure full data is returned.
  • This operation is supported for all entities except JournalCode, TaxAgency, TimeActivity, TaxCode, and TaxRate.

Full details about the change data capture resource can be found here. Consult the Accounting API reference guide for the current resource list.

Also consider using webhooks, which provide event notification back to your app via HTTP POST.  For objects that are supported, webhooks can reduce the need to have servers dedicated to polling.  See Webhooks for further information. 

Using change data capture

Operation:      GET https://quickbooks.api.intuit.com/v3/company/<realmID>/cdc?entities=<entityList>&changedSince=<dateTime>
Content type: text/plain

Where:
<entityList> is a comma-separated list of entity names.
<dateTime> is a date-time stamp for a look-back date within 30 days of today.

As a way of example, consider this scenario: an application wants to synchronize data with QuickBooks for every hour to refresh its local copy of the following objects:

  • Estimate
  • Customer

Suppose that the last refresh was performed at 2015-12-23T09:00-07:00 (December 23, 2015, at 9:00, PST).  Since that time, a QuickBooks user has updated two Estimate objects, deleted one Estimate object, and updated two Customer objects. To get these changes, the app performs the following steps:

1. At 10:00 AM, one hour after the last refresh, the app calls the CDC operation:

GET https://quickbooks.api.intuit.com/v3/company/<realmid>/cdc?entities=estimate,customer&changedSince=2015-12-23T10:00:00-07:00

2. The QuickBooks API sends a response body back to the app similar to that as shown below . This one includes full object payloads for two Customer objects and two Estimate objects (some content has been replaced by "...") that have been modified between 9:00 and 10:00.  The deleted object payload is returned for the deleted Estimate object. 

Click here to view sample.
{
    "CDCResponse": [{
        "QueryResponse": [{
            "Customer": [{
                ...
                "Id": "63",
                ...
            }, 
            {
                ...
                "Id": "99",
                ...
            }],
            "startPosition": 1,
            "maxResults": 2
        }, 
        {
            "Estimate": [{
                ...
                "Id": "34",
                ...
            }, 
            {
                ...
                "Id": "123",
                ...
            }, 
            {
                "domain": "QBO",
                "status": "Deleted",
                "Id": "979",
                "MetaData": {
                    "LastUpdatedTime": "2015-12-23T12:55:50-08:00"
                }
            }],
            "startPosition": 1,
            "maxResults": 3,
            "totalCount": 5
        }]
    }],
    "time": "2015-12-23T10:00:01-07:00"
}

3. The app updates its local database based on what was returned in the CDC response.  Deleted objects include a status attribute set to delete. In this case the app:

  • Refreshes local storage for two Customer objects whose ids are 63 and 99.
  • Refreshes local storage for two Estimate objects whose id are 34 and 123.
  • Removes Estimate object 979 from local storage, or otherwise denotes it is deleted from the QuickBooks company.

No changes

Here is the CDC response in the case where no changes have been made to the specified entities within the look-back period.

{
  "CDCResponse": [
    {
      "QueryResponse": [
        {}
      ]
    }
  ],
  "time": "2015-12-23T12:36:51.763-08:00"
}

 Got Questions? Get Answers in our developer forums.