fix(syncro): correct billing rules for prepaid customers and ticket creation defaults

- Add hard rule: 9269129 (Prepaid Project Labor) is Exempt and does NOT deduct
  from prepay_hours block — never use for normal work (verified 2026-05-04)
- Expand prepay_hours check from emergency-only to ALL billing workflows
- Fix emergency/prepaid branching table to use delivery-channel product instead
  of hardcoding 26118 (Onsite) for remote and other labor types
- Clarify invoice step 15: $0.00 invoice total is correct for prepaid customers;
  verify by checking customer.prepay_hours dropped by quantity
- Field 7 (Assigned Tech): add explicit default to API key owner; mark as MUST
  always be included in POST payload to prevent null user_id on ticket create
- Add billing workflow hard rule: read prepay_hours before any billing, not just
  emergency, so prepaid invoice behavior is known before execution begins

Triggered by ticket #32265 (Russo Law Firm) missing assignee/priority/billing.
Russo Law has 12.5 prepaid hrs — 0.5 hrs correctly deducted via invoice #67578.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-05-08 11:59:54 -07:00
parent 8539f62462
commit 56ada4bea1

View File

@@ -40,6 +40,10 @@ 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`. If `prepay_hours > 0`, the customer has a prepaid block — bill `26118` (Onsite) at `quantity × 1.5` instead (prepaid debits by quantity, not by dollars). Never stack `26118` + `26184` for the same hours — the Emergency product rate already has the 1.5× multiplier baked in. Verified 2026-04-23 on ticket #32203 (Desert Auto Tech) after Winter caught the bug.
**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).
**Line-item `price_retail` MUST be set explicitly:** Earlier guidance to "omit `price_retail` and let Syncro auto-calc from the product rate" was wrong — the rate does NOT populate automatically. Fetch it with `GET /products/<id>``.product.price_retail` and pass it on `add_line_item`. Omitting it leaves the line at $0.00 and the invoice posts at $0.00 (verified 2026-04-23 on #32203).
## Implementation
@@ -295,7 +299,7 @@ Collect in one pass (do not ask field by field):
| 4 | **Description** | Expanded detail — becomes the "Initial Issue" comment body |
| 5 | **Do Not Email** | Suppress customer notification on ticket create? (yes for internal/reminder tickets) |
| 6 | **Due Date** | ISO date |
| 7 | **Assigned Tech** | Who owns the ticket |
| 7 | **Assigned Tech** | Who owns the ticket. Defaults to API key owner if not specified (mike → 1735, howard → 1750). MUST always be included in the POST payload — never omit. |
| 8 | **Contact** | Look up from `GET /customers/{id}` → `.contacts[]`; show list, ask user to pick |
| 9 | **Address/Site** | `address_id` — also comes from customer contacts with address data |
| 10 | **Appointment Type** | From table above; omit section if no appointment needed |
@@ -625,7 +629,7 @@ JSON
| `573881` | Labor - In Shop Business | `150.00` | Hardware brought into ACG's shop |
| `26184` | Labor - Emergency or After Hours Business | `262.50` | **1.5× onsite; time-and-a-half baked into the rate.** Non-prepaid customers only. Do NOT stack with `26118` for the same hours. |
| `1049360` | **Labor- Warranty work** | `0.00` | **Use this for ANY warranty / no-charge work.** Do NOT use a billable labor product + `billable: false` or a patched price. See `feedback_syncro_warranty_product.md`. |
| `9269129` | Labor - Prepaid Project Labor | `0.00` | Debits from customer `prepay_hours` bank. Per `feedback_syncro_labor_type.md`: do NOT use as a default — only when explicitly directed. |
| `9269129` | Labor - Prepaid Project Labor | `0.00` | **DO NOT USE for normal or prepaid work.** Exempt Labor category — does NOT deduct from `prepay_hours` block despite the name. Billing a prepaid customer with this product gives a $0.00 invoice AND silently skips the block decrement. Verified 2026-05-04 (see `feedback_syncro_labor_type.md`). Only use if explicitly directed. |
| `9269124` | Labor - Internal Labor | `0.00` | Non-billable internal ACG time (not customer-facing). |
| `26117` | Fee - Travel Time | `40.00` | Per travel event (not hourly) |
| `68055` | Labor - Website Labor | `150.00` | Website-related work |
@@ -638,8 +642,10 @@ Check: `GET /customers/<id>` → `.customer.prepay_hours` (string; `"0.0"` means
| `prepay_hours` | Regular hours | Emergency / after-hours |
|---|---|---|
| `0` / null (no prepaid) | `26118`, qty = actual_hours | `26184`, qty = actual_hours (rate already 1.5×) |
| `> 0` (has prepaid block) | `26118`, qty = actual_hours | `26118`, qty = actual_hours × **1.5** |
| `0` / null (no prepaid) | delivery-channel product, qty = actual_hours | `26184`, qty = actual_hours (rate already 1.5×) |
| `> 0` (has prepaid block) | delivery-channel product, qty = actual_hours | delivery-channel product, qty = actual_hours × **1.5** |
"Delivery-channel product" = `1190473` remote, `26118` onsite, `573881` in-shop, `68055` web — match to how work was actually delivered.
**Rationale (Winter, 2026-04-23):** Prepaid blocks debit by QUANTITY, not dollars. To charge time-and-a-half against a prepaid block we bump the quantity to 1.5× on the Onsite product rather than switching to the Emergency product — switching would double-count because the Emergency product has the 1.5× already built into its dollar rate.
@@ -696,7 +702,7 @@ When showing ticket detail, include:
**ALWAYS ask the user for minutes and labor type before logging any time. Never assume a default.**
**ALWAYS show a preview of the comment + timer entry to the user before posting. Wait for confirmation.**
**ALWAYS read `customer.prepay_hours` before choosing the labor product for emergency work.**
**ALWAYS read `customer.prepay_hours` before billing ANY work** — not just emergency. Prepaid customers get $0.00 invoices with block deductions; non-prepaid customers get dollar invoices. Knowing this before you start prevents false "zero invoice" panic mid-workflow.
**ALWAYS bill via `timer_entry → charge_timer_entry`. Bare `add_line_item` for time-based work bypasses Syncro's time-tracking system and is forbidden — see Hard Rules.**
When `/syncro bill <number>` is called:
@@ -718,7 +724,7 @@ When `/syncro bill <number>` is called:
12. Charge the timer: `POST /tickets/{id}/charge_timer_entry` with `{"timer_entry_id": N}` — this records the time AND auto-generates a linked line item with the timer's `product_id` and computed `quantity` (hours).
13. Verify the auto-generated line item picked up the rate: `GET /tickets/{id}` and inspect the new entry in `.ticket.line_items[]`. If `price_retail` came in at `0.00` (Syncro sometimes drops it on auto-generated lines), patch it: `PUT /tickets/{id}/update_line_item` with `{"ticket_line_item_id": N, "price_retail": <rate>}`.
14. Create invoice: `POST /invoices` with `{"ticket_id": N, "customer_id": N, "category": "Standard"}`
15. Verify invoice: `GET /invoices/{id}` → confirm `.invoice.total` matches `qty × price_retail`. (For prepaid customers, the line totals against the prepay block — `.invoice.total` will reflect any non-prepaid items only.)
15. Verify invoice: `GET /invoices/{id}` → confirm line items transferred. **For prepaid customers, `.invoice.total` will be $0.00 — this is correct.** The line item name is annotated "- Applied X Prepay Hours" and the block is debited. Confirm by re-fetching `customer.prepay_hours` and checking it dropped by `quantity`. For non-prepaid customers, `.invoice.total` must equal `qty × price_retail`.
16. Update ticket status to `Invoiced`
**If `.invoice.total` comes back $0.00** (auto-generated line item went in with null price and you missed step 13): `PUT /tickets/{id}/update_line_item` with `price_retail` on each item, then `DELETE /invoices/{bad_id}` and re-POST `/invoices`. Recovery verified on #32203 (2026-04-23).