QuickBooks integration

Overview

The QuickBooks integration connects your Mallard Bay outfitter account to QuickBooks Online so booking-related payments and bookings you operate in Mallard Bay can align with accounting in QuickBooks. After you authorize the link through Intuit, you manage connection status, bookkeeping preferences (invoice date, deposit account), and mapping tables that tie Mallard Bay listings, pricing packages, and add-ons to QuickBooks classes and products/services.

This is distinct from Mallard Bay subscription billing: your Mallard Bay plan is billed separately from how guest bookings and Quick Pay flows flow into your QuickBooks books.

Prerequisites

• Active outfitter — QuickBooks screens require an outfitter selected. If none is chosen, you see the dashboard’s usual “please select an outfitter” empty state (QuickBooksPage uses the same pattern as other outfitter-specific pages).
• Plan access — The QuickBooks page is wrapped in a feature paywall (FeatureKey.QuickBooks). If you only see upgrade or paywall content, your subscription may not include this integration yet; Mallard Bay support can confirm entitlements (exact plan tiers are not spelled out in this app code).
• QuickBooks Online — Connection is described and implemented as QuickBooks Online (https://qbo.intuit.com for “Go to QuickBooks”).
• Data in QuickBooks for mappings — To use Class Mappings, your QuickBooks company should have classes defined; for Product and Service Mappings, it should have products and services items. Empty lists trigger in-app guidance directing you to add them in QuickBooks first.

Open QuickBooks setup

1. In the sidebar, open Integrations (/integrations).
2. Open the QuickBooks card (subtitle: “Connect QuickBooks to automate invoicing and track finances with ease.”).
3. You arrive at QuickBooks (/integrations/quick-books). What you see next depends on whether the outfitter already has an active QuickBooks connection (see below).

Connect QuickBooks or fix a broken connection

First-time or standard connect

When QuickBooks is not yet enabled—or you return after clearing the connection—you see an overview titled “Seamlessly Sync with QuickBooks Online” and primary action Connect to QuickBooks:

1. Click Connect to QuickBooks.
2. The app asks Mallard Bay for an authorization URL, then navigates your browser to Intuit to sign in and approve access.
3. After Intuit redirects you back, onboarding continues in Mallard Bay (you’ll see integration-specific UI once the backend marks the outfitter connected).

Reconnection needed

If the outfitter is flagged “needs reconnection,” Mallard Bay shows a red reconnect banner titled Your QuickBooks account needs to be reconnected with the note that you may need to manually sync data that was not synced while it was disconnected, and button Reconnect and sync data. The overview block can still appear with Connect to QuickBooks as part of the same screen.

Important: While QuickBooks is off or awaiting reconnection, you do not get the tabbed settings (account details, general settings, mappings). Complete connect/reconnect before configuring mappings.

After you disconnect

Choosing Disconnect QuickBooks on Account Details opens a confirmation: payments and bookings will no longer be synced to QuickBooks. After confirmation, Mallard Bay shows QuickBooks disconnected successfully!

Tabs when connected (four areas)

Routes live under /integrations/quick-books/...:

Landing on /integrations/quick-books alone still shows tabbed navigation; content matches the tabs above.

Account Details

Shows QuickBooks Account Details:

• Company name and Connected user
• Integration status: Active (green pill) when viewing this connected state
• Go to QuickBooks opens QuickBooks Online in a new context
• Disconnect QuickBooks (see disconnect copy above)

Banners link to Mallard Bay help for syncing issues (“Having trouble syncing your data to QuickBooks?”).

General Settings

Two outfitter-wide settings persist through integration settings (changes save via the dashboard; you should see feedback like Successfully updated setting!):

1. Invoice date — Subtitle: Select which timestamp you would like to use as your invoice date. Options correspond to Mallard Bay booking timestamps displayed as plain English labels derived from BOOKING_APPROVAL_DATE, BOOKING_DATE, TRIP_START_DATE (Booking approval date, Booking date, Trip start date in the picker).
2. Deposit Settings → Deposit account — Subtitle: Select which account the funds are being sent to. The list is populated from QuickBooks deposit accounts fetched for your linked company.

Knowledge-base prompts on this tab (“Need help setting up QuickBooks?”) point back to Mallard Bay documentation.

Class Mappings

• Table-style layout: columns Listing and QuickBooks Class (QuickBooks Class may stack on narrow screens).
• Rows are ordering from Mallard Bay’s listing_order metadata.
• Each row maps one listing to a QuickBooks class. You can clear a mapping via the dashboard’s shared None / unselect behavior.
• Saving shows Successfully updated the class mapping!

If QuickBooks returns no classes, the screen shows No QuickBooks classes defined and explains to add classes in QuickBooks first.

Product and Service Mappings

Requires QuickBooks products and services; otherwise No QuickBooks products and services defined with instructions to add items in QuickBooks.

When items exist:

1. Default product or service — Optional outfitter-level QuickBooks item; can be cleared (set to None).
2. Listings — Only published listings appear. Each listing is a collapsible card titled “<Listing title> – Pricing packages”. Expanding a row loads that listing’s pricing package ↔ QuickBooks item mappings on demand. Each package has a Select product or service control.
3. Add-ons — Each add-on has its own Select product or service row.

Successful updates show Successfully updated the product or service mapping!

How this fits other Mallard Bay workflows

• Bookings and payments — Disconnect messaging explicitly names payments and bookings as no longer syncing. Keep Mallard Bay booking and payment data accurate so whatever your backend sends to QuickBooks stays aligned with operations.
• Quick Pay — If QuickBooks is enabled for the outfitter, Quick Pay shows that name and email are required for quick pay transactions to be synced to QuickBooks; validation enforces those fields (phone remains optional in that rule set).
• Listings — Class mappings consider listing rows returned from the mapping API; product/service mapping’s listings list is published-only in the UI.
• Reports — Mallard Bay Reports remain in-dashboard views; formal accounting after sync lives in QuickBooks Online unless your process says otherwise.
• Other integrations — Calendar, Meta, SMS, custom email, website widget, etc., are separate Integrations cards and do not replace QuickBooks setup.

Common pitfalls

• Paywall instead of setup — If you never reach the connect screen, this is often plan gating, not bad Intuit credentials.
• Reconnect state — Until reconnection completes, you cannot open mapping tabs; expect possible gaps in synced data while disconnected (per in-app copy).
• Empty QuickBooks classes or items — Mapping screens stay empty or blocked until you create the underlying records in QuickBooks.
• Quick Pay with QuickBooks on — Missing name or email blocks the form.
• Unpublished listings — They do not appear under Listings on Product and Service Mappings even if you sell them later; publish when you need per-package QuickBooks items.

What this codebase does not define

The dashboard implements OAuth initiation (redirect to Intuit), disconnect, company info, deposit accounts, classes/items fetch, settings updates, and mapping mutations. This repository does not document exact sync schedules, invoice/transaction shapes inside QuickBooks, refunds or voids, historical backfill, or automated retries after errors. Treat those details as backend and Intuit platform behavior—or ask Mallard Bay support when a specific booking or payment disagrees between Mallard Bay and QuickBooks.