QuickBooks TimeActivity API: Why Invalid ProjectRef Happens Even When the ID Exists

we're working on a QuickBooks Online API integration where we needed to create a TimeActivity.
The payload looked fine.
The project ID was available in QuickBooks.
The employee reference was correct.

But the API still returned:

Invalid ProjectRef

At first, this looks like a simple wrong ID issue.
But in this case, the ID was not the problem.
The real issue was that QuickBooks did not consider that record a valid project.
The part that is easy to miss
In QuickBooks, a project is connected to customer records, but every customer record is not a project.

The part that is easy to miss:

• In QuickBooks, a project is connected to customer records.
• But every customer record is not treated as a project.
• A normal customer works with CustomerRef, but not with ProjectRef.
• A sub-customer may work sometimes, but not always.
• A proper QuickBooks project works with both CustomerRef and ProjectRef.

So even if the ID exists, QuickBooks may still reject it inside ProjectRef.
That is why this error can be confusing.

CustomerRef and ProjectRef are not interchangeable

• Use CustomerRef when the time entry only needs to be linked to a customer.
• Use ProjectRef when the time entry must be tracked under an actual QuickBooks project.
• This sounds small, but it changes how QuickBooks validates the request.
• For normal customer-level time tracking, CustomerRef is usually enough.
• For project-level billing, reporting, or job tracking, use ProjectRef, but only after checking that the record is really marked as a project.

The check I would do first
Before changing the payload multiple times, check the Customer record for that project ID.

Use:
SELECT * FROM Customer WHERE Id = 'PROJECT_ID'

Then look for these values:
Active = true
Job = true
IsProject = true

If Job or IsProject is false, the record may exist, but it is not valid for ProjectRef.
That is usually where the error comes from.

Quick debugging note

The mistake is usually not in the TimeActivity fields.
It is usually here:
The ID exists, but the record is not project-enabled.
So instead of only checking whether the ID exists, check what type of record QuickBooks thinks it is

Common reasons for Invalid ProjectRef:

• The ID belongs to a normal customer, so CustomerRef should be used instead.
• The ID belongs to a sub-customer, but it may not be marked as a project.
• The project is inactive, so check the Active value.
• The project was imported, so project-related flags may be missing.
• If Job is false, the record is not valid for ProjectRef.
• If IsProject is false, the record is not valid for ProjectRef.
• The wrong reference field may be used, so CustomerRef may be the correct option.

Simple fix

When project-level tracking is not required, replace ProjectRef with CustomerRef.
That solves the issue in many cases.
When project-level tracking is required, validate the project first. If the record looks broken or was imported incorrectly, recreate the project from the QuickBooks UI and use the new reference.

Final takeaway
Invalid ProjectRef does not always mean the ID is wrong.
Many times, it means QuickBooks does not see that record as a valid project.
So before changing the payload again and again, check these three values:
Active
Job
IsProject

That one check can save a lot of debugging time.

Originally published on Satva Solutions:
QuickBooks TimeActivity API Error: Fix Invalid ProjectRef