---
name: time-entry-protocol
description: Normal Syncro billing uses add_line_item per the /syncro command; timers are an outlier path used only when Mike explicitly requests one; always confirm minutes + labor type before logging.
applies-to: syncro
---

# Syncro Time Entry Protocol

## Source of truth

The `/syncro` command (`.claude/commands/syncro.md`) is the SINGLE source of truth for
the billing mechanics — product IDs, rates, emergency and prepaid handling, the
line-item + invoice flow. Do not duplicate or contradict it here. This standard states
only the cross-cutting discipline.

## Normal billing = add_line_item

Routine labor bills directly via `POST /tickets/{id}/add_line_item` (see the /syncro
command for the exact payload, product IDs, and `price_retail` rules). This is the
standard, expected path for all normal billing. (Confirmed by Mike, 2026-06-08.)

## Timers are an OUTLIER — not the billing loop

`timer_entry → charge_timer_entry` is NOT part of normal billing. Use it ONLY when Mike
explicitly asks for a timer on a specific job. The capability stays available, but it is
never the default and routine labor is never routed through it.

When a timer IS explicitly requested:
1. `POST /tickets/{id}/timer_entry` → 2. `POST /tickets/{id}/charge_timer_entry` →
   verify the generated line item's `price_retail` (patch via `update_line_item` if wrong).
- `billable: false` is silently ignored by the API on `timer_entry` — for warranty/free,
  verify in the GUI that the charged line landed at $0 and patch if not.

## Always confirm before logging (either path)

Before logging any time, confirm: (1) how many minutes, (2) what labor type — onsite /
remote / emergency / warranty / project. Never assume a default or round up. Billing
errors are client-facing, hard to reverse, and affect prepaid block balances (Winter has
to reverse them manually).

## Prepaid

Check `prepay_hours` on the customer before billing — the /syncro command holds the
authoritative prepaid + emergency rules.