Skip to main content
Glama

QuBe Sync: QuickBooks Desktop API for developers

Create time tracking

create_time_tracking
Read-onlyIdempotent

This request adds a time tracking transaction to QuickBooks, mirroring the time-tracking feature available in the QuickBooks UI. The time tracking feature allows a QuickBooks user to base payroll or invoices on time worked. You can add time-tracking information to any vendor, employee, or person on the Other Names list in QuickBooks.

The time_tracking_add wrapper from qbXML is also accepted. Returns the v2 request to send, and the webhook payload QuickBooks' answer arrives in (this operation's response_json: its data shape and the status codes to handle).

Possible errors (error.code / error.type; the call result explains each): 1030 unsupported_request, 3000 invalid_object_id, 3040 invalid_amount, 3070 string_too_long, 3120 object_not_found, 3140 invalid_reference, 3150 missing_element, 3175 in_use, 3176 locked, 3180 cannot_save, 3210 invalid_value, 3220 not_authorized, 3231 request_not_processed, 3250 feature_not_enabled, 3260 insufficient_permission, 3261 personal_data_access_denied, 3262 payroll_subscription_required, 3263 read_only_access, 3264 merchant_services_subscription_required, 3270 missing_posting_account

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "duration": "<duration>",
      "entity_ref": "<entity_ref>"
    },
    "name": "create_time_tracking"
  }
}

Input Schema

NameRequiredDescriptionDefault
rateNo
notesNoAdditional information.
durationYesTime spent doing the work. In a TimeTrackAdd request, notice that although you can specify seconds, seconds aren’t returned in the response because the UI doesn’t use seconds.
txn_dateNoThe date of the transaction. In some cases, if you leave `txn_date` out of an -Add message, QuickBooks will prefill `txn_date` with the date of the last-saved transaction of the same type.
class_refNoUse classes to categorize transactions (for example, by department, location, or work type). Class tracking is off by default in QuickBooks.
def_macroNo`def_macro` lets you assign a reusable name to a returned `txn_id` or TxnLineID so later requests can reference it with `useMacro`. This feature requires SDK 2.0+.
entity_refYesA QuickBooks “entity” is a customer, vendor, employee, or person on the QuickBooks “other names” list. Special cases to note: In a BillToPayQuery message, `entity_ref` refers to the vendor name.
request_idNoYour own label for the request, sent to QuickBooks as its qbXML `requestID` and echoed in the raw answer (`response_xml`); optional, since the answer's webhook already carries the request's `id`.
customer_refNo`customer_ref` identifies a customer or customer job. If both `full_name` and `list_id` are provided, `full_name` is ignored. In SalesReceipt and ReceivePayment, it identifies who receives credit.
external_guidNoAllows for the attachment of a user defined GUID value.
include_qbxmlNoAlso return the qbXML this compiles to, for debugging. Not part of the v2 request.
billable_statusNoThe billing status of this item line or expense line.
item_service_refNoA service item refers to services that a business charges for or purchases. Examples include specialized labor, consulting hours, and professional fees.
include_ret_elementNo
payroll_item_wage_refNoEach payroll wage item describes and names a payment scheme, for example, Regular Pay or Overtime Pay. A `payroll_item_wage_ref` aggregate refers to one of these wage items.

Output Schema

NameRequiredDescriptionDefault
urlYesReplace {connection_id} with the customer's connection.
bodyYesThe JSON body: the arguments you passed.
qbxmlNoThe qbXML it compiles to. Only with include_qbxml.
methodYes
headersYesSend with the request. Resent unchanged when no 201 came back, it answers with the request already queued.
webhookYesJSON Schema of the payload POSTed to webhook_url once QuickBooks answers, with this operation's response_json (data shape and status codes).

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

C2.8/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description asserts a write ('This request adds a time tracking transaction to QuickBooks') while annotations declare readOnlyHint=true. The later sentence that it 'returns the v2 request to send, and the webhook payload' partially reconciles this by framing the tool as a request compiler, but the headline claim still leaves an agent unable to tell whether calling it mutates QuickBooks data. That ambiguity is exactly the contradiction the annotations are supposed to resolve, so the description undercuts them rather than adding to them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded and the first paragraph is efficient, but the second paragraph degenerates into a 20-entry error-code dump that is dense and hard to scan. It is informative rather than wasteful, yet the enumeration of error.type pairs would serve better as structured output than as prose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 15-parameter nested-object tool with an output schema, the description does substantial work: it explains the v2 request/webhook response mechanism, points to response_json's shape and status codes, and enumerates the error conditions an agent must handle. The one significant gap is the unresolved read-only-versus-write framing, which is the piece an agent most needs confirmed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 87%, so the schema already explains entity_ref, class_ref, include_ret_element, and the rest. The description adds no per-parameter meaning beyond what is in the schema, though the note that the qbXML `time_tracking_add` wrapper is also accepted has some bearing on how the payload is shaped. Baseline 3 is appropriate given the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: it 'adds a time tracking transaction to QuickBooks' and explains what time tracking is used for (payroll and invoice billing based on time worked). It is clear what the tool creates, but it never distinguishes itself from the sibling update_time_tracking or find_time_trackings, so an agent must infer the boundary from the name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to call this versus update_time_tracking or find_time_trackings, and no prerequisites are given beyond the domain note that time can be attached to vendors, employees, or Other Names entries. The description only implies usage from the create semantics; an agent gets no routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources