sync: auto-sync from GURU-5070 at 2026-06-23 21:14:42

Author: Mike Swanson
Machine: GURU-5070
Timestamp: 2026-06-23 21:14:42

.claude/commands/syncro.md

@@ -45,6 +45,8 @@ Create, update, close, comment on, and bill tickets in Syncro PSA.
 
 **Emergency/after-hours billing — check prepaid first:** Before adding a `26184` (Emergency) line item, `GET /customers/<id>` and read `prepay_hours`. Emergency = time-and-a-half (×1.5), applied ONCE — never bill a separate regular + emergency line for the same hours. **No prepaid (`prepay_hours == 0`):** `26184` at qty = actual hours; set `price_retail` by delivery channel — **Onsite $262.50** (175×1.5, 26184's default), **Remote / In-Shop $225** (150×1.5, override price_retail). The rate carries the 1.5×; do NOT also ×1.5 the qty. **Prepaid (`prepay_hours > 0`):** still use `26184`, at qty = actual hours **× 1.5** (premium goes in the quantity since prepaid debits by quantity; invoice nets $0, block debits hours×1.5). e.g. 1.5 emergency hrs prepaid → `26184` @ 2.25. (Rule updated 2026-05-27 by Mike: prepaid emergency uses `26184`, NOT the old `26118`×1.5 — keeps the line labeled emergency + mapping right in QuickBooks. Original ×1.5-not-additive lesson: #32203 Desert Auto Tech 2026-04-23, Winter.)
 
+**`prepay_hours` is ONLY reliable from `GET /customers/{id}` — the customer SEARCH/LIST endpoint lies.** `GET /customers?query=...` (and any list endpoint) returns `prepay_hours: null` (or stale) even when the customer HAS a block. **NEVER read `prepay_hours` from a search/list result, and NEVER assert "no prepaid block" / "real charge" / a dollar total in a preview built from search data.** Before ANY billing preview or decision that mentions prepay, do a full `GET /customers/{id}` and read `.customer.prepay_hours` from THAT response. If you only have search data, fetch the full record first — do not guess. The billing-flow Step-1 GET is mandatory and must happen BEFORE the preview, not just before the invoice. (Recurring miss flagged by Mike 2026-06-23: previews repeatedly said "$300, no block," then the block surfaced at invoice time and netted $0 — Dataforth, Grabb & Durando #32455.)
+
 **Prepaid customers — ALL billing (not just emergency):** `GET /customers/<id>` → `prepay_hours` before creating ANY invoice for a prepaid customer. When you bill a prepaid customer using a billable labor product (remote / onsite / in-shop / web), Syncro automatically deducts from their prepay block and the invoice total shows $0.00. The line item name is annotated "- Applied X Prepay Hours". This is correct behavior — do NOT treat a $0.00 invoice as an error. Verify the deduction by re-fetching `customer.prepay_hours` after invoicing and confirming it dropped by `quantity`.
 
 **`9269129` (Labor - Prepaid Project Labor) is EXEMPT — it does NOT deduct from prepay blocks:** Despite the name, this product is categorized as Exempt Labor at $0.00 and contains no prepay-deduction logic. Billing a prepaid customer with this product results in a $0.00 invoice AND no block decrement — silent accounting drift. Discovered 2026-05-04 (see `feedback_syncro_labor_type.md`). NEVER use `9269129` for normal or prepaid work. Only use it if explicitly directed. The correct approach for prepaid customers is a billable labor product matching the delivery channel (remote / onsite / in-shop / web).
@@ -610,9 +612,9 @@ COMMENT_ID=$(echo "$COMMENT_RESP" | jq -r '.comment.id')
 #### Customers
 
 ```bash
-# Search
+# Search — returns id/name/email ONLY. Do NOT read prepay_hours from this list (it is null/stale here).
 curl -s "${BASE}/customers?query=<name>&per_page=25&api_key=${API_KEY}" | jq '[.customers[] | {id, business_name, email}]'
-# Get one
+# Get one — this is the ONLY trustworthy source of prepay_hours. Always GET this before any billing preview.
 curl -s "${BASE}/customers/${CUST_ID}?api_key=${API_KEY}" | jq '{id: .customer.id, prepay_hours: .customer.prepay_hours}'
 ```