Why am I getting "Invalid ProjectRef" even though the project ID exists?

The project may not be properly set up internally in QuickBooks. Not all sub-customers are valid projects. The entity must have Job = true and IsProject = true. Try recreating the project through the QuickBooks UI.

Can I use CustomerRef instead of ProjectRef for time tracking?

Yes. If you just need to link a TimeActivity to a customer without project-specific tracking, use CustomerRef. It works with any active customer and does not require the project flag.

How do I check if a customer is set up as a project?

Query the Customer entity via the QuickBooks API and check if Job = true and IsProject = true. If these flags are not set, the customer cannot be used with ProjectRef.

Should I create projects via the API or the QuickBooks UI?

It is recommended to create projects through the QuickBooks UI to ensure proper internal linking. Projects created via import or other methods may not be properly mapped and can cause "Invalid ProjectRef" errors.

QuickBooks TimeActivity API Error: Fix “Invalid ProjectRef” (With Examples)

April 23, 2026 4 min read

TimeActivity API flow showing CustomerRef success path and ProjectRef error path in API hub request processing workflow

QuickBooks TimeActivity API Error: Fix “Invalid ProjectRef”

When creating a TimeActivity via the QuickBooks Online API, developers commonly encounter the error “Invalid ProjectRef” even when the project ID exists.

This article explains the difference between CustomerRef and ProjectRef, why the error occurs, and how to fix it.

CustomerRef vs ProjectRef in QuickBooks API showing invoice success with CustomerRef and error with invalid ProjectRef

Creating TimeActivity in QuickBooks API (Using CustomerRef)

To create a TimeActivity linked to a customer (not a project), use the following API payload:

 {
    "NameOf": "Employee",
    "StartTime": "08:00:00",
    "EndTime": "16:00:00",
    "TxnDate": "2025-04-15",
    "BreakHours": 0,
    "BreakMinutes": 0,
    "EmployeeRef": {
        "value": "80"
    },
    "CustomerRef": {
        "value": "83"
    }
}

This works correctly when the customer ID is active and valid. The issue arises when developers try to use ProjectRef instead.

CustomerRef vs ProjectRef in QuickBooks API

Field	What It Means	When to Use It
`CustomerRef`	Refers to a Customer or Sub-Customer (normal customers, no “Project” behavior required)	Use when linking TimeActivity to a Customer (general work, no project)
`ProjectRef`	Refers to a special kind of Customer that is marked as a Project (`Job = true`, `IsProject = true`)	Use when linking TimeActivity to a Project (specific job work)

Key insight: Both CustomerRef and ProjectRef point to the Customer table behind the scenes.

However, CustomerRef works with any active customer, while ProjectRef only works with a customer that is set up as a Project. ProjectRef is a more strict, specialized form of CustomerRef.

API Examples: CustomerRef vs ProjectRef Payloads

CustomerRef Example (General Customer, No Project)

"CustomerRef": {
  "value": "1",
  "name": "Amy's Bird Sanctuary"
}

ProjectRef Example (Real Project)

"ProjectRef": {
  "value": "530614583",
  "name": "Amy's Bird Sanctuary:Redway Bridge"
}

When to Use CustomerRef vs ProjectRef

Situation	What Happens
Use CustomerRef with a Customer ID	Works if customer is active
Use ProjectRef with a Project ID	Works if project is properly set up
Use ProjectRef with a normal Customer (not a project)	Error: “Invalid ProjectRef”
Use wrong ID in either field	Error: “Invalid CustomerRef” or “Invalid ProjectRef”

These decisions become even more important when building accounting automation workflows where incorrect references can break data synchronization. This is especially critical in automation for accounting firms, where accurate time tracking directly impacts billing and reporting.

Common Causes of “Invalid ProjectRef” Error

Why invalid ProjectRef happens in QuickBooks API including mapping issues, broken links, corrupted data and missing flags

If you are receiving “Invalid ProjectRef” errors, consider the following:

When you create a Project manually in QuickBooks UI, it creates a special internal “Project” mapping.
Not all sub-customers that look like Projects are properly linked internally
Some Projects are broken if they were imported, not created properly, or corrupted.
Broken Projects must be manually fixed or recreated.
New Projects should be created inside the QuickBooks UI.

Quick Rule: CustomerRef = any Customer (works fine even if not a project). ProjectRef = only for valid Projects, must be internally linked with Job = true and IsProject = true. (TimeActivity API Reference, 2024)

Issues like this are common in complex financial systems integrations, where multiple data sources need to stay aligned.

Summary

Field	Points To	Special Notes
CustomerRef	Regular Customer (or Sub-Customer)	Any customer, no “Project” behavior required
ProjectRef	Customer that is a Project (Job = true, IsProject = true)	Must be a valid, properly linked Project

FAQ: QuickBooks TimeActivity & ProjectRef Issues

Why am I getting “Invalid ProjectRef” even though the project ID exists?: The project may not be properly set up internally in QuickBooks. Not all sub-customers are valid projects. The entity must have Job = true and IsProject = true. Try recreating the project through the QuickBooks UI.
Can I use CustomerRef instead of ProjectRef for time tracking?: Yes. If you just need to link a TimeActivity to a customer without project-specific tracking, use CustomerRef. It works with any active customer and does not require the project flag.
How do I check if a customer is set up as a project?: Query the Customer entity via the QuickBooks API and check if Job = true and IsProject = true. If these flags are not set, the customer cannot be used with ProjectRef.
Should I create projects via the API or the QuickBooks UI?: It is recommended to create projects through the QuickBooks UI to ensure proper internal linking. Projects created via import or other methods may not be properly mapped and can cause “Invalid ProjectRef” errors.