Field Mapping: QuickBooks and Fieldclix

Modified on Fri, Jun 12 at 6:23 AM

TABLE OF CONTENTS

How QuickBooks sync works in Fieldclix
Object mapping — QuickBooks Desktop / Enterprise
Object mapping — QuickBooks Online
QuickBooks Online vs Desktop — key differences
Match keys — how records are linked
- QuickBooks Desktop
- QuickBooks Online
Sync object details
Questions & Answers

What this article covers: which QuickBooks records match Fieldclix (FCX) records, which way data flows, and how QuickBooks Desktop differs from QuickBooks Online (QBO).

How QuickBooks sync works in Fieldclix

Fieldclix connects through a connector service (Web Connector on Desktop, cloud API on QBO) that keeps selected records in sync.

One QuickBooks company, one FCX instance. Synced objects are usually not tied to a specific Our Company unless filters are configured.

Sync order:

Base records — employees, payment terms, payroll items (Desktop), classes, GL codes
Dependent records — service items, customers, customer jobs, vendors, invoices, bills, timesheets (Desktop), cost rates (Desktop)

Product	Connection
QuickBooks Desktop	Web Connector + company file
QuickBooks Online	Cloud API (OAuth)

Direction key: ⇨ into FCX | ⇦ out of FCX | ⇦⇨ both ways

Object mapping — QuickBooks Desktop / Enterprise

QuickBooks Desktop	Direction	FCX
Employees	⇨	Employees
Terms List	⇨	Payment Terms
Class List	⇨	Classes
Chart of Accounts	⇨	GL Codes
Customers	⇦⇨	Customers
Customer Job Types	⇨	Projects
Customer Jobs	⇦⇨	Customer Jobs
Sales Rep List	⇨	Sales Rep
Vendors	⇦⇨	Vendors
Invoices	⇦⇨	CIM Invoices
Bills / Check / CC Charge	⇦⇨	VIM Invoices
Payroll Items List	⇨	Payroll Items
Items List (service)	⇨	Service Items
Payroll Summary Reports	⇨	Cost Rates
Timesheet	⇦	Payroll TC Data
Item List (sales tax)	⇨	Sales Tax Items

Object mapping — QuickBooks Online

QuickBooks Online	Direction	FCX
Employees	⇨	Employees
Terms List	⇨	Payment Terms
Class List	⇨	Classes
Chart of Accounts	⇨	GL Codes
Customers	⇦⇨	Customers
Customer Jobs (sub-customers)	⇦⇨	Customer Jobs
Projects	⇦⇨	Build Plans
Vendors	⇨	Vendors
Invoices	⇦⇨	CIM Invoices
Bills / Purchases (COD)	⇦⇨	VIM Invoices
Items List (service)	⇨	Service Items
Tax Codes	⇨	Sales Tax Items
Payroll Items / Timesheets / Sales Reps	Not synced	—

QuickBooks Online vs Desktop — key differences

Topic	Desktop	QBO
Connection	Web Connector + company file	Cloud API (OAuth)
Vendors	Two-way	Into FCX only
Sales reps	QB → FCX	Not available
Projects / jobs	Job Types → Projects; Customer Jobs ↔ FCX	QBO Projects ↔ Build Plans; Customer Jobs separate
Payroll items	QB → FCX	Not synced
Timesheets	FCX → QB	Not synced
Cost rates	Payroll Summary → FCX	Not synced
PTO / sick on employee	Supported	Not supported (API)
COD	Credit Card Charges / Checks	Purchases / Expenses
Sales tax source	Sales Tax Items	Tax Codes (groups)

Match keys — how records are linked

1) External link (QB ListID / QBO Id) — used after first match.

2) Business key — only when no link exists, among unlinked FCX records only.

QuickBooks Desktop

FCX	QB	Match key
Employees	Employees	Account Number = Employee ID
Payment Terms	Standard / Date-Driven	Name + Due In set (standard) or empty (date-driven)
Payroll Items	Wage / Non-Wage	Name + Is Wage flag
Classes	Class List	Full Name = Name
GL Codes	Accounts	Account Number = Number; fallback: Number · Name
Service Items	Service Items	Full Name = Name
Sales Tax Items	Sales Tax Item	Name
Sales Rep	Sales Rep List	Initial = Name / Initials
Projects	Job Types	Full Name = Name
Customers	Customers	Name
Customer Jobs	Customer Jobs	Customer + Parent Job + Name
Vendors	Vendors	Name
CIM / VIM	Invoices / Bills	QB→FCX: TxnID link; FCX→QB: no link yet
Timesheets / Cost Rates	Time Tracking / Payroll Summary	Payroll check + employee link; item Name for cost rates

QuickBooks Online

FCX	QBO	Match key
Employees	Employee	Employee Number = Employee ID
Payment Terms	Term	Name
Classes	Class	Fully Qualified Name = Name
GL Codes	Account	AcctNum = Number
Service Items	Item	Fully Qualified Name = Name
Sales Tax Items	Tax Code (group)	Name
Customers	Customer (Job=false)	Display Name = Name
Customer Jobs	Customer (Job=true)	Display Name = Name + ParentRef
Build Plans	Project	Project Name = Build Plan Name
Vendors	Vendor	Display Name = Name
CIM / VIM	Invoice / Bill / Purchase	QBO→FCX: Id link; FCX→QBO: no link yet

Sync object details

Each section covers both Desktop and QBO. Columns show where the products differ; “—” means not available. Optional fields depend on connector settings.

Employees (QB → FCX)

Important notes

Direction: QB → FCX only. QB is the HR source; FCX edits do not go back.
Desktop match key: Account Number = Employee ID. QBO: Employee Number = Employee ID.
Desktop only: supervisor, job title, department, class, PTO/sick balances.
QBO only on create: default category, payroll period type, payroll state.
Both (optional): home location from address when HomeLocationTypeId is set.

QB Desktop field	QBO field	Direction	FCX field	Notes
Account Number	Employee Number	⇨	Employee ID	Match key; both required
First / Middle / Last Name	Given Name / Family Name		First / Middle / Last Name	QBO: no Middle Name
Birth Date, Gender	Birth Date, Gender		Birth Date, Gender	QBO: if specified
Sick / Vacation hours (Payroll Info)	—		Sick / Vacation hours	Desktop only
Phone (configurable QB field)	Primary / Mobile / Alt / Fax phone		Phone	Optional: `EmployeeFieldForPhone` / `SyncPhone`
Email (configurable QB field)	Primary Email		Email	Optional: `EmployeeFieldForEmail` / `SyncEmail`
Supervisor Ref	—		Supervisor	Optional: `SyncSupervisors`; Desktop
Job Title	—		Position (Job Title)	Optional: `SyncJobTitles`; Desktop
Department	—		Department	Optional: `SyncDepartments`; Desktop
Class (Payroll Info)	—		Class	Optional: `SyncEmployeeClass`; Desktop
Employee Address	Primary Address		Home Location address	Optional: `HomeLocationTypeId`
—	Released Date		Is Active	QBO: `CloseTerminated` / `OpenActive`
—	—		Category, Payroll Period, State	QBO: set on new employee only

Payment Terms (QB → FCX)

Important notes

Direction: QB → FCX only. Terms are created in QuickBooks.
Desktop: standard and date-driven types matched separately by Name + Due In flag.
QBO: standard terms use Due Days; date-driven use Day of Month / Days Next Month.

QB Desktop field	QBO field	Direction	FCX field	Notes
Name	Name	⇨	Name	Match key
Is Active	Active		Is Active
Std Due Days	Due Days (STANDARD type)		Due In	Standard terms
Day of Month Due / Due Next Month Days	Day of Month Due / Due Next Month Days		Due Day of Month / Days Next Month	Date-driven terms

Payroll Items

Important notes

Desktop only. Required for timesheet and cost rate sync.
Direction: QB → FCX. Wage and non-wage items matched separately by Name + Is Wage.
Wage subtypes set sick/vacation flags on FCX payroll items.

QB Desktop field	QBO field	Direction	FCX field	Notes
Name	—	⇨	Name	Match key + wage flag
Is Active	—		Is Active
Wage Type / Non-Wage Type	—		Item Type, Is Wage
Wage subtype	—		Is Sick / Is Vacation	Wage items only

Classes (QB → FCX)

Important notes

Direction: QB → FCX only.
Hierarchy synced by sublevel; parent must exist first.
Used on invoices, bills, timesheets, customer jobs (optional), service items.

QB Desktop field	QBO field	Direction	FCX field	Notes
Full Name	Fully Qualified Name	⇨	Name	Match key
Name	Name		Short Name
Sublevel	Level (from FQN)		Level
Parent Ref	Parent Ref		Parent Class
Is Active	Active		Is Active

GL Codes (Chart of Accounts)

Important notes

Direction: QB → FCX only.
Desktop match: Account Number first; fallback to Number · Name if QB number is blank.
QBO: syncs filtered account types (Income, Expense, COGS, etc.); match by AcctNum.
Default AR/AP accounts used on invoice and bill push via AccountReceivableId / AccountPayableId.

QB Desktop field	QBO field	Direction	FCX field	Notes
Account Number	AcctNum	⇨	Number	Primary match key
Account Number + Name	AcctNum + Name / FQN		Name	Desktop fallback if no number
Desc	Description		Description
Account Type	Account Type		Type
Parent Ref	Parent Ref		Parent GL Code
Is Active	Active		Is Active

Service Items

Important notes

Direction: QB → FCX. Depends on Classes and GL Codes.
Hierarchy synced by sublevel; parent processed first.
Income account (sales+purchase) or expense account (sales or purchase only) mapped to FCX GL.
Used on CIM invoice lines, VIM bill lines (optional), Desktop timesheets (optional).

QB Desktop field	QBO field	Direction	FCX field	Notes
Full Name	Fully Qualified Name	⇨	Name	Match key
Name	Name		Short Name
Sublevel	Level		Level
Parent Ref	Parent Ref		Parent Item
Class Ref	Class Ref		Class	QBO: if classes enabled
Income / Expense Account Ref	Income / Expense Account Ref		GL Account
Is Active	Active		Is Active

Sales Tax Items

Important notes

Direction: QB → FCX only.
Desktop: Sales Tax Items from Item List.
QBO: Tax Code groups only (single TAX/NON codes skipped). Purchase rate also synced.
Used on CIM invoices and VIM bills when tax codes enabled.

QB Desktop field	QBO field	Direction	FCX field	Notes
Name	Name	⇨	Name	Match key
Tax Rate	Sales tax rates (avg)		Rate	QBO: from TaxRate list
—	Purchase tax rates (avg)		Purchase Rate	QBO only
Is Active	Active		Is Active

Sales Reps

Important notes

Desktop only. Not available in QBO connector.
Direction: QB → FCX. Linked to Employee or Vendor via SalesRepEntityRef.
Optional on Customer Jobs when SalesRepUsed is enabled.

QB Desktop field	QBO field	Direction	FCX field	Notes
Initial	—	⇨	Name, Initials	Match key
Sales Rep Entity Ref	—		Employee or Vendor	Must link to synced employee/vendor
Is Active	—		Is Active

Projects and Build Plans

Important notes

Desktop: Customer Job Types → FCX Projects. QB → FCX; new FCX projects can push to QB as Job Types.
QBO: QBO Projects ↔ FCX Build Plans (GraphQL API). Customer Jobs remain separate sub-customers.
QBO invoices/bills can reference Build Plan as Project when UseProjects is enabled.

QB Desktop field	QBO field	Direction	FCX field	Notes
Full Name (Job Type)	Project Name	⇨	Project Name / Build Plan Name	Match key
Is Active	Status	⇨	Is Active	QBO: In Progress / Complete
Name (Job Type Add)	—	⇦	Project Name	Desktop: new projects to QB
—	Name, Description	⇦⇨	Build Plan Name, Description	QBO ProjectsToQbo flow
—	Customer Ref	⇦⇨	Build Plan Customer	QBO only
—	Site Address	⇦⇨	Build Plan Site Address	QBO only

Customers

Important notes

Direction: two-way on Desktop; QBO uses separate From/To flows.
Desktop match: Name. QBO match: Display Name.
FCX → QB: only customers without link yet.
Addresses: street lines, city, state, ZIP, country on both bill and ship.

QB Desktop field	QBO field	Direction	FCX field	Notes
Name	Display Name	⇦⇨	Name	Match key
Account Number	AcctNum	⇦⇨	Account Number
Customer Type Ref	Customer Type Ref	⇨	Category
Terms Ref	Sales Term Ref	⇦⇨	Payment Term
Bill Address / Ship Address	BillAddr / ShipAddr	⇦⇨	Billing / Shipping Address
Company Name	Company Name	⇨	Print Name	QBO From only
Is Active	Active	⇦⇨	Is Active

Customer Jobs

Important notes

Direction: two-way on both products (separate flows on QBO).
Match key: Customer + Parent Job + Name (Desktop); Display Name + ParentRef (QBO).
Desktop optional: Class (UseClassForCustomerJobs), Job Type/Project (UseJobTypesForCustomerJobs), Sales Rep (SalesRepUsed).
Desktop FCX → QB: job status In Progress; optional custom DataExt from stored procedure.
QBO FCX → QBO: sub-customer with Job flag; filtered by Build Plan instance.

QB Desktop field	QBO field	Direction	FCX field	Notes
Name	Display Name	⇦⇨	Name	Part of match key
Parent Ref	Parent Ref	⇦⇨	Customer / Parent Job	Part of match key
Sublevel	Level	⇨	Level
Class Ref	—	⇦⇨	Class	Desktop optional
Job Type Ref	—	⇨	Project	Desktop optional
Sales Rep Ref	—	⇦⇨	Sales Rep	Desktop optional
Ship Address	—	⇦⇨	Shipping Address	Desktop
Job Status / Job Desc	Job Info (Description, Status)	⇦	Name	FCX → QB on create
Is Active	Active	⇦⇨	Is Active	Desktop From
DataExt (custom fields)	—	⇦	Custom SP fields	Desktop optional SP

Vendors

Important notes

Desktop: two-way. QBO: into FCX only (no push to QBO).
Desktop match: Name. QBO match: Display Name.
Required for VIM bills and COD documents.

QB Desktop field	QBO field	Direction	FCX field	Notes
Name	Display Name	⇦⇨ / ⇨	Name	Match key; QBO inbound only
Account Number	AcctNum	⇦⇨ / ⇨	Account Number
Vendor Type Ref	—	⇨	Category	Desktop From
Terms Ref	Term Ref	⇦⇨ / ⇨	Payment Term
Vendor Address / Ship Address	BillAddr / ShipAddr	⇦⇨ / ⇨	Billing / Shipping Address
Is Active	Active	⇦⇨ / ⇨	Is Active

CIM Invoices

Important notes

FCX → QB: Stage = Submitted; allocation lines required; no existing link.
QB → FCX: paid status only; matched by TxnID / QBO Id link (must exist from prior push).
Desktop: customer or customer job on header; sales tax item on header.
QBO extras: Project (Build Plan), Department, Custom Fields, Tax Codes on lines.
Optional: UseCustomerJobForInvoices / Invoices.UseCustomerJobs, UseClassesForInvoices.

QB Desktop field	QBO field	Direction	FCX field	Notes
Linked payments / Credit Memo	Linked Payment transactions	⇨	Stage (Paid / Rejected), Paid Date	QB → FCX
Ref Number	Doc Number	⇦	Number	FCX → QB header
Txn Date / Due Date	TxnDate / DueDate	⇦	Date / Due Date	FCX → QB
PO Number	PO Number / Custom Field	⇦	PO Name	QBO: custom field optional
Memo	Customer Memo	⇦	Memo
Customer Ref / Customer Job Ref	Customer Ref / Project Ref	⇦	Customer / Customer Job / Build Plan	Optional flags
Class Ref	Class Ref / Department Ref	⇦	Class	QBO: department optional
Terms Ref	Sales Term Ref	⇦	Payment Term
Item Sales Tax Ref	Tax Code (lines)	⇦	Sales Tax Item
AR Account Ref	AR Account Ref	⇦	AR GL (setting)
Bill / Ship Address	BillAddr / ShipAddr	⇦	Customer Billing / Site Address
Line: Qty, Service Date, Desc, Amount, Item, Class, Tax Code	Line: Qty, Service Date, Description, Amount, Item, Class, Tax Code	⇦	Allocation lines	FCX → QB

VIM Invoices (Bills)

Important notes

FCX → QB: Stage = Approved; allocation required; not synced as Check/CC (see COD section).
QB → FCX: payment info by TxnID / QBO Id link; may set Cancelled if paid with no payment txn.
Desktop lines: expense (GL) or service item or inventory item distribution.
QBO: Project on header; tax codes; optional document attachments.

QB Desktop field	QBO field	Direction	FCX field	Notes
Ref Number, Txn Date, Due Date, Terms	Doc Number, TxnDate, DueDate, SalesTermRef	⇨	Number, Date, Due Date, Payment Term	QB → FCX
Linked payment txns	Bill Payment transactions	⇨	Paid Amount, Paid Date, Paid By, Paid Notes	QB → FCX
Is Paid (no payments)	Balance = 0 (no payments)	⇨	Stage Cancelled	QB → FCX
Vendor Ref	Vendor Ref	⇦	Vendor	FCX → QB header
Ref Number, Txn Date, Due Date, Memo	Doc Number, TxnDate, DueDate, PrivateNote	⇦	Number, Date, Due Date, Memo
Terms Ref, AP Account Ref	SalesTermRef, AP Account Ref	⇦	Payment Term, AP GL
—	Project Ref	⇦	Build Plan (from allocation)	QBO optional
Line: GL or Item, Amount, Notes, Class, Customer Job	Line: Account or Item, Amount, Class, Customer Job, Tax Code	⇦	Allocation lines	Optional customer job per line

VIM Invoices (COD — Checks and Card Charges)

Important notes

FCX bills flagged SyncAsChecks or SyncAsCreditCardCharges at Approved stage.
Desktop: pushes as QB Check or Credit Card Charge (not Bill).
QBO: pushes as Purchase (Check, Credit Card, or Cash Expense).
Requires Card GL Code on FCX bill; bill marked Paid after push.

QB Desktop field	QBO field	Direction	FCX field	Notes
Payee Entity Ref	Entity Ref (Vendor)	⇦	Vendor
Ref Number, Txn Date, Memo	Doc Number, TxnDate, PrivateNote		Number, Date, Memo
Account Ref (bank/card GL)	Account Ref / Payment Method		Card GL Code	QBO: Cash uses payment method
Expense or Item lines	Account or Item lines		Allocation (GL or Service Item, Class, Customer Job)	Same pattern as bills
Check / Credit Card Charge	Purchase (Check / CreditCard / Cash)		SyncAsChecks / SyncAsCreditCardCharges	Document type

Timesheets (Payroll TC Data)

Important notes

Desktop only. Not available in QBO connector.
Direction: FCX → QB after payroll check is ready for sync.
Existing QB time entries for the period are deleted first, then re-added.
Optional: customer job, service item, class on lines (UseCustomerJobsForTimeSheets, etc.).

QB Desktop field	QBO field	Direction	FCX field	Notes
Txn Date	—	⇦	Payroll allocation Date
Duration (hours)	—		Hours (grouped)
Entity Ref (Employee)	—		Employee	Via employee link
Payroll Item Wage Ref	—		Payroll Item
Customer Ref (job)	—		Customer Job	Optional
Item Service Ref	—		Service Item	Optional
Class Ref	—		Class	Optional; class mapping supported
Billable Status	—		—	Billable if job + service item set

Cost Rates

Important notes

Desktop only. Imports from QB Payroll Summary Report after payroll processed in QB.
Direction: QB → FCX into payroll check Cost Rates table.
Per employee on check pay date; payroll item matched by Name.

QB Desktop field	QBO field	Direction	FCX field	Notes
Payroll Item Name (report column)	—	⇨	Payroll Item	Match by name
Hours (report column)	—		Hours
Rate (report column)	—		Rate
Amount (report column)	—		Amount
Employee (report filter)	—		Employee	Via employee link

Questions & Answers

Q: Can one FCX instance connect to more than one QuickBooks company?

A: No. Integration is one QuickBooks company per FCX instance. You choose either QuickBooks Desktop or QuickBooks Online for that company — not both at the same time for the same tenant.

Q: Who owns employee data — QuickBooks or Fieldclix?

A: QuickBooks → FCX only. QuickBooks is the HR source for synced employee fields. Changes made only in FCX on those fields do not flow back to QuickBooks and may be overwritten on the next employee sync.

Q: How does Fieldclix know which QuickBooks record matches which FCX record?

A: After the first successful match, FCX stores an external link (QuickBooks ListID on Desktop, Id on QBO). Before a link exists, matching uses business keys — for example Employee ID = Account Number (Desktop) or Employee Number (QBO), customer Name = Display Name (QBO), and similar rules per object (see Match keys).

Q: Why did my CIM invoice not push to QuickBooks?

A: Common reasons for FCX → QuickBooks:

Invoice stage is not Submitted
Allocation lines are missing or incomplete
The invoice already has an external link (only unlinked invoices are pushed from FCX)
Required references are missing (customer, payment term, GL, service item, etc.)

Q: Why did payment status not update in FCX after I paid in QuickBooks?

A: QuickBooks → FCX payment updates require an existing link from a prior FCX push (TxnID on Desktop, Id on QBO). Invoices created only in QuickBooks without that link are not matched automatically by this flow.

Q: Can we push vendors from FCX to QuickBooks Online?

A: No. On QBO, vendors sync into FCX only. Desktop supports two-way vendor sync.

Q: Why are timesheets or cost rates missing with QBO?

A: Those objects are not available in the QuickBooks Online connector. They exist only on QuickBooks Desktop (timesheets FCX → QB; cost rates from Payroll Summary QB → FCX).

Q: What is the difference between Customer Jobs and Build Plans on QBO?

A: On QBO, Customer Jobs (sub-customers) and Build Plans (mapped to QBO Projects) are separate objects with separate sync flows. Invoices and bills can optionally reference a Build Plan as a Project when projects are enabled for the tenant.

Q: Can I change sync options (which fields sync, customer job on invoice lines, etc.) myself in FCX?

Connector behavior is configured per tenant by the Fieldclix Implementation team (not self-service in the FCX UI).