QuickBooks - Lago

Community maintained: This integration is built and maintained by the Lago community. It is not an official Lago integration.

Overview

Sync your Lago billing data to QuickBooks Online automatically using this community-maintained integration. It uses n8n as middleware to transform Lago webhooks into QuickBooks API calls — so your accounting records stay in sync with your billing, without lifting a finger.

How it works

The integration uses n8n (a workflow automation platform) as middleware between Lago and QuickBooks Online.

Bring your own n8n — This integration requires your own n8n account (self-hosted or Cloud). n8n is a third-party service with its own pricing. You are responsible for managing and paying for your instance.

What gets synced

Lago Event	QuickBooks Action	Description
`customer.created`	Create/Update Customer	Creates customer record with billing details
`customer.updated`	Update Customer	Updates existing customer information
`invoice.created`	Create Invoice	Creates invoice with line items and taxes
`invoice.one_off_created`	Create Invoice	Creates one-off invoice
`credit_note.created`	Create Credit Memo	Creates credit memo for refunds/adjustments
`invoice.payment_status_updated`	Create Payment (if succeeded)	Records successful payments
`invoice.voided`	Void Invoice	Voids invoice in QuickBooks

Key features

Auto-create customers

Creates QuickBooks customers on-the-fly when processing invoices.

Exact tax override

Uses Lago’s tax calculations instead of QuickBooks tax rates.

Duplicate prevention

Checks for existing records before creating new ones.

Item mapping

Map Lago item codes to QuickBooks products/services.

Batch processing

Handle high-volume invoice creation with concurrency control.

Retry logic

Automatic retries with exponential backoff for transient failures.

Prerequisites

Required accounts

Lago account with API and webhook endpoints access
QuickBooks Online account (Essentials, Plus, or Advanced)
n8n instance — n8n Cloud or self-hosted

QuickBooks developer setup

Create a QuickBooks Developer account
Create a new app in the Developer Portal
Note your Client ID and Client Secret
Set the OAuth2 redirect URI to https://your-n8n-instance.com/rest/oauth2-credential/callback

Technical requirements

n8n version 0.235.0 or higher
HTTPS endpoint for webhook receiver (required for production)
QuickBooks Online API access (included with QB Online subscriptions)

Installation

Deploy the n8n workflow

Import from file
Import from URL (n8n Cloud)

Download lago-quickbooks-main.json from the GitHub repository
In n8n, go to Workflows → Add workflow
Click the ⋮ menu → Import from file
Select the downloaded file and click Import

In n8n, go to Workflows → Add workflow
Click Import from URL
Enter: https://raw.githubusercontent.com/getlago/lago-quickbooks-integration/main/lago-quickbooks-main.json
Click Import

The workflow will be created with 47 nodes pre-configured.

Configure QuickBooks OAuth2 credentials

In n8n, click + → Credentials → Add credential
Search for QuickBooks OAuth2 API
Fill in the details:

Field	Value
Credential name	`QuickBooks OAuth2`
Client ID	From QuickBooks Developer Portal → Your App → Keys & credentials
Client Secret	From QuickBooks Developer Portal → Your App → Keys & credentials
Environment	`sandbox` for testing, `production` for live data
Scope	`com.intuit.quickbooks.accounting`

Click Connect my account, authorize in QuickBooks, then Save

The workflow expects the credential to be named exactly QuickBooks OAuth2. All 14 QuickBooks nodes reference it by name — use a different name and you’ll need to update each one manually.

Configure the workflow

The workflow has two configuration nodes.

HMAC Signature node

Open the Verify HMAC Signature node and edit the CONFIG object:

const CONFIG = {
  LAGO_WEBHOOK_SECRET: 'your_lago_webhook_secret_here',  // REQUIRED
  BYPASS_SIGNATURE: true,  // Set to false in production

  QB_ENVIRONMENT: 'sandbox',  // REQUIRED: 'sandbox' or 'production'
  QB_REALM_ID: 'your_quickbooks_company_id',  // REQUIRED
  QB_DEFAULT_ITEM_ID: '1',  // REQUIRED: Fallback QB Item ID
  QB_DISCOUNT_ACCOUNT_ID: '1'  // QB Account ID for discounts
};

Field	Required	Description
`LAGO_WEBHOOK_SECRET`	Yes	From Lago → Settings → Webhooks → Secret
`QB_ENVIRONMENT`	Yes	`sandbox` for testing, `production` for live
`QB_REALM_ID`	Yes	Your QuickBooks company ID (see below)
`QB_DEFAULT_ITEM_ID`	Yes	Default QuickBooks Item ID — see Item mapping
`QB_DISCOUNT_ACCOUNT_ID`	No	Account ID for discounts/credits
`BYPASS_SIGNATURE`	No	Skip signature verification (dev only)

How to find your QB_REALM_ID

Log into QuickBooks Online and look at the URL: https://app.qbo.intuit.com/app/homepage?realmId=123456789The number after realmId= is your Realm ID. Alternatively, use the API Explorer and look for CompanyInfo.Id.

How to find your QB_DEFAULT_ITEM_ID

Go to QuickBooks → Settings → Products and Services, click an item, and grab the ID from the URL: https://qbo.intuit.com/app/item?id=1 — here, the Item ID is 1.

Item Mappings Config node

Open the Item Mappings Config node and edit the MAPPINGS object:

const MAPPINGS = {
  ITEM_MAPPINGS: {
    // 'startup_plan': '5',
    // 'premium_plan': '12',
  },
  ITEM_FALLBACK_ID: '1',  // REQUIRED: Same as QB_DEFAULT_ITEM_ID

  QB_TAX_CODE_ID: '',  // REQUIRED if you charge tax

  DISCOUNT_MAPPINGS: {},
  DISCOUNT_FALLBACK_ACCOUNT_ID: '1'
};

See Item mapping and Tax mapping below for details.

Get your webhook URL

In n8n, open the workflow and click the Lago Webhook Receiver node
Copy the Production URL (e.g., https://your-n8n.com/webhook/lago-webhook)

For production, you need an HTTPS webhook URL. n8n Cloud provides this automatically. For self-hosted n8n, ensure your instance is accessible via HTTPS.

Configure Lago webhooks

In Lago, go to Settings → Webhooks → Add a webhook endpoint
Paste the n8n webhook URL from the previous step
Enable HMAC signature (strongly recommended)
Copy the Signature secret and paste it into the LAGO_WEBHOOK_SECRET field in n8n
Set BYPASS_SIGNATURE: false for production

Activate the workflow

In n8n, toggle the workflow to Active (top right). Done — the workflow is now listening for Lago webhooks.

Item mapping

Item mapping connects Lago billing items to QuickBooks products/services, so you can track revenue by product line. When Lago sends an invoice, each fee includes an item.code (e.g., "premium_plan"). The workflow looks it up in ITEM_MAPPINGS and uses the matched QuickBooks Item ID — or falls back to ITEM_FALLBACK_ID if there’s no match.

Find your QuickBooks Item IDs

Go to QuickBooks → Settings → Products and Services, click an item, and note the ID from the URL.

List your Lago item codes

In Lago, check Billable metrics and Plans for the code field on each item.

Create the mapping

Edit the Item Mappings Config node in n8n:

ITEM_MAPPINGS: {
  'startup_monthly': '10',    // QB: "Subscription Revenue"
  'premium_monthly': '10',    // QB: "Subscription Revenue"
  'api_calls': '20',          // QB: "Usage Revenue"
  'storage_gb': '20',         // QB: "Usage Revenue"
  'onboarding_fee': '30',     // QB: "Professional Services"
},
ITEM_FALLBACK_ID: '1',        // QB: "Services" (for unmapped items)

Keep it simple — You can map everything to a single QB item, group items by category, or go one-to-one. Pick the granularity that matches your accounting needs.

Tax mapping

The integration uses QuickBooks’ tax override feature — Lago’s exact tax amounts show up in QuickBooks, regardless of QB’s own tax rates. No recalculation, no rounding surprises. Under the hood:

Line items are marked TAX or NON based on Lago data
The exact tax total from Lago is set via TxnTaxDetail.TotalTax
The API uses minorversion=70 to enable the override

Find your Tax Code ID

Use the API Explorer to query:

SELECT Id, Name FROM TaxCode WHERE Active = true

Use the ID of the taxable code (e.g., "TAX" → Id: "2"), not "NON".

Set the tax code

In the Item Mappings Config node:

QB_TAX_CODE_ID: '2',  // Your taxable code ID. Leave empty if no tax.

Test it

Create a test invoice with tax in Lago and verify the exact amounts match in QuickBooks.

Troubleshooting tax issues

Tax amount doesn’t match — Verify QB_TAX_CODE_ID is set and points to a taxable code (not “NON”).QuickBooks recalculates tax — Ensure minorversion=70 is in the API URL. The workflow includes this by default — check the node settings if you’ve modified things.

Understanding the flow

Workflow architecture

Event flows

Customer Created/Updated

Deduplicates by DisplayName — updates if found, creates if not.

Invoice Created

Auto-creates missing customers and prevents duplicates by checking DocNumber.

Credit Note Created

Same flow as Invoice Created, but creates a Credit Memo in QB.

Payment Status Updated

Only succeeded creates a QB Payment. Other statuses are logged and skipped.

Invoice Voided

Error handling

Retries

All QB API calls retry up to 5 times with exponential backoff.

Rate limiting

1-second wait between API calls to stay within QB limits.

Duplicate prevention

Lookups before creation prevent duplicate records.

Missing customers

Auto-created when processing invoices or credit notes.

Monitoring — In n8n, go to Executions to view all workflow runs. Click any execution to see detailed logs per node.

Scaling

Limit	Value
Requests per minute	500
Concurrent requests	10
Per-second limit	10

For n8n self-hosted, set the concurrency limit:

N8N_CONCURRENCY_PRODUCTION_LIMIT=10

n8n Cloud manages concurrency automatically. Incoming webhooks are queued in memory (FIFO) and processed within the concurrency limit.

Scenario	Throughput	Time for 10k invoices
Default (10 concurrent)	~100/min	~100 minutes
Optimized (parallel)	~300/min	~33 minutes

For 10,000+ invoices per day, consider separating workflows, using Redis-backed queues, or reaching out at support@getlago.com.

Testing

Always test in QuickBooks Sandbox (QB_ENVIRONMENT: 'sandbox') before going to production.

Checklist

Customer sync: Create/update customer in Lago → verify in QB
Invoice creation: Create invoice in Lago → verify items and tax in QB
Credit note: Create credit note → verify credit memo in QB
Payment: Mark invoice as paid → verify payment in QB
Duplicate prevention: Send same invoice twice → only one in QB
Tax calculation: Tax amount in QB matches Lago exactly
Item mapping: Correct QB items are used

Troubleshooting

Webhook not received in n8n

Check the webhook URL in Lago settings
Verify the workflow is Active in n8n
Check n8n firewall/network settings

HMAC validation fails

Verify LAGO_WEBHOOK_SECRET matches Lago exactly
Check for extra spaces when copying the secret

QuickBooks authentication fails

Re-authorize the OAuth2 credential in n8n
Verify Client ID and Secret are correct

Tax amounts don't match

Check QB_TAX_CODE_ID is set and points to a taxable code (not “NON”)
Verify minorversion=70 is in the API URL (included by default)

Production checklist

Before going live:

QB_ENVIRONMENT set to production
BYPASS_SIGNATURE set to false
QB_REALM_ID matches your production company
Item mappings configured and tested
QB_TAX_CODE_ID configured (if using tax)
QuickBooks OAuth2 credential authorized for production
Lago webhook endpoint configured with HMAC enabled
n8n workflow set to Active
Error notifications configured (email/Slack)

Support and resources

GitHub repository

Source code, issues, and contributions.

Lago community

Join the Slack community or email success@getlago.com.

n8n documentation

Official n8n docs for workflow and hosting setup.

QuickBooks API

QuickBooks Online API reference.

Integrations

​Overview

​How it works

​What gets synced

​Key features

Auto-create customers

Exact tax override

Duplicate prevention

Item mapping

Batch processing

Retry logic

​Prerequisites

​Installation

​HMAC Signature node

​Item Mappings Config node

​Item mapping

​Tax mapping

​Understanding the flow

​Workflow architecture

​Event flows

​Error handling

Retries

Rate limiting

Duplicate prevention

Missing customers

​Scaling

​Testing

​Checklist

​Troubleshooting

​Production checklist

​Support and resources

GitHub repository

Lago community

n8n documentation

QuickBooks API

Overview

How it works

What gets synced

Key features

Prerequisites

Installation

HMAC Signature node

Item Mappings Config node

Item mapping

Tax mapping

Understanding the flow

Workflow architecture

Event flows

Error handling

Scaling

Testing

Checklist

Troubleshooting

Production checklist

Support and resources