QuickBooks API
Create a QuickBooks authorization invitation, queue invoice import work, and inspect asynchronous sync status.
On this page
Authorization and scope
Use a Carden key for the intended QuickBooks integration, merchant, and environment. Creating an invitation or queueing a sync requires integrations:write; reading sync status requires integrations:read. A Stripe- or Square-integration key cannot manage QuickBooks.
Connection IDs are looked up inside authorized context and are not bearer credentials. QuickBooks OAuth is completed by a person on Intuit's consent screen; these operations never accept a QuickBooks password or authorize a payment provider.
A payment service reads imported invoices through the shared GET /api/v1/invoices resources only after an explicit same-context source link and invoices:read grant. Existing keys receive no automatic access.
Create a connection invitation
POST /api/v1/integrations/quickbooks/invitations| Field | Type | Meaning |
|---|---|---|
| recipientEmail | string, required | Email of the intended QuickBooks administrator. |
| expiresInHours | integer, optional | Invitation lifetime from 1–168 hours; default 48. |
| organizationId / environment / connectionId | strings, optional | Context assertions only; each supplied value must match the authenticated integration context. |
{
"recipientEmail": "accounting@example.com",
"expiresInHours": 48
}The sender and target merchant are derived from authorization. A successful 201 response returns quickbooks.connection_invitation with an expiring connectUrl. Treat that URL as sensitive and avoid public logs.
Invalid recognized values produce 400. Missing or inactive organization context can produce 404. A repeated email inside the 30-second cooldown produces 429 and can omit Retry-After. Delivery failures can produce 502; retain x-carden-request-id rather than creating duplicate invitations.
Queue an invoice import
POST /api/v1/integrations/quickbooks/{connectionId}/syncAn empty body or {} requests normal checkpoint-based sync work. Optional { "fullReconciliation": true } requests full reconciliation. The connection must be active and authorized; resume or reconnect a paused or disconnected source before queueing.
{
"object": "quickbooks.sync_run",
"data": {
"syncRunId": "sync_example",
"workflowRunId": "workflow_example",
"created": true
}
}created: false means existing queued or active work was reused. A 202 response establishes acceptance only. Poll status or inspect integration activity before considering records current, and avoid tight loops or overlapping full imports.
Read the latest sync
GET /api/v1/integrations/quickbooks/{connectionId}/syncA 200 response returns quickbooks.sync_run and the latest run data, including state, source-period boundaries, timestamps, progress, entity counts, cursors, and safe error summaries where available. Data can be null when an authorized connection has no run.
- Retain the sync run ID returned when queueing work.
- Check status with a modest polling interval or through integration activity.
- When complete, review rejected records and reconciliation exceptions; completion does not establish preparation eligibility.
- If failed, correct the recorded cause and retry import rather than blindly reauthorizing.
Handle response differences safely
QuickBooks management errors can use a top-level string error, unlike the structured errors used by payment APIs. Always branch on HTTP status, tolerate the documented envelope difference, and retain x-carden-request-id.