---
title: "QuickBooks TimeActivity API Error: Fix “Invalid ProjectRef” (With Examples)"
url: "https://satvasolutions.com/blog/quickbooks-api-projectref-error-fix"
date: "2026-04-23T23:03:25-04:00"
modified: "2026-04-23T23:03:25-04:00"
author:
  name: "Chintan Prajapati"
  url: "https://satvasolutions.com"
categories:
  - "Accounting Integration"
tags:
  - "QuickBooks TimeActivity"
  - "QuickBooks TimeActivity API"
word_count: 765
reading_time: "4 min read"
summary: "TABLE OF CONTENTS


  Introduction
  Creating TimeActivity with CustomerRef
  CustomerRef vs ProjectRef
  Usage Examples
  Why It Matters
  Troubleshooting Invalid ProjectRef
  FAQ



..."
description: "QuickBooks TimeActivity not working with ProjectRef? Discover the root cause, correct setup, and working API examples to fix errors instantly."
keywords: "QuickBooks TimeActivity ProjectRef, QuickBooks TimeActivity, QuickBooks TimeActivity API"
language: "en"
schema_type: "Article"
---

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

_Published: April 23, 2026_  
_Author: Chintan Prajapati_  

![TimeActivity API flow showing CustomerRef success path and ProjectRef error path in API hub request processing workflow](https://satvasolutions.com/wp-content/uploads/2026/04/timeactivity-api-flow-customerref-success-projectref-error-workflow-768x609.webp)

## 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](https://satvasolutions.com/wp-content/uploads/2026/04/quickbooks-api-customerref-vs-projectref-invoice-success-error-comparison.webp)

## 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**](https://satvasolutions.com/accounting-automation) where incorrect references can break data synchronization. This is especially critical in [automation for accounting firms](https://satvasolutions.com/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](https://satvasolutions.com/wp-content/uploads/2026/04/quickbooks-invalid-projectref-causes-mapping-links-data-flags.webp)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](https://developer.intuit.com/app/developer/qbo/docs/api-reference/qbo/timeactivity))

Issues like this are common in complex [financial systems integrations](https://satvasolutions.com/accounting-integration-for-financial-services), 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

<dl class="faq-list"><dt class="faq-question">Why am I getting “Invalid ProjectRef” even though the project ID exists?</dt><dd class="faq-answer">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.</dd><dt class="faq-question">Can I use CustomerRef instead of ProjectRef for time tracking?</dt><dd class="faq-answer">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.</dd><dt class="faq-question">How do I check if a customer is set up as a project?</dt><dd class="faq-answer">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`.</dd><dt class="faq-question">Should I create projects via the API or the QuickBooks UI?</dt><dd class="faq-answer">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.</dd></dl>


---

_View the original post at: [https://satvasolutions.com/blog/quickbooks-api-projectref-error-fix](https://satvasolutions.com/blog/quickbooks-api-projectref-error-fix)_  
_Served as markdown by [Third Audience](https://github.com/third-audience) v3.5.4_  
_Generated: 2026-04-24 03:03:26 UTC_