QuickBooks operations

Authorization and scope

Use a Carden key for the intended merchant and environment. Connection IDs are looked up within authorized context; they are not bearer credentials. Creating an invitation or queueing a sync requires integrations:write; reading sync status requires integrations:read. Only keys created for the QuickBooks integration can grant these scopes; a Stripe-integration key cannot.

QuickBooks OAuth is completed by a person on Intuit's consent screen. These operations manage that workflow and subsequent import work; they do not accept a QuickBooks password or give Carden access to Stripe.

Create a connection invitation

POST /api/v1/integrations/quickbooks/invitations

{
  "recipientEmail": "accounting@example.com",
  "expiresInHours": 48
}

The sender identity and target merchant are derived server-side from the authorized key. Caller-supplied requester names or emails are not used to establish identity. The integration environment must also match the QuickBooks environment configured for the deployment.

A successful 201 response uses object: quickbooks.connection_invitation and an invitation object containing id, organizationId, environment, organizationName, recipientEmail, expiresAt, and connectUrl. The invitation is sent to the recipient. Treat connectUrl as sensitive and expiring; avoid storing it in public logs.

Invalid request fields produce 400. Missing or inactive organization context can produce 404. An invitation email delivery failure can produce 502; configuration and other server failures can produce 500. Use the request ID when investigating delivery rather than creating a large batch of duplicate invitations.

Queue an invoice import

POST /api/v1/integrations/quickbooks/{connectionId}/sync

Replace connectionId with the existing authorized QuickBooks connection identifier. An empty body or {} requests normal sync work. An optional JSON body { "fullReconciliation": true } requests a full reconciliation rather than the normal checkpoint-based path. The value must be boolean.

Without an existing checkpoint, normal work starts with a bounded historical import. Later normal runs use the stored checkpoint for incremental refresh; a stale checkpoint can trigger full reconciliation. A connection must be active and authorized. A paused or disconnected connection must be resumed or reconnected 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 the import complete. Avoid tight retry loops or overlapping full imports.

Read the latest sync

GET /api/v1/integrations/quickbooks/{connectionId}/sync

A successful 200 response uses object: quickbooks.sync_run and data containing the latest run information. The syncRun includes its state, source-period boundary timestamps, created/start/completion timestamps, and available progress information. Preserve null timestamps for work that has not yet started or completed.

For an authorized connection with no run, data can be null. When present, data.entities lists entity-level progress with counts, cursors, and safe error summaries. A 404 indicates the connection or integration was not found in the key's scope; it is not proof that the QuickBooks company has no invoices.

1. Retain the run ID returned when queueing work.
2. Check the latest status with a modest polling interval or in integration activity.
3. When complete, review imported records and exceptions; import completion does not establish enrichment eligibility.
4. If failed, inspect the safe error and connection state, correct the cause, and retry the import operation rather than reauthorizing blindly.

Response differences and safety

QuickBooks operation errors may use a top-level string error, unlike the Stripe API's structured error object. Always branch on HTTP status, tolerate the documented envelope difference, and retain x-carden-request-id. Avoid assuming every response has api_version or an error.issues array.