Part Warranty Tracking (Mechanics)

Paid pluginsize Mplanned, not built

Indicative price, not an offer: €24/mo; warranty claim tracking, supplier billing, dispute audit trail

Generated from docs/plan/paid/part-warranty-tracking/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A paid module for mechanics/parts shops to track warranty claims from sale through supplier dispute resolution, maintaining audit trails for chargebacks and supplier billing. Core provides orders; this pack adds warranty claim entities, dispute workflows, and supplier billing reports.

The problem

A customer returns a failed alternator 6 months after purchase; mechanic must manually email the supplier, track whether the claim is approved/rejected, and account for the credit in next month’s supplier invoice. Without audit trails, disputes arise: ‘we sent that claim in July—why isn’t it in your system?’

What it does

• Warranty claim creation: link to original order/line item, capture claim reason, date of failure, customer contact
• Claim status workflow: draft → submitted → approved/rejected → credited/replaced (state machine)
• Supplier communication: email supplier with claim details, link to track responses (CC supplier on status changes)
• Dispute management: record supplier response (approved/rejected/needs more info), escalation chain (manager review if >€500)
• Supplier billing report: monthly; list claims approved for credit, total credit amount, link to PO/invoice (for reconciliation)
• Audit trail: every claim state change logged (who, when, notes); immutable record for chargebacks
• Claim templates: pre-fill reason (DOA, premature wear, manufacturing defect) with required fields per reason

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Returns logistics (RMA, shipping labels)—owned by fulfillment/returns module
• Inventory adjustment when claim approved—core inventory system handles credit notes, not this module
• Supplier contract terms (warranty % coverage)—config stored in supplier record, module applies but doesn’t manage contracts
• Automated supplier payment/credit processing—owned by accounting/AR module; this module only reports
• Customer-facing warranty registration portal—owned by customer account module, not supplier-facing

Data model

New entities: WarrantyClaim (id, orderId, lineItemId, claimReason, failureDate, status, supplierApproved, creditAmount, createdAt, createdBy); ClaimNote (id, claimId, author, note, timestamp, type[internal|supplier-facing]). Links: WarrantyClaim.orderId → Order, WarrantyClaim.lineItemId → OrderLineItem. Migration: none (new data).

API

• POST /api/v1/warranty-claims — create claim linked to order line item (staff only)
• GET /api/v1/warranty-claims/{id} — fetch claim + audit trail (staff/supplier roles, supplier sees own claims only)
• PATCH /api/v1/warranty-claims/{id}/status — update claim status (draft→submitted→approved, staff only, audit logged)
• POST /api/v1/warranty-claims/{id}/notes — add internal or supplier-facing note (staff/supplier, audit logged)
• GET /api/v1/warranty-claims/supplier-billing — monthly billing report (claims approved for credit, total, by supplier)
• POST /api/v1/warranty-claims/bulk-export — export claims (date range, supplier, status) as CSV for AR

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Staff dashboard: warranty claims list (filter by status, supplier, date range). Claim detail: order info, failure date, reason, timeline of status changes + notes. Supplier communication section: history of emails sent, supplier notes (read-only for supplier), escalation trigger (if >€500, require manager approval). Monthly billing card: list suppliers with approved claims this month, total credit amount, button to export for AR reconciliation.

The seam — why this is paid

Core owns: order history, supplier records, audit logging, email infrastructure. Paid pack owns: WarrantyClaim entity, status workflow state machine, claim note audit, supplier billing report logic. Seam drawn here because warranty disputes require support team involvement (interpreting supplier contracts, handling escalations)—core cannot manage warranty policy.

Support commitment: warranty claim audits, supplier relationship management

Dependencies

• core:orders — warranty claims link to Order and OrderLineItem
• core:audit-log — every status change and note must log who/when/previous value
• core:email — send claim notifications to supplier, status change emails
• core:supplier-management — supplier record lookup (assumed to exist)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• A warranty claim is created for Order #123, line item ‘Alternator X’, reason ‘DOA’, failure date 2026-08-01; the claim status is ‘draft’
• The claim status is changed to ‘submitted’; an email is sent to the supplier listing claim reason, order #, failure date; audit log shows ‘staff-id submitted claim on 2026-09-01’
• A supplier-facing note is added: ‘Supplier approved, credit €45’; the note is visible in the supplier’s view and logged
• An internal note ‘Check for similar failures’ is added by staff; the note is NOT visible to the supplier (internal tag hides it)
• A claim for €550 moves to ‘approved’; the system flags it as ‘requires manager review’ and email is sent to manager (audit logged)
• A monthly billing report is generated (date range 2026-09-01 to 2026-09-30); it lists 3 suppliers, claims approved for each, total credit €1200; export to CSV is valid (no truncation)
• A claim is rejected by supplier (status ‘rejected’); staff are notified by email, the claim no longer appears in the billing report
• A claim created on 2026-08-01 is never changed; the audit trail shows only creation entry (no accidental edits)

Risks

Supplier email must be accurate—sending claim to wrong email address breaks the workflow. Audit log is the source of truth for chargebacks; if an entry is missing or corrupted, it opens the merchant to disputes. Currency must lock to claim creation (use order’s currency), not shop setting. Billing report must be idempotent—exporting twice should show same totals (no double-counting approved claims). Escalation logic for >€500 must not block status updates—require manager approval as async, not blocking.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.