Booking a Cab

POST /bookings

Books one vehicle from a quote. EazyGo prices the trip again from its own data, takes the full amount from your agency wallet and confirms the booking straight away (status: confirmed, payment_status: paid).

Headers

Header	Required	Description
`Authorization`	yes	`Bearer <API key>`
`Idempotency-Key`	yes	A unique id for this booking from your system (8 to 100 letters, digits, `-`, `_`, `:`, `.`), e.g. your order number

Body

Field	Required	Description
`quote_token`	yes	From `POST /quotes`, less than 30 minutes old
`vehicle_category_id`	yes	One of the quote's `options[].vehicle_category.id`
`passenger.name`	yes	Passenger's name
`passenger.mobile`	yes	10-digit Indian mobile number. The passenger gets the driver details on it
`passenger.email`	no	Passenger's email
`pickup.address`	yes	Full pickup address for the driver
`pickup.latitude`, `pickup.longitude`	yes	Exact pickup point. For local and hourly trips it must be within 3 km of the quoted pickup
`drop.address`	no	Drop address. Recommended for local and outstation trips
`drop.latitude`, `drop.longitude`	no	For local trips, within 3 km of the quoted drop
`notes`	no	Instructions for the driver (up to 1,000 characters)

curl -X POST https://eazygo.in/api/agent/v1/bookings \
  -H "Authorization: Bearer $EAZYGO_API_KEY" \
  -H "Idempotency-Key: order-58213" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_token": "eyJpdiI6...",
    "vehicle_category_id": 2,
    "passenger": { "name": "Asha Sharma", "mobile": "9800000001" },
    "pickup": { "address": "Flat 4, Green Park, Shivajinagar, Pune", "latitude": 18.5311, "longitude": 73.8479 },
    "notes": "Two large bags"
  }'

201 Created:

{
  "success": true,
  "message": "Booked EZ7Q2K9P4XMA: ₹661.50 paid from your wallet.",
  "data": {
    "reference": "EZ7Q2K9P4XMA",
    "status": "confirmed",
    "payment_status": "paid",
    "trip_status": "pending",
    "service_type": "local",
    "vehicle_category": { "id": 2, "name": "Sedan" },
    "pickup_at": "2026-11-20T05:30:00+05:30",
    "return_at": null,
    "hours": null,
    "from": { "city_id": 133024, "city": "Pune", "location": "Shivajinagar, Pune" },
    "to": { "city_id": null, "city": null, "location": "Pune International Airport" },
    "pickup": { "address": "Flat 4, Green Park, Shivajinagar, Pune", "latitude": 18.5311, "longitude": 73.8479 },
    "drop": { "address": null, "latitude": null, "longitude": null },
    "passenger": { "name": "Asha Sharma", "mobile": "9800000001", "email": null },
    "notes": "Two large bags",
    "included_km": 15,
    "extra_km_rate": 14,
    "amounts": {
      "public_fare": 700, "discount": 0, "agency_commission": 70, "taxable": 630,
      "gst_rate": 5, "gst": 31.5, "total": 661.5, "paid": 661.5, "due": 0
    },
    "driver": null,
    "vehicle": null,
    "trip_started_at": null,
    "trip_completed_at": null,
    "booked_by": { "id": 812, "name": "Website booking engine login" },
    "created_at": "2026-11-18T10:33:12+05:30"
  }
}

Retrying safely

Networks fail. If you don't get an answer, send the same request again with the same Idempotency-Key:

If the first request booked, you get that booking back with 200 OK and "idempotent_replay": true. Nothing is booked or charged again, even if the body differs.
If the first request didn't book, the retry books normally.

Use a new key for every new booking. The key is unique per login: another login of your agency reusing it gets 409 IDEMPOTENCY_KEY_REUSED.

When a booking is refused

HTTP	`error`	Meaning
400	`IDEMPOTENCY_KEY_REQUIRED`	Missing or malformed `Idempotency-Key`
402	`INSUFFICIENT_BALANCE`	The wallet can't cover the booking. Top up, then retry with the same key
422	`QUOTE_EXPIRED`	The quote is older than 30 minutes, was changed, or is another agency's
422	`VEHICLE_UNAVAILABLE`	That vehicle can no longer do the trip. Quote again
422	`ADDRESS_TOO_FAR`	The pickup or drop is more than 3 km from the quoted point. Quote again with the real points
422	`PICKUP_TOO_SOON`	The pickup no longer has enough notice
422	`AGENCY_NOT_ACTIVE`	Your agency is suspended or not yet approved
422	`VALIDATION_FAILED`	See `errors` for the fields

What happens next

trip_status moves through pending → assigned_vendor → assigned_driver → accepted → started → completed. A cancelled booking has status: cancelled. The driver (name, mobile) and vehicle (model, registration_number, color) fields fill in once EazyGo assigns them, usually well before pickup. The passenger is also told on WhatsApp.

GET /bookings/{reference}

One booking, in the same format as above. A reference you can't see returns 404 BOOKING_NOT_FOUND.

GET /bookings

Your bookings, newest first.

Parameter	Description
`status`	e.g. `confirmed`, `completed`, `cancelled`
`trip_status`	e.g. `assigned_driver`, `started`
`pickup_from`, `pickup_to`	Pickup date range, `YYYY-MM-DD` (IST)
`per_page`	1 to 100, default 25
`page`	Page number

{
  "success": true,
  "data": [ { "reference": "EZ7Q2K9P4XMA", "...": "..." } ],
  "meta": { "current_page": 1, "per_page": 25, "total": 1, "last_page": 1 }
}

← Cities and Quotes

Cancellations →