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

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.

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"
    }
}

CustomerRef vs ProjectRef in QuickBooks API

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"
}

How to Validate ProjectRef Before Creating TimeActivity

Before using ProjectRef in the QuickBooks TimeActivity API, you should first confirm whether the selected ID belongs to a valid QuickBooks Project.

This is important because QuickBooks projects are connected to the Customer entity, but not every customer or sub-customer can be passed as a valid ProjectRef.

You can validate the project by querying the Customer entity before creating the TimeActivity.

SELECT * FROM Customer WHERE Id = 'PROJECT_ID'

After getting the response, check whether the record is active and whether it has project-related values such as Job = true and IsProject = true.

{
  "Id": "530614583",
  "DisplayName": "Amy's Bird Sanctuary:Redway Bridge",
  "Active": true,
  "Job": true,
  "IsProject": true
}

If the record does not have Job = true and IsProject = true, avoid using it inside ProjectRef. In that case, you should either use CustomerRef or recreate the project properly from the QuickBooks UI.
A simple validation process would be:

• Query the Customer entity using the project ID.
• Confirm that the record exists.
• Check whether the record is active.
• Verify that Job is set to true.
• Verify that IsProject is set to true.
• Use ProjectRef only if the record is a valid project.
• Use CustomerRef if you only need to track time against a customer.

When to Use CustomerRef vs ProjectRef

Common Causes of “Invalid ProjectRef” Error

• 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.

Summary

Quick Checklist to Fix Invalid ProjectRef in QuickBooks API

Use this checklist when the QuickBooks TimeActivity API returns an Invalid ProjectRef error:

• Confirm that the ID exists in QuickBooks.
• Check whether the record is active.
• Make sure the ID belongs to a project, not just a regular customer.
• Verify that the project has Job = true.
• Verify that the project has IsProject = true.
• Do not use ProjectRef for normal customers.
• Use CustomerRef when project-level tracking is not required.
• Recreate the project from the QuickBooks UI if the project was imported or has broken internal mapping.
• Test the same TimeActivity payload with CustomerRef to confirm whether the issue is specific to project validation.

In most cases, the fastest fix is to replace ProjectRef with CustomerRef when you only need to link time entries to a customer.

However, if your workflow requires project-level time tracking, you should first confirm that the project is properly created and mapped inside QuickBooks.

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.