Documentation Index
Fetch the complete documentation index at: https://docs.narrativebanking.com/llms.txt
Use this file to discover all available pages before exploring further.
Use this page to understand the QuickBooks connection flow, supported data, and refresh expectations.
Overview
QuickBooks lets users connect their accounting system through a hosted QuickBooks authorisation flow. After connection, Narrative SDK loads supported records during onboarding and daily refresh.What’s new in v1.5.2
QuickBooks integration was released inv1.5.2 so users can connect accounting data to Narrative SDK.
Narrative handles the QuickBooks connection behind the scenes. Tenants do not need to do their own QuickBooks setup to make the integration work.
Connected accounting data can support better financial context over time. Some downstream views may update after the data load completes rather than at the exact moment the user finishes the provider connection.
When to use QuickBooks
Use QuickBooks when you want accounting context alongside other connected data sources. Key outcomes:- a guided user connection flow from the product
- an initial accounting data load during onboarding
- repeat data refresh after the integration is active
- clearer visibility into accounting-derived context for downstream product experiences
Prerequisites
Before users connect QuickBooks, confirm:| Requirement | Why it matters | Notes |
|---|---|---|
| QuickBooks enabled for the tenant experience | Users need the QuickBooks option available before they can connect. | Narrative enables and manages the provider setup. |
| QuickBooks option visible in the product | Users need a clear place to start the accounting connection flow. | Typically surfaced in an integrations or data hub area. |
| User is signed in | The platform must associate the QuickBooks connection with the correct user. | Start the connect action only from an authenticated experience. |
| User has access to the QuickBooks company | The connecting user must be able to approve access in QuickBooks. | Exact approval options depend on the user’s QuickBooks account. |
Tenant teams do not need to create or configure their own QuickBooks app. Narrative handles the technical provider setup.
Connection flow
Start the connect action from the product UI
The signed-in user starts the QuickBooks connect flow from the product.
Redirect the user to QuickBooks authorisation
The user reviews and approves the accounting access request in the QuickBooks-hosted authorisation flow.
Complete the connection in Narrative SDK
After approval, QuickBooks returns the user to Narrative SDK and the integration state is updated.
Connection result
After authorisation, Narrative SDK returns the user to the product with a QuickBooks success or error status.- On success, the integration is marked as connected and can start loading supported accounting data.
- On error, the experience should surface a retry path and keep the previous state unchanged until the user completes a successful connection.
- return the user to the integrations or data hub screen
- refresh active integration state immediately
- show a provider-specific success or failure message
- avoid assuming the user can continue until the connection result is confirmed
Data load lifecycle
Initial load during onboarding
If QuickBooks is connected during onboarding, Narrative SDK includes it in the initial data load before later onboarding outputs are finalised.Scheduled refresh after connection
After activation, the platform runs a daily refresh for supported QuickBooks data.What this means for the product experience
- users should not expect all downstream outputs to update instantly at the exact moment of connection
- onboarding can take QuickBooks data into account when the connection exists in time for the initial load
- daily refresh improves continuity for recurring reporting and insight generation
Supported data
The current supported QuickBooks data categories for the default sync path are:- Accounts
- Customers
- Vendors
- Items
- Invoices
- Bills
- Purchases
Supported data here means the record categories included in the current QuickBooks data load. It does not mean every category appears as a first-class UI view.
Operational expectations
- Keep provider-specific messaging in your product UI.
- Refresh the integrations state after every connect attempt.
- Plan support workflows around connection errors, expired consent, or provider-side access issues.
Failure handling
| Scenario | Recommended response |
|---|---|
| User cancels or fails authorisation | Return to the integrations surface and offer a clear retry action. |
| Connection completes with error status | Surface a QuickBooks-specific message and keep the integration marked as not connected. |
| Data does not appear immediately after connection | Explain that initial and scheduled loads complete asynchronously after a successful connection. |