Job Lifecycle

Overview

A job in MechZie follows a strict state machine from creation to payment. Understanding these states is critical for building the correct UI flows.

State Machine

Status Reference

Status	Who triggers	Description	UI State
`pending`	System	Job created, about to dispatch	”Finding a mechanic…”
`dispatching`	System	Actively searching for mechanics	”Searching nearby mechanics…”
`accepted`	Mechanic	A mechanic accepted the job	Show mechanic info
`en_route`	Mechanic	Mechanic is driving to location	Show map + ETA
`arrived`	Mechanic	Mechanic has arrived	”Mechanic has arrived”
`in_progress`	Mechanic	Work has started	Show live line items
`completed`	Mechanic	Work finished, final price set	Show payment screen
`paid`	System (webhook)	Payment captured successfully	Show receipt
`cancelled`	Customer/Mechanic	Job cancelled	Show cancellation
`no_mechanic_found`	System	No mechanic available in any tier	”No mechanics available”

Creating a Job

curl -X POST https://mechzie-api-production.run.app/api/v1/jobs \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "service_category_id": "uuid-of-category",
    "pickup_address": "MG Road, Bangalore, Karnataka",
    "pickup_lat": 12.9716,
    "pickup_lng": 77.5946,
    "vehicle_id": "uuid-of-vehicle",
    "description": "Engine not starting, battery might be dead",
    "photo_urls": ["https://s3.../photo1.jpg"]
  }'

Required fields: service_category_id, pickup_address, pickup_lat, pickup_lng Optional fields: vehicle_id, description, photo_urls

If the customer has unpaid cancellation fees, job creation returns 402 PAYMENT_REQUIRED. The customer must pay the fee first via POST /payments/create-order.

Dispatch System

After job creation, the system automatically dispatches to nearby mechanics in expanding tiers:

Tier	Search Radius	Timeout	Max Mechanics Contacted
1	3 km	30 seconds	20
2	7 km	30 seconds	20
3	15 km	45 seconds	30

How it works:

System finds available, verified mechanics within Tier 1 radius
Filters by vehicle type (matches job’s vehicle type) and service category (double gate)
Sends job:offer Socket.io event to each matching mechanic
First mechanic to call POST /jobs/{id}/accept wins. Their availability flips to false. The winning mechanic’s other pending offers for different jobs are superseded. Other mechanics contacted for the same job get a job:taken Socket.io event.
If the mechanic accepts another job, their pending offers for other jobs are superseded (revoked) and the mechanic receives a job:offer-revoked Socket.io event.
If no one accepts within the timeout, expands to Tier 2, then Tier 3
If all tiers exhaust → status becomes no_mechanic_found

Mechanics only receive job offers for vehicle types they registered for. A mechanic who only services two_wheeler will never receive offers for four_wheeler jobs.

The customer sees the job status change from pending → dispatching almost immediately. They receive job:status events via Socket.io as the state changes. Show a loading/searching animation during dispatching.

Mechanic Registration

Before receiving job offers, a mechanic must register with their vehicle types and service categories:

curl -X POST https://mechzie-api-production.run.app/api/v1/mechanics/register \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicle_types": ["two_wheeler", "three_wheeler"],
    "service_category_ids": ["uuid-of-category"],
    "service_radius_km": 10,
    "documents": [
      { "type": "aadhaar", "file_url": "https://s3.../doc.jpg" }
    ]
  }'

Field	Type	Required	Description
`vehicle_types`	string[]	Yes (≥1)	`two_wheeler`, `three_wheeler`, `four_wheeler`, `commercial`
`service_category_ids`	uuid[]	Yes (≥1)	Service categories the mechanic can handle
`service_radius_km`	integer	No (default: 10)	Max dispatch radius (1–50 km)
`documents`	object[]	Yes (≥1)	Verification documents (`aadhaar`, `skill_cert`, `photo_id`, `other`)

Updating Vehicle Types

Mechanics can update their vehicle type preferences after registration:

curl -X PUT https://mechzie-api-production.run.app/api/v1/mechanics/vehicle-types \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicle_types": ["two_wheeler", "four_wheeler", "commercial"]
  }'

Both vehicle_types and service_category_ids are required at registration. The mechanic must select at least one of each.

Mechanic Actions (State Transitions)

Each transition is a simple POST:

# Accept the job (mechanic)
POST /api/v1/jobs/{id}/accept

# Start driving to customer
POST /api/v1/jobs/{id}/en-route

# Arrived at location
POST /api/v1/jobs/{id}/arrive

# Start working
POST /api/v1/jobs/{id}/start

# Finish the job
POST /api/v1/jobs/{id}/complete

# Decline the job (during dispatch)
POST /api/v1/jobs/{id}/decline

All require Authorization: Bearer ACCESS_TOKEN. Invalid transitions return 409 INVALID_TRANSITION.

Line Items (Parts & Labor)

Mechanics can add charges during arrived or in_progress status:

curl -X POST https://mechzie-api-production.run.app/api/v1/jobs/{id}/line-items \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Spark plug (NGK BKR6E)",
    "quantity": 2,
    "unit_price": 15000,
    "type": "part",
    "barcode_image_url": "https://s3.../barcode-ngk-bkr6e.jpg"
  }'

Field	Type	Values
`description`	string	Free text
`quantity`	integer	1+
`unit_price`	number	In paisa (₹150 = 15000)
`type`	string	`part`, `labor`, or `other`
`barcode_image_url`	string (URL)	Optional. S3 URL of a barcode photo. Upload via `POST /uploads/presigned-url` before adding the line item.

When completed, final_price = base_price + SUM(quantity × unit_price for all line items). The customer receives a job:line-item-added Socket.io event in real-time.

Cancellation Rules

curl -X PATCH https://mechzie-api-production.run.app/api/v1/jobs/{id}/cancel \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cancel_reason": "Found alternative help"
  }'

Fee Schedule

Cancel from status	Fee	Who can cancel
`pending`	Free	Customer
`dispatching`	Free	Customer
`accepted`	Free	Customer or Mechanic
`en_route`	₹50 (5000 paisa)	Customer or Mechanic
`arrived`	₹50 (5000 paisa)	Customer or Mechanic
`in_progress`	₹50 (5000 paisa)	Customer or Mechanic

When a cancellation fee is charged, the customer cannot create new jobs until they pay it. Check for outstanding fees: GET /api/v1/payments/unpaid-fees.

Checking Unpaid Fees

GET /api/v1/payments/unpaid-fees
Authorization: Bearer ACCESS_TOKEN

Response:

{
  "hasFees": true,
  "amount": 5000
}

Listing Jobs

GET /api/v1/jobs?page=1&limit=20&status=completed
Authorization: Bearer ACCESS_TOKEN

Response:

{
  "data": [...],
  "page": 1,
  "limit": 20,
  "total": 42
}

Filter by status: pending, dispatching, accepted, en_route, arrived, in_progress, completed, paid, cancelled, no_mechanic_found.

Job Detail

GET /api/v1/jobs/{id} returns an enriched response with nested related entities:

{
  "data": {
    "id": "job-uuid",
    "customer": {
      "id": "customer-uuid",
      "name": "Amit Kumar"
    },
    "vehicle": {
      "id": "vehicle-uuid",
      "type": "four_wheeler",
      "make": "Honda",
      "model": "City",
      "registration": "AP00XX0000"
    },
    "service_category": {
      "id": "category-uuid",
      "name": "Flat Tyre Repair"
    },
    "pickup_address": "MG Road, Bangalore",
    "pickup_lat": 12.9716,
    "pickup_lng": 77.5946,
    "description": "Front left tyre punctured",
    "line_items": [
      {
        "id": "item-uuid",
        "job_id": "job-uuid",
        "type": "part",
        "description": "Tyre tube",
        "quantity": 1,
        "unit_price": 35000,
        "barcode_image_url": "https://s3.../barcode.jpg",
        "created_at": "2023-11-07T05:35:00Z",
        "updated_at": "2023-11-07T05:35:00Z"
      }
    ],
    "estimated_price": 85000,
    "final_price": 85000,
    "base_price": 50000,
    "cancellation_fee": 0,
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:40:00Z",
    "mechanic": {
      "id": "mechanic-profile-uuid",
      "name": "Rahul Sharma",
      "avatar_url": "https://s3.../avatar.jpg",
      "rating": "4.8"
    },
    "photo_urls": ["https://s3.../photo1.jpg"],
    "cancel_reason": null,
    "hms_room_id": "room-uuid",
    "disputed_at": null,
    "resolved_at": null
  }
}

estimated_price is computed as base_price + sum(line_items quantity × unit_price). All prices are in paisa.

Mechanic Public Profile

For a dedicated mechanic profile screen, use GET /api/v1/mechanics/{mechanicProfileId}. This endpoint exposes only customer-safe fields:

{
  "data": {
    "id": "mechanic-profile-uuid",
    "name": "Rahul Sharma",
    "avatar_url": "https://s3.../avatar.jpg",
    "rating": 4.8,
    "jobs_completed": 126,
    "service_categories": [
      { "id": "cat-uuid", "name": "Flat Tyre Repair" },
      { "id": "cat-uuid", "name": "Battery Jump Start" }
    ],
    "vehicle_types": ["two_wheeler", "four_wheeler"]
  }
}

Any authenticated user can access this endpoint. Response is cached for 5 minutes.

Frontend Integration Summary

Customer App Flow

Create job → Show searching animation
Listen for job:status → Update UI based on status
On accepted → Show mechanic info, start tracking
job:join → Join job room for location updates
Listen for location:updated → Animate map marker + show ETA
Listen for job:line-item-added → Show added parts/labor
On completed → Show final price, open payment flow
On paid → Show receipt, prompt for rating

Mechanic App Flow

Listen for job:offer → Show accept/decline dialog (with timer)
On job:taken or job:offer-revoked → Dismiss dialog if another mechanic accepted or mechanic is no longer available (e.g. accepted another job)
Accept → Navigate to job detail, start sending location:update
Transition through states → en-route → arrive → start → complete
Add line items during arrived/in_progress
On paid → Show completion, prompt for rating

Getting Started

Guides

Development

Overview

State Machine

Status Reference

Creating a Job

Dispatch System

Mechanic Registration

Updating Vehicle Types

Mechanic Actions (State Transitions)

Line Items (Parts & Labor)

Cancellation Rules

Fee Schedule

Checking Unpaid Fees

Listing Jobs

Job Detail

Mechanic Public Profile

Frontend Integration Summary

Customer App Flow

Mechanic App Flow

​Overview

​State Machine

​Status Reference

​Creating a Job

​Dispatch System

​Mechanic Registration

​Updating Vehicle Types

​Mechanic Actions (State Transitions)

​Line Items (Parts & Labor)

​Cancellation Rules

​Fee Schedule

​Checking Unpaid Fees

​Listing Jobs

​Job Detail

​Mechanic Public Profile

​Frontend Integration Summary

​Customer App Flow

​Mechanic App Flow

Overview

State Machine

Status Reference

Creating a Job

Dispatch System

Mechanic Registration

Updating Vehicle Types

Mechanic Actions (State Transitions)

Line Items (Parts & Labor)

Cancellation Rules

Fee Schedule

Checking Unpaid Fees

Listing Jobs

Job Detail

Mechanic Public Profile

Frontend Integration Summary

Customer App Flow

Mechanic App Flow