Multi-Company Support

Codeless Sync supports connecting multiple QuickBooks companies to a single CLS account. This guide explains how multi-company data works and how to query it in your database.

How It Works

When you connect multiple QuickBooks companies:

1. Each connection is separate - Each QuickBooks company has its own OAuth connection
2. Data syncs to the same table - All companies sync to the same table (e.g., quickbooks_customers)
3. Distinguished by company_id - Every synced record includes a company_id column

The company_id Field

The company_id column contains the QuickBooks Realm ID - a unique identifier for each QuickBooks company.

Where to Find Your Company ID

You can view your company ID in several places:

• CLS Dashboard - Each connection card shows the Company ID
• QuickBooks - Settings → Account and Settings → Billing & Subscription
• Database - Query the company_id column in any synced table

Database Schema

All QuickBooks tables include the company_id column:

-- Example: quickbooks_customers table
CREATE TABLE quickbooks_customers (
    id TEXT PRIMARY KEY,
    company_id TEXT NOT NULL,  -- QuickBooks Realm ID
    display_name TEXT,
    email TEXT,
    -- ... other fields
    cls_synced_at TIMESTAMPTZ NOT NULL
);

Querying Multi-Company Data

Get All Data

-- All customers across all companies
SELECT * FROM quickbooks_customers;

Filter by Company

-- Customers from a specific company
SELECT * FROM quickbooks_customers
WHERE company_id = '123456789012345';

Compare Across Companies

-- Customer count by company
SELECT company_id, COUNT(*) as customer_count
FROM quickbooks_customers
GROUP BY company_id;

Join with Company Metadata

If you maintain a companies table:

SELECT c.display_name, c.email, m.company_name
FROM quickbooks_customers c
JOIN my_companies m ON c.company_id = m.realm_id
WHERE m.company_name = 'Acme Corp';

Best Practices

1. Index the company_id Column

For better query performance:

CREATE INDEX idx_qb_customers_company
ON quickbooks_customers(company_id);

2. Use Views for Single-Company Access

If your application typically queries one company:

CREATE VIEW acme_customers AS
SELECT * FROM quickbooks_customers
WHERE company_id = '123456789012345';

3. Consider Row-Level Security

For multi-tenant applications:

-- Example Supabase RLS policy
CREATE POLICY company_isolation ON quickbooks_customers
FOR ALL USING (
    company_id IN (
        SELECT realm_id FROM user_companies
        WHERE user_id = auth.uid()
    )
);

Sync Configurations

Each sync configuration is tied to a specific connection:

• One connection = One company - Each QuickBooks OAuth connection represents one company
• Multiple configs per company - You can have separate configs for customers, invoices, etc.
• Independent schedules - Each config can have its own sync schedule

Troubleshooting

Missing company_id

If company_id is NULL:

• Verify the connection was established correctly
• Re-sync the data using a manual sync
• Check the connection status in the dashboard

Wrong Company Data

If data appears in the wrong company:

• Verify you selected the correct connection when creating the config
• Check the connection's Company ID in the dashboard
• Each config is linked to exactly one connection

Next Steps

• Database Setup - Configure your PostgreSQL database
• Configurations - Create sync configurations
• Troubleshooting - Common issues and solutions