Skip to main content

ACF Connector Specification — QuickBooks Online

1. Purpose​

This specification defines how the ZAYAZ Accounting Connectivity Framework (ACF) integrates with Intuit QuickBooks Online (QBO).

QuickBooks Online is treated as a cloud accounting source platform.

The preferred ZAYAZ integration uses:

  • the QuickBooks Online Accounting API for authoritative accounting records;
  • OAuth 2.0 authorization for customer access;
  • realmId for source-company identity;
  • CloudEvents webhooks for near-real-time change detection;
  • Change Data Capture (CDC) for incremental consistency and recovery;
  • periodic source reconciliation;
  • SyncToken and source metadata for revision awareness;
  • Attachable objects for accounting evidence; and
  • TrustGate for end-to-end provenance.

QuickBooks Desktop is intentionally outside this primary connector specification.

Its qbXML and QuickBooks Web Connector architecture should be treated as a separate compatibility profile if ZAYAZ later chooses to support it.

2. Why QuickBooks matters to ACF​

QuickBooks Online represents a very different end of the accounting market from SAP.

A QuickBooks company may have:

  • a relatively simple chart of accounts;
  • vendors;
  • customers;
  • bills;
  • purchases;
  • invoices;
  • items;
  • classes;
  • departments;
  • attachments; and
  • financial reports.

It may not have:

  • plants;
  • WBS structures;
  • sophisticated warehouses;
  • production orders;
  • material documents; or
  • enterprise procurement hierarchies.

The ACF architecture must work equally well for both.

That makes QuickBooks an important validation of the abstraction.

3. Source identity​

QuickBooks Online identifies a connected accounting company using:

realmId

The source namespace is therefore:

Intuit application
       ↓
Environment
       ↓
realmId
       ↓
Entity type
       ↓
Entity ID

The realmId must be mapped to:

ZAYAZ organization
       +
E-C-O Number

before accounting data enters governed processing.

4. realmId​

realmId is returned during the Intuit OAuth authorization flow.

It identifies the QuickBooks Online company to which the customer has granted access.

It is also used in API URLs.

For example:

/v3/company/{realmId}/...

The displayed company name must never replace realmId as the source identity.

5. Sandbox and production​

QuickBooks provides separate sandbox and production environments.

Their API hosts are different:

Sandbox
sandbox-quickbooks.api.intuit.com

Production
quickbooks.api.intuit.com

Credentials and authorizations are environment-specific.

A sandbox realm and production realm are separate source contexts.

6. OAuth 2.0​

QuickBooks Online uses OAuth 2.0 authorization.

The flow is:

ZAYAZ
  ↓
Intuit authorization
  ↓
customer authentication
  ↓
company authorization
  ↓
authorization code + realmId
  ↓
token exchange
  ↓
access token + refresh token

ZAYAZ never receives the customer's QuickBooks password.

7. Accounting scope​

The standard QuickBooks Online Accounting API authorization scope is:

com.intuit.quickbooks.accounting

The connector should request only scopes that are needed for the approved ZAYAZ integration.

Additional Intuit products or APIs should not automatically be included.

8. Access tokens​

QuickBooks access tokens are short-lived.

The documented access-token lifetime is approximately:

3600 seconds

or one hour.

API Hub must therefore refresh them as part of normal connector operation.

Token expiration is not an exceptional condition.

9. Refresh tokens​

Refresh tokens allow ZAYAZ to obtain new access tokens without repeatedly asking the customer to authorize the application.

ZAYAZ must always persist the latest refresh token returned by Intuit.

The token relationship is:

realmId
   +
access token
   +
refresh token

The tokens must not become detached from their associated realm.

10. Refresh-token rotation​

A refresh operation may return a new refresh token.

Therefore:

old refresh token
      ↓
refresh operation
      ↓
new access token
      +
latest refresh token

must be persisted atomically.

Using stale token state can break a previously healthy customer connection.

11. Refresh-token lifetime​

QuickBooks historically used a rolling refresh-token model in which continued use within the relevant rolling period could maintain the connection.

Intuit has added an absolute maximum lifetime.

The ACF token model should therefore understand both:

rolling token-use requirement
       +
absolute maximum token lifetime

rather than assuming a QuickBooks connection can remain authorized forever.

12. Five-year maximum authorization lifetime​

Intuit now applies a maximum five-year lifetime to refresh tokens.

For the standard QuickBooks Accounting API scope, the earliest affected tokens are expected to reach that maximum beginning in October 2028.

This makes reconnection a permanent operational requirement.

13. Reconnect workflow​

The connector must implement:

token expiry approaching
       ↓
customer notification
       ↓
ZAYAZ reconnect URL
       ↓
Intuit authorization
       ↓
new authorization
       ↓
same realm revalidated

The reconnection process must preserve historical connector identity and TrustGate lineage rather than create an unrelated new source.

14. No service-account assumption​

The standard QuickBooks Online Accounting API uses customer OAuth authorization.

ACF must not design QuickBooks as though it supports the Fortnox-style:

service account
   +
client credentials

production model.

This distinction belongs in the connector capability profile.

15. Company capability profile​

Each connected realm produces:

ACF-QUICKBOOKS-CUSTOMER-PROFILE

The profile records:

  • realm ID;
  • environment;
  • company information;
  • country/locale;
  • home currency;
  • multicurrency configuration;
  • tax configuration;
  • available features;
  • purchase-order capability;
  • inventory capability;
  • classes;
  • departments;
  • available API entities;
  • webhook coverage;
  • CDC coverage;
  • API minor version; and
  • canonical mappings.

16. API capability is not product capability​

The QuickBooks API documentation may expose an entity such as:

PurchaseOrder

while the connected QuickBooks company does not have the required feature.

Therefore:

API entity exists

does not equal:

customer capability exists

ACF must resolve both.

17. Plan- and configuration-dependent capabilities​

Capabilities such as:

  • purchase orders;
  • inventory;
  • classes;
  • departments/locations;
  • multicurrency; and
  • selected other accounting features

can depend on QuickBooks product edition or customer configuration.

These must be part of connector discovery.

18. Accounting API​

The QuickBooks Online Accounting API is the authoritative source interface.

The API family is versioned under:

v3

and business entities are normally addressed under:

/v3/company/{realmId}/...

19. Minor versions​

QuickBooks also evolves its Accounting API through:

minorversion

The connector must therefore distinguish:

ACF connector version

from:

QuickBooks API generation

and:

QuickBooks minor version

All three are separate governance concepts.

20. API contract tracking​

The customer profile should record the minor version used in production.

A provider API update can then trigger:

minor-version change
        ↓
mapping review
        ↓
compatibility validation
        ↓
production acceptance

rather than silently changing source behavior.

21. Source object identity​

Most QuickBooks entities expose:

Id

as their source identity.

This value must be retained.

For example:

realmId
   +
Vendor
   +
Id

forms a source object identity.

22. SyncToken​

QuickBooks objects also expose:

SyncToken

to support concurrency control and updates.

For ACF it is additionally useful as source-revision information.

Thus:

Id

answers:

Which source object is this?

while:

SyncToken

helps answer:

Which revision/state of that source object did ZAYAZ process?

23. Source metadata​

QuickBooks entities can also expose metadata such as:

MetaData.CreateTime
MetaData.LastUpdatedTime

where applicable.

ACF should preserve these independently from:

ZAYAZ retrieval time

because source mutation time and ingestion time are different facts.

24. Source revision model​

QuickBooks therefore gives us a useful three-part source model:

SOURCE IDENTITY
Id

SOURCE REVISION
SyncToken

SOURCE MODIFICATION
MetaData.LastUpdatedTime

This should become a reusable ACF source-version pattern.

25. Query API​

QuickBooks provides a query interface for retrieving entity populations.

The query language resembles SQL, but it is not general-purpose SQL.

ACF must respect its limitations.

26. Query-language limitations​

QuickBooks query behavior has important restrictions.

For example, it does not provide generic support for:

  • arbitrary joins;
  • GROUP BY;
  • normal projections; or
  • arbitrary OR behavior comparable with SQL.

This means API Hub cannot push all canonical joining into QuickBooks.

Some joins must occur in the governed ACF canonical layer.

27. Query pagination​

A QuickBooks query can use:

STARTPOSITION
MAXRESULTS

The default result population is smaller than the maximum.

The connector must explicitly paginate.

No collection response may be assumed complete simply because the API request succeeded.

28. Maximum query result page​

QuickBooks queries can return up to approximately:

1000 entities

per response.

Larger populations must be retrieved in chunks.

This makes source pagination a mandatory connector function.

29. Stable retrieval​

The connector should avoid relying on source ordering assumptions.

For incremental processing, use:

  • CDC;
  • source modification metadata where appropriate;
  • transaction dates where appropriate; and
  • deterministic local identity processing.

The entity Id should not be treated as a universal chronological ordering key.

30. Change Data Capture​

QuickBooks provides a dedicated Change Data Capture operation.

CDC returns objects that have changed since a supplied timestamp.

The conceptual request is:

realm
  +
entity list
  +
changedSince

and the response contains matching changed source objects.

31. CDC is different from a webhook​

A webhook says:

Something changed.

CDC says:

Give me source objects that changed since this point in time.

These are separate synchronization capabilities.

32. CDC lookback​

QuickBooks CDC supports a maximum lookback of:

30 days

This creates a bounded recovery window.

ZAYAZ must track its CDC watermark.

33. Daily CDC​

A strong production pattern is:

Webhooks
   ↓
near-real-time freshness

CDC
   ↓
daily consistency

Periodic reconciliation
   ↓
completeness assurance

Intuit itself recommends using CDC to recover from missed webhook activity.

34. CDC recovery risk​

If the last reliable synchronization is more than 30 days old:

CDC alone

is no longer sufficient for complete recovery.

The connector must perform:

authoritative entity queries
        or
full reconciliation

depending on the affected source domains.

35. CloudEvents webhooks​

QuickBooks has moved its webhook infrastructure to the CloudEvents 1.0 format.

New ZAYAZ development should implement this format directly.

Legacy webhook payload compatibility should not define the production connector.

36. CloudEvent structure​

A QuickBooks event can include fields such as:

specversion
id
source
type
time
intuitentityid
intuitaccountid

The event type can encode entity and operation semantics, for example:

qbo.customer.created.v1

37. intuitaccountid​

In the CloudEvents format:

intuitaccountid

identifies the QuickBooks company.

This corresponds to the realm/company context required by ACF.

The event must therefore resolve:

intuitaccountid
       ↓
ACF-QUICKBOOKS-CUSTOMER-PROFILE
       ↓
ZAYAZ organization
       ↓
E-C-O Number

before processing.

38. intuitentityid​

The CloudEvent also provides:

intuitentityid

for the changed business object.

The event can therefore trigger:

realm
   +
entity type
   +
entity ID
      ↓
Accounting API reread

39. Webhook signature validation​

QuickBooks webhook requests must be authenticated.

ZAYAZ should validate:

intuit-signature

using the configured webhook verifier token and the unmodified raw request payload.

The signature validation occurs before semantic processing.

40. Durable event processing​

The correct processing pattern is:

CloudEvent
    ↓
signature validation
    ↓
realm resolution
    ↓
durable queue
    ↓
idempotency check
    ↓
authoritative API reread
    ↓
canonical processing

Complex processing should not occur in the HTTP receiver.

41. Webhooks do not establish completeness​

Webhook delivery must never become the only source synchronization mechanism.

The full production architecture uses:

webhooks
   +
CDC
   +
reconciliation

This is now a recurring ACF pattern across several providers.

42. Event lineage​

TrustGate should preserve:

CloudEvent ID
    +
event type
    +
event time
    +
realm
    +
entity ID

followed by:

authoritative source reread

This explains both:

Why did ZAYAZ refresh this object?

and:

What actual source state did ZAYAZ process?

43. Batch API​

QuickBooks provides a batch operation endpoint.

A batch can combine multiple operations into one HTTP request.

This can reduce network overhead.

44. Batch isolation​

Each operation inside a batch must remain independently identifiable.

Conceptually:

Batch
 ├── operation A
 ├── operation B
 ├── operation C
 └── operation D

ACF must not collapse them into one opaque source event.

45. Rate limiting​

QuickBooks applies API limits per realmId.

The current recommended production limits include controls around:

  • concurrent requests;
  • requests per minute;
  • batch requests; and
  • payloads per batch.

API Hub should maintain independent rate budgets for each realm.

46. Realm-scoped throttling​

The architecture becomes:

Realm A
   ↓
API budget A

Realm B
   ↓
API budget B

Realm C
   ↓
API budget C

A heavy synchronization for one QuickBooks company should not unnecessarily block another company's processing.

47. Adaptive throttling​

API Hub should treat:

HTTP 429

as a normal operational capacity signal.

The response is:

reduce request rate
      +
backoff
      +
jitter
      +
retry safely

not:

mark accounting data invalid

48. Accounts​

QuickBooks Account objects provide the chart of accounts.

They can carry information such as:

  • account name;
  • account type;
  • account subtype;
  • active state; and
  • source identity.

This provides the first ESG classification layer.

49. Account classification​

A QuickBooks account such as:

Utilities
Travel
Fuel
Office Supplies
Professional Services

is useful.

But account names are customer-defined.

Therefore:

account

is a source signal rather than an ESG taxonomy.

50. Vendors​

QuickBooks Vendor objects provide supplier identity.

They can support:

  • supplier spend;
  • supplier segmentation;
  • country enrichment;
  • Scope 3 screening;
  • supplier questionnaires;
  • CSDDD workflows;
  • supplier-specific evidence requests; and
  • factor resolution.

51. Vendor identity is not ESG evidence​

This distinction remains critical:

Vendor = Supplier A

does not establish:

Supplier A product footprint = X

The first is accounting identity.

The second requires sustainability evidence.

52. Bills​

Bills represent accounts-payable transactions associated with vendors.

They are particularly useful for ACF because they combine:

  • vendor;
  • financial amount;
  • date;
  • currency;
  • accounts; and
  • itemized lines where used.

This can provide a significant upgrade over account-only screening.

53. Bill lines​

QuickBooks expense transactions can contain different line semantics.

For example:

AccountBasedExpenseLineDetail

or:

ItemBasedExpenseLineDetail

This distinction should be preserved.

54. Account-based expense lines​

An account-based line may provide:

expense account
     +
amount
     +
description

This is useful for spend classification.

It normally remains DQ1 or DQ2.

55. Item-based expense lines​

An item-based line may provide:

ItemRef
Qty
UnitPrice
Amount

This is significantly more interesting for ESG.

But Qty remains only an activity candidate until its semantics are resolved.

56. Purchases​

The QuickBooks Purchase entity can represent expenses paid through mechanisms such as:

  • bank;
  • cash; or
  • credit card.

It can contain account-based or item-based expenditure lines.

This makes Purchase important for companies that do not enter every expense first as a Bill.

57. Purchases versus Bills​

The connector should not assume:

all procurement = Bill

A QuickBooks company may use:

Bills
Purchases
Credit card expenses
Checks

depending on accounting workflow.

ACF should normalize their economic meaning without losing the source transaction type.

58. Purchase orders​

QuickBooks exposes PurchaseOrder through the Accounting API.

Purchase-order lines can include:

Vendor
Item
Qty
UnitPrice
Amount

This can provide useful procurement context.

59. Purchase-order capability is conditional​

The presence of a PurchaseOrder API entity does not mean every QuickBooks customer has purchase orders enabled.

QuickBooks currently associates purchase-order functionality with particular subscription levels/features.

Therefore capability must be discovered per realm.

60. Items​

QuickBooks Items represent products and services a company buys or sells.

Relevant item types include concepts such as:

Inventory
NonInventory
Service

This distinction is highly useful for ACF.

61. Inventory Items​

An inventory item may contain:

  • income account;
  • expense account;
  • asset account;
  • quantity on hand;
  • inventory start date; and
  • tracking configuration.

This gives ACF more operational information than pure G/L accounts.

62. Services​

A service item may represent:

  • consulting;
  • installation;
  • professional services;
  • maintenance; or
  • another non-physical commercial activity.

A quantity of:

1 service item

must not be converted into physical environmental activity.

63. Non-inventory items​

Non-inventory items can still represent physical goods.

The fact that QuickBooks does not track them as inventory does not mean the underlying business object is non-physical.

Semantic mapping is required.

64. Quantity semantics​

Suppose a Bill line says:

Item: Diesel
Qty: 1,500

ZAYAZ cannot yet calculate fuel emissions.

It still needs to establish:

1,500 litres?
1,500 gallons?
1,500 units?

The source quantity is only part of the activity.

65. Semantic Activity Resolution​

QuickBooks reinforces the common ACF resolver:

SOURCE ENTITY
      ↓
LINE TYPE
      ↓
ITEM
      ↓
QUANTITY
      ↓
UNIT SEMANTICS
      ↓
ACTIVITY TYPE
      ↓
METHOD COMPATIBILITY
      ↓
FACTOR ELIGIBILITY

Only after this resolution may quantity become DQ3 activity data.

66. Example — useful item quantity​

Suppose QuickBooks contains:

Vendor: Fuel Supplier
Item: Diesel Fuel
Qty: 1,500
Description: litres

and the semantic mapping is validated.

ACF may resolve:

1,500 litres diesel
        ↓
fuel combustion method
        ↓
appropriate factor
        ↓
MICE
        ↓
tCO2e

That can supersede a spend estimate.

67. Example — unsafe interpretation​

Suppose QuickBooks instead contains:

Item: Fuel
Qty: 1
Amount: EUR 2,500

The connector must not infer:

1 litre

or:

2,500 litres

The physical quantity remains unresolved.

68. Classes​

QuickBooks Classes allow businesses to segment transactions or transaction lines.

Examples might include:

  • operating division;
  • service line;
  • project type;
  • geography; or
  • another internal business segment.

Their meaning is customer-defined.

69. Class mapping​

A mapping might be:

QuickBooks Class
"Northern Region"
       ↓
ZAYAZ semantic map
       ↓
Operating region

But ACF must not automatically interpret it as:

physical facility

or:

legal entity

without validation.

70. Departments​

QuickBooks Department entities can also represent organizational or location-style segmentation.

Potential ESG uses include:

  • business-unit allocation;
  • location allocation;
  • department footprinting; and
  • internal reporting.

Again, the customer-specific meaning must be established.

71. QuickBooks dimensions versus ACF dimensions​

QuickBooks Classes and Departments should map into a generic canonical dimensional model:

source dimension
       ↓
source value
       ↓
semantic mapping
       ↓
canonical ZAYAZ dimension

This pattern should be shared with:

  • SAP cost centers/plants;
  • Business Central dimensions;
  • e-conomic dimensions;
  • NetSuite departments/classes/locations; and
  • other ACF connectors.

72. Currency​

QuickBooks supports accounting currency information and, where configured, multicurrency.

ACF preserves:

source amount
transaction currency
exchange rate
home currency

where available.

Any ZAYAZ factor-currency conversion is a separate transformation.

73. Currency normalization​

For example:

QBO source:
NOK 100,000

ZAYAZ method:
EUR-normalized spend

Conversion:
NOK → EUR
using governed FX source

Factor:
kgCO2e / EUR

The original NOK amount remains immutable source evidence.

74. Tax​

QuickBooks tax behavior can vary by country and company configuration.

ACF must therefore avoid designing one universal tax interpretation for every realm.

Tax metadata can support:

  • net/gross normalization;
  • source validation;
  • transaction interpretation; and
  • reconciliation.

Tax is not an emissions methodology.

75. International differences​

QuickBooks Online is used in multiple markets.

Provider behavior and business fields may differ by:

  • country;
  • tax regime;
  • product availability;
  • company configuration; and
  • API capability.

The customer connector profile must therefore preserve country or locale context.

76. Attachables​

QuickBooks provides an Attachable entity.

An attachment can contain:

  • a file;
  • a note; or
  • file metadata.

Attachments can be linked to supported QuickBooks entities through an AttachableRef.

77. Attachments as evidence​

This allows:

ESG result
    ↓
MICE execution
    ↓
classified QuickBooks transaction
    ↓
Bill / Purchase / other source object
    ↓
AttachableRef
    ↓
invoice / receipt / document

This can become a strong auditor-readable evidence chain.

78. Attachments as enrichment​

A QuickBooks Bill may contain:

Vendor: Utility Company
Amount: EUR 4,500

while an attached PDF could contain:

Consumption: 12,350 kWh
Meter: ABC-123
Period: January

The accounting transaction can therefore serve as a locator for higher-quality environmental evidence.

79. Reports​

QuickBooks provides financial reports through its API.

These can be useful for:

  • profit-and-loss reconciliation;
  • balance-sheet reconciliation;
  • trial-balance checks;
  • management totals; and
  • reasonableness tests.

Reports should normally support reconciliation rather than replace transaction-level ESG lineage.

80. Financial reconciliation​

A useful pattern is:

transaction-level ACF ingestion
       ↓
canonical totals
       ↓
QuickBooks report
       ↓
reconciliation

A mismatch can trigger DaVE.

81. ESG processing model​

The source-to-result chain is:

QuickBooks
     ↓
realm registration
     ↓
source entity
     ↓
canonical mapping
     ↓
normalization
     ↓
classification
     ↓
activity resolution
     ↓
method selection
     ↓
factor resolution
     ↓
MICE
     ↓
TrustGate
     ↓
governed ESG result

82. Spend-based emissions​

QuickBooks is particularly strong for SMB spend screening.

A calculation can combine:

Account
   +
Vendor
   +
Bill
   +
Bill line
   +
Item
   +
Class
   +
Department
      ↓
classification
      ↓
spend category
      ↓
currency normalization
      ↓
factor
      ↓
tCO2e

83. Accounting hierarchy of evidence​

A useful QuickBooks evidence ladder is:

Account
   ↓
Purchase / Bill
   ↓
Vendor
   ↓
Itemized line
   ↓
Item
   ↓
Quantity
   ↓
Attachment
   ↓
External primary evidence

Each layer can strengthen interpretation.

84. Data-quality hierarchy​

ACF-DQ1 — Accounting-only estimate​

Typical source:

Account
Vendor
Amount

Suitable for:

  • screening;
  • materiality;
  • spend-based estimation.

ACF-DQ2 — Invoice/transaction-level data​

Typical source:

Bill
Purchase
Vendor
Itemized line
Item
Attachment

This usually improves classification.

ACF-DQ3 — Activity data​

A valid physical quantity and unit have been established.

The activity may originate from:

  • itemized transaction data;
  • attached invoice;
  • external operational data; or
  • other validated source evidence.

ACF-DQ4 — Supplier/item-specific data​

The environmental information relates to the actual:

  • supplier;
  • item;
  • product;
  • service; or
  • contractual relationship.

ACF-DQ5 — Verified primary data​

The primary evidence has undergone the required verification or assurance.

85. Progressive quality upgrade​

A QuickBooks calculation might evolve:

DQ1
EUR 20,000 fuel spend
       ↓
DQ2
Supplier bill + item
       ↓
DQ3
6,250 litres diesel
       ↓
DQ4
supplier-specific fuel data
       ↓
DQ5
verified primary evidence

Each prior result remains available in lineage.

86. Scope 1​

QuickBooks can identify candidate Scope 1 transactions such as:

  • fuel expenditure;
  • vehicle expenses;
  • heating fuel;
  • generator fuel; and
  • other combustion-related purchases.

But accounting transactions alone do not establish complete Scope 1 emissions.

87. Scope 2​

QuickBooks can identify:

  • electricity suppliers;
  • utility expenditure;
  • utility invoices;
  • relevant locations through mapped dimensions; and
  • attached invoices.

Actual kWh, tariff attributes and contractual instruments may require additional evidence.

88. Scope 3​

QuickBooks is well suited to initial Scope 3 screening.

Useful inputs include:

  • vendor;
  • account;
  • bill;
  • purchase;
  • item;
  • transaction amount;
  • class; and
  • department.

The method may later upgrade from spend-based to physical or supplier-specific data.

89. PEF/LCA limitations​

QuickBooks has items and quantities, but it is not generally a manufacturing ERP.

It therefore lacks the universal expectation of:

  • production orders;
  • bills of material;
  • goods movements;
  • detailed material consumption; and
  • plant-specific manufacturing activity.

PEF/LCA support is possible but should be classified as conditional.

90. SMB strength​

This limitation is also a strength of the connector architecture.

ACF must still produce trustworthy results when the source company only provides:

Vendor
Bill
Expense account
Item
Amount

The common ACF architecture cannot require SAP-level source richness.

91. Source authority progression​

For an SMB company, the authority path may therefore be:

Accounting amount
       ↓
Transaction
       ↓
Vendor
       ↓
Item
       ↓
Attachment
       ↓
External activity
       ↓
Supplier evidence

ZAYAZ progressively improves the result instead of rejecting the accounting system for being simple.

92. Historical source changes​

QuickBooks source entities can change after initial ingestion.

ACF can detect this through:

  • CloudEvents;
  • CDC;
  • SyncToken;
  • MetaData.LastUpdatedTime; and
  • reconciliation.

A material historical mutation triggers revalidation.

93. Historical mutation workflow​

QuickBooks change
      ↓
CloudEvent / CDC
      ↓
new source revision
      ↓
DaVE
      ↓
TrustGate lineage event
      ↓
affected ESG result
      ↓
revalidation
      ↓
recalculation if required

The prior ESG result remains immutable historical evidence.

94. Voids and deletions​

QuickBooks supports transaction lifecycle operations including deletion and, for some transaction types, voiding.

ACF must distinguish:

source transaction originally existed

from:

source transaction is no longer active/current

The former must not disappear from audit lineage.

95. SyncToken and audit challenge​

Suppose an auditor asks:

Why did this calculation change?

ZAYAZ should be able to answer:

QuickBooks Bill ID 245
SyncToken 2
       ↓
was previously
SyncToken 1
       ↓
source amount or classification changed
       ↓
calculation revalidated

This is more useful than merely saying:

QuickBooks was updated.

96. ZARA behavior​

ZARA should be able to explain:

  • which realm supplied the value;
  • which QuickBooks entity was used;
  • which source revision was processed;
  • whether the transaction was a Bill, Purchase or Journal Entry;
  • which vendor was involved;
  • which item was involved;
  • whether quantity qualified as physical activity;
  • whether an attachment supplied additional evidence;
  • whether the calculation came from DQ1, DQ2, DQ3, DQ4 or DQ5;
  • why an estimate was upgraded; and
  • why a calculation changed.

97. ZARA source distinction​

ZARA must distinguish:

QuickBooks-native source value

QuickBooks source revision metadata

ZAYAZ canonical mapping

ZAYAZ classification

ZAYAZ activity resolution

ZAYAZ calculation

external enrichment

These are not interchangeable evidence classes.

98. FOGE behavior​

FOGE can use validated QuickBooks data for reporting prepopulation.

For example:

Bill
  ↓
Vendor + item
  ↓
classification
  ↓
approved method
  ↓
MICE
  ↓
reporting requirement
  ↓
FOGE

If the reporting requirement needs evidence that QuickBooks does not provide, FOGE requests additional information.

99. COSE behavior​

COSE compares QuickBooks evidence with required calculation evidence.

Example:

Requirement:
diesel litres consumed

QuickBooks:
EUR 5,000 fuel purchase

Result:
physical activity missing

If an attached invoice provides:

1,420 litres

and the evidence is validated, the quality state may be upgraded.

100. DaVE behavior​

DaVE monitors:

  • OAuth health;
  • token rotation;
  • absolute token expiry;
  • customer reconnection;
  • API throttling;
  • CloudEvent signatures;
  • unknown event types;
  • CDC continuity;
  • CDC lookback risk;
  • source revision changes;
  • plan/feature changes;
  • entity mapping;
  • vendor resolution;
  • item semantics;
  • dimension semantics;
  • attachment relationships; and
  • reconciliation.

101. TrustGate behavior​

TrustGate preserves:

QuickBooks realm
      ↓
source entity
      ↓
source ID + revision
      ↓
CloudEvent / CDC reason
      ↓
canonical mapping
      ↓
classification
      ↓
activity resolution
      ↓
calculation
      ↓
reporting
      ↓
verification

102. MICE behavior​

MICE receives governed inputs including:

  • realm;
  • entity type;
  • entity ID;
  • source revision;
  • vendor;
  • item;
  • quantity;
  • activity unit;
  • amount;
  • currency;
  • class/department context;
  • classification;
  • method;
  • factor;
  • factor vintage;
  • reporting period; and
  • data-quality tier.

The source must be reproducible.

103. API Hub behavior​

API Hub owns QuickBooks-specific connectivity.

It manages:

  • OAuth;
  • refresh-token rotation;
  • reconnection;
  • realm routing;
  • rate budgets;
  • Accounting API calls;
  • queries;
  • pagination;
  • batches;
  • CloudEvents;
  • webhook signature verification;
  • CDC;
  • authoritative rereads; and
  • reconciliation.

Downstream systems should not implement Intuit-specific transport logic.

104. Accounting-partner model​

QuickBooks is particularly relevant to accounting-firm distribution.

An accounting partner may help many clients connect:

Accounting firm
       │
       ├── QBO Realm A
       ├── QBO Realm B
       ├── QBO Realm C
       └── QBO Realm D
              │
              ▼
             ACF
              │
      separate ZAYAZ contexts

Each QuickBooks company remains separately authorized and governed.

105. Realm isolation​

The accounting firm is not the source-company boundary.

Each realm maps separately:

Realm A → Organization A → E-C-O A
Realm B → Organization B → E-C-O B
Realm C → Organization C → E-C-O C

Cross-client source leakage must be technically impossible.

106. Continuous sustainability bookkeeping​

QuickBooks can support continuous ESG bookkeeping through:

QuickBooks transaction
        ↓
CloudEvent
        ↓
authoritative reread
        ↓
classification
        ↓
calculation / evidence gap
        ↓
daily CDC
        ↓
continuous ESG ledger

This is especially valuable for SMBs that otherwise perform ESG work only annually.

107. Data minimization​

The connector should retrieve only what is required for the governed sustainability purpose.

For example:

Vendor
Bill
Item
Amount
Currency
Class

does not justify retrieving unrelated:

customer contact information
employee personal data
all attachments
tax identifiers

unless they are specifically required.

                     INTUIT
                       │
                    OAuth 2.0
                       │
                       ▼
               QUICKBOOKS ONLINE
                       │
          ┌────────────┼────────────┐
          │            │            │
     Accounting     CloudEvents     CDC
        API            │            │
          │            │            │
          └────────────┼────────────┘
                       ▼
                  ZAYAZ API HUB
                       │
                realm capability
                    profile
                       │
                       ▼
                   TRUSTGATE
                       │
                       ▼
                      ACF
          ┌────────────┼────────────┐
          │            │            │
       normalize    validate     classify
          │            │            │
          └────────────┼────────────┘
                       ▼
              CANONICAL DATA MODEL
                       │
          ┌────────────┼────────────┐
          ▼            ▼            ▼
         MICE         FOGE         ZARA
                       │
                       ▼
              GOVERNED ESG DATA

Periodic reconciliation operates alongside CDC and webhook processing.

109. Quick-start implementation​

A controlled pilot should:

  1. create an Intuit Developer application;
  2. create or select a QuickBooks sandbox company;
  3. configure OAuth redirect URIs;
  4. authorize the accounting scope;
  5. capture the realmId;
  6. obtain OAuth tokens;
  7. register secure token storage;
  8. retrieve CompanyInfo;
  9. generate the customer connector profile;
  10. retrieve Accounts;
  11. retrieve Vendors;
  12. retrieve Bills and Purchases;
  13. retrieve Items;
  14. inspect Classes and Departments where configured;
  15. test query pagination;
  16. test source revision tracking;
  17. test CDC;
  18. configure CloudEvents webhooks;
  19. validate webhook signatures;
  20. test authoritative entity rereads;
  21. test Attachable evidence;
  22. perform initial ESG screening;
  23. run reconciliation; and
  24. validate TrustGate lineage.

110. Production implementation​

Production should add:

  • production Intuit credentials;
  • production OAuth redirect;
  • customer authorization;
  • realm mapping;
  • token rotation;
  • absolute token-expiry monitoring;
  • reconnect URL;
  • feature-capability profiling;
  • production CloudEvents;
  • HMAC signature validation;
  • durable event queue;
  • daily CDC;
  • CDC recovery monitoring;
  • API throttling;
  • reconciliation;
  • source revision monitoring;
  • attachment evidence;
  • TrustGate registration;
  • DaVE monitoring; and
  • governed recalculation.

111. Hybrid ESG implementation​

The strongest SMB sustainability result may combine:

QuickBooks
   │
   ├── Vendor
   ├── Bill
   ├── Item
   ├── Amount
   └── Qty
       +
Attachment
       +
Supplier portal
       +
Meter data
       +
Travel / logistics data
       +
Approved factor
       ↓
Governed ESG result

QuickBooks remains the accounting backbone.

ZAYAZ orchestrates evidence quality.

112. Limitations​

112.1 QuickBooks Online is not a manufacturing ERP​

Detailed physical material flows may not exist.

112.2 API entity availability does not guarantee customer feature availability​

Plan and configuration must be discovered.

112.3 OAuth authorization requires lifecycle management​

Connections cannot be treated as permanently authorized.

112.4 Refresh tokens have an absolute maximum lifetime​

Customer reconnection must be supported.

112.5 Webhooks are not authoritative source state​

The source entity must be reread.

112.6 CDC has a finite recovery horizon​

Recovery beyond 30 days requires broader reconciliation.

112.7 Query language is intentionally limited​

ACF must perform some canonical joining itself.

112.8 Quantity does not automatically equal physical activity​

Item and unit semantics must be validated.

112.9 Items are not environmental declarations​

Supplier/product evidence remains distinct.

112.10 Attachments do not automatically prove environmental meaning​

They are evidence objects requiring interpretation.

112.11 QuickBooks data cannot satisfy every sustainability disclosure​

Policies, governance, workforce, due-diligence and narrative requirements require other sources.

113. Connector activation gate​

A production QuickBooks connector should not activate until:

Intuit application                    PASS
Production OAuth                      PASS
OAuth state validation                PASS
realmId                               PASS
CompanyInfo                           PASS
ZAYAZ organization mapping            PASS
E-C-O Number mapping                  PASS
Token storage                         PASS
Token rotation                        PASS
Reconnect workflow                    PASS
Customer capability profile           PASS
Accounting API profile                PASS
Minor-version registration            PASS
Canonical mappings                    PASS
TrustGate registration                PASS
Initial synchronization               PASS
CDC                                   PASS
Reconciliation                        PASS
Rate controls                         PASS
Monitoring                            PASS

For CloudEvents:

CloudEvents 1.0 consumer              PASS
Verifier token                        PASS
HMAC signature verification           PASS
Realm resolution                      PASS
Durable queue                         PASS
Idempotency                           PASS
Authoritative reread                  PASS
CDC recovery                          PASS

must also pass.

114. Definition of done​

The QuickBooks Online connector is production-ready when ZAYAZ can demonstrate that it can:

  1. authorize through Intuit OAuth 2.0;
  2. validate OAuth state;
  3. receive and retain realmId;
  4. map the realm to the correct ZAYAZ organization and E-C-O Number;
  5. distinguish sandbox from production;
  6. securely store client credentials and tokens;
  7. refresh access tokens;
  8. persist the latest refresh token;
  9. monitor rolling token validity;
  10. monitor absolute refresh-token lifetime;
  11. support customer reconnection;
  12. retrieve CompanyInfo;
  13. generate the customer connector profile;
  14. distinguish API entity availability from QuickBooks feature capability;
  15. record the active API minor version;
  16. retrieve Accounts;
  17. retrieve Vendors;
  18. retrieve Bills;
  19. retrieve Purchases;
  20. retrieve PurchaseOrders where available;
  21. retrieve Items;
  22. retrieve JournalEntries;
  23. retrieve Classes where available;
  24. retrieve Departments where available;
  25. retrieve Attachables;
  26. preserve entity IDs;
  27. preserve SyncToken;
  28. preserve source modification metadata;
  29. paginate query results correctly;
  30. respect QuickBooks query-language limitations;
  31. operate within provider rate limits;
  32. batch requests safely where appropriate;
  33. consume CloudEvents 1.0;
  34. validate intuit-signature;
  35. resolve intuitaccountid;
  36. resolve intuitentityid;
  37. process events idempotently;
  38. reread authoritative source entities;
  39. execute CDC;
  40. maintain a CDC watermark;
  41. detect CDC recovery-window risk;
  42. recover from missed webhooks;
  43. reconcile source populations;
  44. detect historical accounting mutations;
  45. preserve voided/deleted source lineage;
  46. map source records into the ZAYAZ canonical model;
  47. normalize currency correctly;
  48. map supplier identities;
  49. map item semantics;
  50. map Classes and Departments;
  51. distinguish financial values from physical activity;
  52. reject unresolved quantity semantics;
  53. promote validated quantities to activity data;
  54. link Attachables through TrustGate;
  55. execute ESG screening without inventing missing activity;
  56. upgrade calculations when higher-quality evidence becomes available;
  57. preserve previous calculations and provenance;
  58. support ZARA, FOGE, MICE, COSE, DaVE and TrustGate;
  59. prevent cross-realm and cross-tenant data leakage; and
  60. reproduce any material ESG result from QuickBooks source to final output.

115. Source references​

This connector specification is based primarily on current Intuit documentation and developer materials covering:

  • QuickBooks Online Accounting API;
  • OAuth 2.0;
  • realmId;
  • OAuth token management;
  • refresh-token lifecycle changes;
  • reconnect workflows;
  • QuickBooks sandbox companies;
  • Accounting API v3;
  • minor versions;
  • query operations;
  • pagination;
  • batch operations;
  • API throttling;
  • Change Data Capture;
  • webhooks;
  • CloudEvents 1.0;
  • webhook signature validation;
  • Accounts;
  • Vendors;
  • Bills;
  • Purchases;
  • Purchase Orders;
  • Items;
  • Classes;
  • Departments;
  • Journal Entries;
  • Attachables; and
  • financial reporting APIs.

The current Intuit API contracts and the connected QuickBooks company's actual feature configuration remain authoritative for implementation.

The ACF customer connector profile must be reviewed or regenerated when material changes affect:

  • OAuth authorization;
  • refresh-token policy;
  • realm authorization;
  • company subscription;
  • company features;
  • country/locale configuration;
  • Accounting API minor versions;
  • source entities;
  • webhook payload contracts;
  • webhook entity coverage;
  • CDC coverage;
  • Items;
  • Classes;
  • Departments;
  • multicurrency;
  • tax configuration; or
  • canonical mappings.


Runtime Provider Extension​

The provider-specific runtime contract for this connector is maintained separately from the common ACF connector frontmatter.

It contains machine-actionable provider semantics that are intentionally not part of the common ACF schema, including authentication lifecycle, provider object revision semantics, change-capture constraints and provider-specific capability rules.

provider-extension.yamlGitHub ↗
schema_id: zayaz.acf.provider-extension.v1
extension_version: 1.0.0
connector_id: ACF-QUICKBOOKS
provider:
  namespace: intuit.quickbooks
  name: Intuit Inc.
  product: QuickBooks Online
runtime:
  source_contract:
    primary_api: quickbooks_online_accounting_api
    api_generation: v3
    minor_version_supported: true
  source_identity:
    company_partition_field: realmId
    eco_resolution_required: true
  object_revision:
    identity_field: Id
    revision_field: SyncToken
    modified_at_field: MetaData.LastUpdatedTime
  change_capture:
    webhook:
      supported: true
      payload_standard: cloudevents_1_0
      authoritative_payload: false
      authoritative_api_reread_required: true
    cdc:
      supported: true
      maximum_lookback_days: 30
    reconciliation:
      required: true
  capability_rules:
    product_plan_and_feature_configuration_material: true
    api_entity_presence_is_not_sufficient: true
  source_semantics:
    organizational_dimensions:
      class:
        candidate_id_class: EBU
        automatic_resolution_allowed: false
      department:
        candidate_id_class: EBU
        automatic_resolution_allowed: false
    quantity:
      source_field: Qty
      activity_status: candidate
      requires_unit_resolution: true
      requires_business_semantic_resolution: true
  evidence:
    native_object: Attachable
    supports_source_document_relationship: true
  extensions:
    oauth_lifecycle:
      model: authorization_code
      access_token_lifetime_seconds: 3600
      refresh_rotation_required: true
      refresh_rolling_use_window_days: 100
      absolute_maximum_lifetime_years: 5
    query_language:
      sql_compatible: false
    batching:
      recommended_maximum_operations_per_batch: 10
governance:
  status: active
  last_verified: 2026-08-30
  review_interval_days: 90
  change_control_required: true
  source_basis: connector_specification
GitHub RepoRequest for Change (RFC)
Last updated on by ZAYAZ