Change data capture operation

Use the change data capture operation (also known as CDC) to see which API entities and what data changed within a certain timeframe. This lets you track recent changes made by your app or QuickBooks Online users.

Use the CDC operation to poll Intuit’s data services. This returns the full payload for entities that changed within the specified “look-back” period.

CDC operations can track changes within the last 30 days.

Server responses can handle a maximum of 1,000 objects. We suggest you query for shorter time periods. This ensures all data changes are captured in the server response.

You can use the CDC operation for all API entities except the following:

• JournalCode
• TaxAgency
• TimeActivity
• TaxCode
• TaxRate

Use a GET operation and the following parameter:

The content type for the request should be text/plain.

Include all the API entities you need to review and the “look-back” date for the changes.

Replace the following in the request:

The server response only lists entities that changed since the “look-back” date.

Deleted entities return a Deleted value for the status field.

Learn more about the change data capture operation.

Let’s say your app needs to synchronize with QuickBooks Online for every hour. The last refresh was on December 23, 2015, at 9:00, PST (2015-12-23T09:00-07:00).

Specifically, your app needs to refresh its local data for the following API entities:

• Estimate
• Customer

Since then, a QuickBooks Online customer has:

• Updated two Estimate entities
• Deleted one Estimate entity
• Updated two Customer entities

To check for changes, your app sends a GET request at 10:00 AM (one hour after the last refresh):

The server response includes full payloads for the two Customer and two Estimate objects.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

{
    "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"
}

Both were modified (i.e. LastUpdatedTime field) between 9:00 and 10:00 PST.

Your app should make updates to its local database based on the CDC response. In this case, it should:

• Refresh local storage for Customer entities with id 63 and 99.
• Refresh local storage for Estimate entities with id 34 and 123.
• Remove the Estimate entity with id 979 from local storage, or mark this entity as “Deleted”.

If there were no changes since the last refresh, the server will send a mostly blank response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

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

Set up your app so it updates its local database based on the CDC response and always gets the most current data.