Cab Ride Booking

POST /v1.5/bookings/create

Request Parameters

• Create Booking

  Once user selects category of choice and confirms for the ride to be booked, the API for booking creation can be called. If the request is correct, a booking id is first generated and sent in the response. The system then starts searching for nearby cabs to be allotted to the booking. There are two possibilities:

  • Successful allotment of cab and driver
  • Stockout due to non-availability of cabs

  Example Request

  POST

  https://devapi.olacabs.com/v1.5/bookings/create

  
  {
  "drop_lat":"12.9592",
  "drop_lng":"77.6974",
  "pickup_lat":"12.9523",
  "pickup_lng":"77.6432",
  "category": "mini",
  "pickup_mode":"now"
  "payment_instrument_type":"cash",
  "fare_id": "1:000008:50002738-7242-4728-9644-0ae0d6fceb01",
  "coupon_code": "DISC50"
  "affiliate_uid": "shfjh3342",
  "merchant_txn_id":"Aabc-12as123if-123123a"
  }
  
  Headers: {
  authorization: Bearer 9b16121212f12ff12f12f1f12f1f12f2
  x-app-token: fd5d4d3726121212f12ff12f12f1f12f1f12fa
  }
  

  Example Response (Success)

  
  {
   "status": "SUCCESS",
   "booking_id": "CRN123456789",
   "message": "Searching for a cab.",
   "merchant_txn_id":"Aabc-12as12if-123123a",
   "booking_timeout": 70,   // time post which driver allocation will no longer happen
   "booking_timeout_unit": "SECONDS"
  }
  

  Once success is received in the response, keep polling Track Ride API (Link) to get driver allotment status. The response will show ‘booking_status’ as one of the following:

  • ALLOTMENT_PENDING: System is still searching for cabs to be allotted
  • CALL_DRIVER: System has allotted a cab (Response will also contain cab/driver details)
  • ALLOTMENT_FAILED: System could not locate any cab nearby

  When the status is allotment pending, the users on your app can be shown a loading screen. On successful allotment, the cab/driver/otp details can be displayed on the screen. In case of no allotment, the same can be conveyed to the users asking them to try booking again.

  Example Responses (Failures)

  • Car category parameter sent is not valid

    
    {
        "message": "BOOKING_FAILED",
        "code": "INVALID_CAR_CATEGORY"
    }
    
    

  • Pickup lat-lng are in a city where Ola is not available

    
    {
        "message": "BOOKING_FAILED",
        "code": "INVALID_CITY"
    }
    

  • Pickup and Drop lat-lng sent are the same

    
    {
        "status": "FAILURE",
        "code": "SAME_PICKUP_DROP",
        "message": "Pickup and drop locations cannot be the same."
    }
    

  • User’s Ola account is in banned or deactivated state

    
    {
       "status": "FAILURE",
       "code": "BANNED USER",
       "message": "Your account has been suspended due to violation of Ola policies. Please contact our customer care."
    }
    

  • User has outstanding payment due from a previous ride

    
    {
        "status": "FAILURE",
        "code": "OUTSTANDING_DUE" or "PAYMENT_PENDING" or "OLA_CREDIT_DUE"
        "message": "Please clear the amount due for previous ride(s). Update your app if you don't see your payment options."
    }
    

  • Pickup and Drop lat-lng are in different cities

    
    {
      "status": "FAILURE",
      "code": "INVALID_DROP_LOCATION",
      "message": "Please enter a drop location within your city"
    }
    




• Abort Booking

  When the system is searching for cabs, user can choose to abort the process of driver allotment. In that case, the abort booking API can be called by sending the ‘booking_id’ provided in the create booking API response. If a driver has already been allotted, abort will not work and it will throw a failure.

  
  

  Example Request

  POST

  https://devapi.olacabs.com/v1/bookings/abort

  
   {
  "booking_id":"CRN123456789"
  }
              
  Headers: {
  Authorization: Bearer 9b6121212f12ff12f12f1f12f1f12f2
  x-app-token: fd6121212f12ff12f12f1f12f1f12fa
  }

  Example Request(Success)

  
  {
   "status": "SUCCESS",
   "message": "Booking Cancelled Successfully",
   "code": "SUCCESS"
  }
  

  Example Request(Failure)

  
  {
    "status": "FAILURE",
    "message": "You can track your ride in a moment.",
    "code": "BOOKING_ALLOTED"
  }
  

  Once success is received in Abort Booking API, calling Track Ride API sends booking_status as ‘BOOKING_CANCELLED’ in the response.

Important Guidelines

• You can send booking create request even for categories which are not available as per ride availability response. It is possible that a cab becomes available during the time system is searching for a cab to allotted to the booking
• Receiving ‘success’ in booking create response and generation of booking_id does not guarantee that user will receive a cab. You need to display booking information to the user only when the cab/driver details are available in the Track Ride API (Link) response
• If booking request is made and response is not received due to timeouts or network failures, call My Rides API (Link) to check if any booking is in active state after few seconds
• Drop location is mandatory for Micro and Auto bookings

Update Drop Location

POST /v1/bookings/drop_location

Request Parameters

Example Request

  "body": {
    "drop_lat": 12.972934,
    "drop_lng": 77.722302,
    "booking_id": "CRN123456789"
  }

  "headers": {
    "Authorization": "Bearer b6121212f12ff12f12f1f12f1f12fbf",
    "X-APP-TOKEN": "6a56121212f12ff12f12f1f12f1f12fc",
    "Content-Type": "application/json"
  }

Example Response

{
  "status": "SUCCESS",
  "request_type": "Update User Booking Drop Location"
  "header": "SUCCESS",
  "text": "Drop Location Updated"
}

{
  "status": "FAILURE",
  "request_type": "Update User Booking Drop Location",
  "header": "Invalid Drop Location",
  "text": "Please enter a drop location within your city"
} 

{
  "status": "FAILURE",
  "request_type": "Update User Booking Drop Location",
  "header": "Oops!",
  "text": "Sorry, the ride is already completed or cancelled!"
}