How does QuickBooks account mapping work in Luminous, including customer account mapping and per-channel income account mapping?

Overview

Luminous connects to QuickBooks Online (QBO) through several layers of account mapping. Understanding each layer helps ensure invoices post to the correct General Ledger accounts and that customer records are matched correctly in QBO.

There are three distinct mapping areas:

1. Global GL Account Mappings — four required accounts that apply to every transaction
2. Customer Account Mapping — how Luminous finds or creates a customer record in QBO
3. Per-Channel Income (Revenue) Account Mapping — overrides the income account on a channel-by-channel basis

---

1. Global GL Account Mappings

These are configured once and apply to all synced invoices and purchase orders unless overridden.

Where to find it: Settings (user menu, top right) → QuickBooks → Account Mappings tab

You must set four accounts:

Field	Purpose
Asset Account	Used for inventory-related assets
Expense Account	Applied to expense lines (e.g. cost of goods)
Income Account	Default income/revenue account for invoice lines
AP Account	Accounts Payable account used for purchase order syncing

To populate the dropdown options: Click Pull Accounts on the QuickBooks Connection tab. This fetches the latest chart of accounts from your connected QBO company. Once populated, select the appropriate account for each field on the Account Mappings tab and click Save Account Mappings.

Note: These four fields are required. The form will not save if any of them is blank.

---

2. Customer Account Mapping

When Luminous pushes an invoice to QBO, it must attach it to a QBO Customer record. Luminous does not require you to manually link customers — it resolves the customer automatically using the following logic:

1. Search by Company Name — Luminous queries QBO for a Customer whose CompanyName matches the Luminous customer's company name.
2. Search by Display Name — If no match is found by Company Name, Luminous repeats the search using DisplayName.
3. Create if not found — If neither search returns a result, Luminous creates a new Customer record in QBO automatically.

Best practice: Keep company names consistent between Luminous and QBO. If the names differ, Luminous may create a duplicate customer record in QBO rather than matching the existing one.

---

3. Per-Channel Income (Revenue) Account Mapping

Luminous supports overriding the income account at the sales channel level, so invoices from different channels (e.g. Shopify, wholesale, B2B portal) can post to different revenue accounts in QBO.

Resolution order

When an invoice is synced, Luminous resolves the revenue account in this order:

1. Invoice-level selection — a revenue account set directly on the individual invoice
2. Channel default — a default revenue account configured on the sales channel
3. Global default — the system-wide default revenue account set in Invoice Settings

Setting a channel-level default revenue account

1. Go to Manage → Channels and open the channel you want to configure.
2. Click Edit.
3. Enable Create Invoice Automatically (the Invoice Settings section appears after enabling this).
4. Under Invoice Settings, select a Default Revenue Account from the dropdown.
5. Save the channel.

The revenue account dropdown only appears when you have more than one revenue account defined in your Chart of Accounts (Manage → Chart of Accounts).

Setting the global default revenue account

Go to Settings → Invoicing and select a Default Revenue Account. This is the fallback used when no invoice-level or channel-level account is set.

---

Revenue Account → QBO Item Mapping (Sync Account mode)

If you use Sync Account mode (configured under Settings → QuickBooks → Invoice Settings), each Luminous revenue account must be mapped to a specific QuickBooks Product/Service item. When an invoice syncs, the mapped QBO item is used for the line, and the SKU and product name appear in the description field.

For full setup instructions on revenue account mappings and sync mode, see: How to Set Up QuickBooks Revenue Account Mapping in Luminous

---

Summary

Mapping type	Where configured	Scope
Asset / Expense / Income / AP accounts	QB Settings → Account Mappings	All transactions (global)
Customer matching	Automatic (by company/display name)	Per invoice push
Per-channel revenue account	Channel edit form → Invoice Settings	Per sales channel
Global default revenue account	Invoice Settings	Fallback for all channels
Revenue account → QBO item	QB Settings → Invoice Settings (Sync Account mode)	Per revenue account