Cannabis Dispensary QuickBooks Setup

Setup in 6 steps

Cannabis dispensary QuickBooks setup is a one-time, ~5-minute flow. The six steps below get every settlement and AP payment landing in your books, with check-clearing status syncing back from QBO daily. If you only need a quick reference, read this section — the rest of the page expands each step in detail.

1. In your retailer portal, go to Settings → QuickBooks Online and click Connect to QuickBooks. Authorize on Intuit.
2. Pick your Expense Account (typically COGS) and your Bank Account (where checks draw from). Click Save Account.
3. Optional: open any Vendors → [vendor] page and set a per-vendor expense override if that vendor's spend should hit a different GL account.
4. If you ran settlements or AP payments before connecting, click Sync Historical Transactions to backfill.
5. Watch the Bookkeeper Match Health panel. If it shows missing checks, click Backfill checks and let it loop until "All caught up."
6. Done. Future settlements and AP payments push to your books on their own. Cleared status syncs back from QBO daily.

Connect your QuickBooks

Open your retailer portal, then Settings → QuickBooks Online → Connect to QuickBooks. You will be redirected to Intuit, where you authorize ShelfSpace. After authorization, you land back on the settings page with a "Connected" badge.

Pick your Expense and Bank accounts

The Expense Account dropdown lists every Expense, Cost of Goods Sold, and Other Expense account from your QBO chart of accounts. Pick the one where ShelfSpace consignment and AP charges should post — typically a Cost of Goods Sold account. We try to pre-select an account whose name contains "cost of goods" or "cogs", but verify the choice.

The Bank Account dropdown is recommended (not strictly required, but the Bookkeeper Match Health panel and bank-feed clearing only work when it is set). Pick the bank account the physical settlement and AP checks draw from. Setting this:

• Routes each Bill Payment's BankAccountRef to that account so QBO's bank feed pre-matches checks by check number plus amount.
• Enables the daily clearing-sync that flips ShelfSpace check status from Downloaded to Cleared on its own.

If you leave it blank, Bill Payments are skipped (the Bill still pushes) and you will match checks manually in QBO. Click Save Account when both are selected.

Per-vendor expense overrides (optional)

If a specific vendor's spend should post to a different GL account than your global default — for example, a non-cannabis service vendor that should hit a Services expense account instead of COGS — set it on the vendor:

1. Vendors → [vendor name], scroll to the QuickBooks section on the vendor detail page.
2. Pick the desired QBO Expense Account.
3. Save.

The override applies to that vendor's future Bills only. Already-synced Bills are not re-routed. There is also a per-payment override available when you create an AP payment — use it sparingly; the per-vendor default is usually the right place to set this.

Vendor matching

When we push our first Bill for a vendor, we search your QBO Vendors by display name (DBA first, legal name fallback) and match the first hit. If no match exists, we create a new QBO Vendor with the ShelfSpace vendor's display name.

There is no manual vendor-mapping UI on the retailer side today. If a Bill posts under the wrong QBO Vendor (this happens when you have similarly-named records like "Acme, Inc." vs. "Acme/Production Co."):

• Edit the Bill in QBO directly to repoint it.
• Email chris@shelfspace.pro if you want the cached mapping updated so future Bills go to the right vendor.

Backfill historical settlements and payments

If you connected QBO after already running settlements or AP payments, those past transactions are not yet in your QBO. Go back to Settings → QuickBooks Online and click Sync Historical Transactions. The button processes the most recent batch in one click; if you have a lot of history, click it more than once.

Each historical row creates the same Bill plus Bill Payment pair that future transactions do. If a row's accrual date falls inside a closed QBO period, we shift the TxnDate to today for you — no need to reopen anything.

What we push on each settlement

Once setup is complete, you do not need to touch anything. Per consignment settlement:

1. Settlement is approved on ShelfSpace.
2. We create a Bill in your QBO with VendorRef = the matched QBO vendor, Amount = net payout, Account = the resolved expense account (per-vendor override, then global default), and PrivateNote = ShelfSpace Settlement {id}.
3. When the settlement PDF generates and the check number is assigned, we create the matching Bill Payment (Check) with DocNumber = check number, BankAccountRef = your mapped bank account, and LinkedTxn to the Bill. The Bill's AP balance clears.
4. Both transactions are visible in your QBO instantly. The Recent Sync Activity panel shows status badges (Synced / Failed / Pending / Skipped).

What we push on each AP payment

For accounts payable (non-consignment) payments, the Bill plus Bill Payment push together at payment creation, because the check number is assigned atomically at that point. Same DocNumber rules, same expense-account hierarchy, same bank-feed clearing once the check clears.

Bookkeeper Match Health

The QuickBooks settings panel shows a Bookkeeper Match Health indicator near the top:

• {N} checks are pre-matched in QBO bank feed — Bill Payments successfully synced. When the bank feed sees these checks clear, QBO will pre-suggest the match and your bookkeeper sees the payee instantly.
• {M} missing — your bookkeeper won't see payees on these — Bills that have a check assigned in ShelfSpace but no matching Bill Payment in QBO. Click Backfill checks to push them. The button processes 50 per click and loops via a sticky toast that shows progress until everything is caught up.
• Skipped count — Bills awaiting check issuance, or Bills where the bank account is not mapped (set the bank account in step 2 to clear these).
• Failed count — pushes that hit a QBO error. Retry from the Recent Sync Activity panel below.

When Missing, Skipped, and Failed all read zero, the panel shows "All caught up."

Cleared status syncs from QBO

This is unique to the retailer side. Daily at 3am ET, our clearing-sync:

1. Reads cleared and reconciled Bill Payments from your QBO bank feed (last 90 days).
2. Matches each row to a ShelfSpace payment by DocNumber (check number) plus Amount.
3. Flips matched ShelfSpace payments from Downloaded to Cleared with the QBO clearing date.
4. Cascades the cleared status to any related purchase orders.

You do not have to do anything. As long as the bank account is mapped and your bookkeeper accepts the pre-suggested match in QBO, the ShelfSpace Cleared status catches up within 24 hours.

If a check cleared with a different DocNumber due to a manual edit in QBO, you can manually mark a payment as cleared from the payment detail screen.

Adjusting after the fact

If you need to re-route a specific past Bill, edit it directly in QBO — we will not override your manual edits.

Troubleshooting

• A row shows "Failed": click Retry. Most failures recover. Failed rows also retry every 10 minutes on their own.
• "Account Period Closed": we handle it. We retry with today's TxnDate. The DocNumber + Amount + Vendor still match for bank-feed reconciliation; only the posting date shifts. The Recent Sync Activity panel also shows a Post to Today button per row and a Post All to Today bulk action when closed-period rows exist.
• Bill posted under the wrong QBO Vendor: QBO's name match can land on a similarly-named record (e.g. "Transfer To/From Acme LLC" vs. "Acme LLC"). Edit the Bill directly in QBO to repoint it, and email Chris if you want the cached mapping updated for future Bills.
• Bookkeeper Match Health shows missing checks: click Backfill checks on the Match Health panel. The button loops through batches of 50 until missing reaches zero.
• No Bill Payments are pushing at all: check that you set a Bank Account in step 2. Without it, every Bill Payment is skipped with reason "QBO bank account not mapped." Set the bank account, then click Backfill checks to fill the gap.
• Connection expired banner: click Reconnect to QuickBooks. QBO refresh tokens expire after 100 days of inactivity. Reconnecting takes 10 seconds and resumes everything.
• Duplicate Document Number error: QBO complains when someone manually entered a Bill or Check with the same number we are pushing. Edit or delete the manual entry in QBO, then click Retry.
• Cleared status not flipping after the check cleared: the clearing-sync runs daily at 3am ET. If it has been more than 24 hours, double-check that (a) the Bank Account is mapped and (b) the QBO Bill Payment's DocNumber matches the check number on the ShelfSpace payment exactly. If they diverge, use the manual "Mark Cleared" override on the payment detail screen.

What's not covered today

• Sales tax handling — transactions push as-is; no separate tax line.
• Multi-location / class tracking — Bills push without a Location or Class reference. If you use those for departmental reporting, set them manually in QBO.
• Vendor name correction UI — today this requires a Chris-side cache update. A retailer-facing vendor mapping page is on the roadmap.

Need help with setup?

Email Chris at chris@shelfspace.pro — most retailers don't need to do any of this themselves; we handle the connection during onboarding and verify the first sync. If you have vendors on ShelfSpace asking how their side works, point them to our Cannabis Vendor QuickBooks Setup guide.