The visit lifecycle — Servicio docs

A visit has a simple state machine. Understanding it makes the rest of Servicio's behavior obvious.

The states

scheduled — created, assigned to a date and (optionally) a tech, no actions yet.
en_route — tech tapped "En route." Time entry opens. Client gets "on the way" SMS.
in_progress — tech tapped "Arrive." Weather stamp captured. GPS breadcrumb may be running.
completed — tech tapped "Complete." Invoice created. Service report email sent. Review request queued.
skipped — tech tapped "Skip" with a reason. Time entry closed. Client gets skipped notification.

What fires at each transition

scheduled → en_route

Opens a kind=visit TimeEntry at the en-route timestamp (catches drive time).
Fires the visit.on_the_way template (SMS + email, per tenant notification toggles) in the client's preferred language.
Writes the outgoing message to the client's inbox thread.

en_route → in_progress

Captures weather stamp (temp, short forecast) from api.weather.gov.
Records arrived_at timestamp.
If no en-route transition occurred, opens a TimeEntry here as a fallback.

in_progress → completed

Closes the TimeEntry with computed minutes; writes labor_minutes to the visit.
Validates any required checklist items (blocks completion if missing).
Creates an Invoice with the ClientService price + any line-item adjustments.
Fires visit.completed email template with photo attachments + AI-generated summary.
Fires invoice.sent template (SMS + email).
Queues a review.request template dispatch.
On invoice.paid (separate event): CommissionCalculator accrues commissions per attribution.

any state → skipped

Captures skip reason + optional note.
Closes any open TimeEntry.
Fires visit.skipped template.
If reschedule=yes, creates a new scheduled Visit 3 days out.

💡

The lifecycle is idempotent in one direction: you can go scheduled → en_route → in_progress → completed, but you cannot reverse. If a tech accidentally taps Complete, the owner must handle the correction by issuing a credit note or adjusting the invoice manually.

The owner override

Owners can change any visit's status from the visit detail page. Use sparingly — it breaks the audit trail cleanliness. The legitimate cases:

Tech forgot to tap Complete and then went home. Owner marks completed with the actual completion time.
Tech marked skipped but the visit actually happened. Owner marks completed (ideally within 24 hours).
Scheduled visit is no longer needed. Owner cancels (moves to cancelled state, which is distinct from skipped).

⚠

Every owner-initiated status change writes to the audit log with the before and after. You can always see who changed what. This is important for disputes — if a client claims "you said you came but you did not," the audit log is the record of truth.