Browse the guides
Workflow States & Actions
The exact public appointment, repair-order, job, and task vocabularies in API v1.
State values are public contract values, not the application's internal labels.
Store them as strings, accept additive future values, and do not infer that
adjacent entries below are valid transitions. For operations, use
available_actions and handle structured blockers.
Appointments
status is exactly one of:
requested | booked | arrived | fulfilled | cancelled | no_showThe only public status actions are:
available_actions value |
Operation |
|---|---|
cancel |
POST /v1/appointments/{id}/cancel |
check_in |
POST /v1/appointments/{id}/check-in |
Both actions require appointments.read, appointments.write, and an
Idempotency-Key. Converting an eligible appointment to a repair order is
POST /v1/appointments/{id}/repair-order; it additionally requires
repair_orders.read and repair_orders.write, returns 201 when it creates
the order, and may return 200 when the appointment was already coherently
converted.
Repair orders
state is exactly one of:
scheduled | checked_in | estimating | awaiting_authorization | authorized
in_progress | waiting_for_parts | quality_check | completed | ready_for_pickup
invoiced | paid | picked_up | closed | cancelled | unknownunknown is a deliberate safety value for an internal state that has no public
mapping. Do not treat it as open, closed, or retryable. Refresh the object and
surface it for operator review. The public API has no repair-order state-change
operation; state changes are observed through reads and
repair_order.status_changed events.
Jobs
A job has two independent state axes:
| Field | Values |
|---|---|
decision_state |
pending, authorized, declined, deferred, cancelled, unknown |
execution_state |
not_started, in_progress, paused, completed, unable_to_complete, unknown |
Do not collapse these into one status. Public operations never authorize or
decline work. With repair_orders.read plus jobs.actions, an authorized job's
available_actions can contain start, complete, or unable_to_complete,
mapping to the three /v1/jobs/{id}/… operations. An empty list means no job
action is currently available to this integration.
kind is exactly service, fee, discount, or no_charge.
Tasks
Task status is open, in_progress, done, blocked, or waiting.
Task priority is low, normal, high, or urgent. PATCH accepts every
status except done; use POST /v1/tasks/{id}/complete to reach done.
Availability is not a state transition feed
GET /v1/appointments/availability returns one summary per shop-local date:
available, reason, open_time, close_time, booked, and capacity. It
does not return bookable time slots. A create can still return a structured
conflict if capacity or policy changes after the availability read.