public-api-docs

User API Booking Guide

Overview

Booking endpoints support scheduled reservations for users and business accounts. Use them for booking availability search, station selection, price calculation, booking creation, pickup, check-in, extension, update, cancellation, and group booking views.

Related reference: User API User API Guide Discovery And Vehicle Guide Rental Guide Error Codes

Core Concepts

Booking vs Rental

A booking reserves a future time window. A rental is the live trip container that is created or associated when the booking is picked up or otherwise converted into an active rental workflow.

Availability

Booking availability depends on branch, station, category, time window, vehicle availability, booking station capacity, opening hours, cooldowns, pricing, rental requirements, and business-account context.

Booking Price

Booking price can be calculated before booking creation. The booking price can change if the user changes time, branch/station, category, additions, pricing bundle, or business context.

Main Booking Flow

The booking flow has two distinct parts: pre-booking search and booking management.

Phase Goal Main endpoints
Pre-booking Find what can be booked for the desired time and place. GET /bookings/bookable-categories, GET /bookings/available-categories, GET /bookings/available-stations, POST /bookings/available-stations, GET /booking-price-calculator
Create Create the scheduled booking. POST /bookings
Manage Update, cancel, check in, extend, or pick up the booking. GET /bookings/{bookingId}, PATCH /bookings/{bookingId}, DELETE /bookings/{bookingId}, POST /bookings/{bookingId}/check-in, POST /bookings/{bookingId}
Convert Move from booking into live rental behavior. POST /bookings/{bookingId}, GET /rentals/{rentalId} where returned/linked

Common User Workflows

Search Availability

Task Endpoint
List booking availability days GET /bookings/availability
List available categories GET /bookings/available-categories
List bookable categories GET /bookings/bookable-categories
List available stations GET /bookings/available-stations
Search available stations with time slots POST /bookings/available-stations
Calculate booking price GET /booking-price-calculator

Use GET /bookings/bookable-categories to show generally bookable categories, then availability endpoints for a concrete time window.

Recommended pre-booking sequence:

  1. Resolve the branch and the user’s desired start/end time.
  2. Load generally bookable categories with GET /bookings/bookable-categories.
  3. For a concrete time range, call GET /bookings/available-categories.
  4. If the branch uses stations, call GET /bookings/available-stations or POST /bookings/available-stations to find station/time-slot combinations.
  5. Load additions if the booking can include extras.
  6. Calculate estimated price with GET /booking-price-calculator, passing branchId, vehicleCategoryId or pricingBundleId, startTime, endTime, optional additions, optional distance, optional userGroupCode, and optional pricing bundle version.
  7. Check user readiness: T&C, payment method, verification, and business group/cost-center context where relevant.
  8. Only then submit POST /bookings.

Create And Review Bookings

Task Endpoint
Create booking POST /bookings
List current user’s bookings GET /bookings
Get upcoming or active bookings GET /bookings/active
Get booking detail GET /bookings/{bookingId}
List group bookings GET /bookings/user-group/{userGroupId}

When creating a booking, collect the selected branch/station, end station where relevant, category, time window, additions, group/cost-center context, and pricing information.

Important creation fields:

Field Purpose
branchId Start branch or station context. Required.
endBranchId End branch/station for one-way station bookings where supported.
vehicleCategoryId Category the user wants to book.
startTime / endTime Booking time window. Required.
startPosition / startPositionRadius Floating booking context where supported.
userGroupCode Business account context.
costCenterId Business billing/reporting context.
additions Optional extras selected for the booking.
bookingRequest Create as a request that needs operator approval where configured.
reason / externalReference Business or integration metadata.

Manage A Booking

Task Endpoint
Update booking PATCH /bookings/{bookingId}
Pick up booking POST /bookings/{bookingId}
Cancel booking DELETE /bookings/{bookingId}
Check in for booking POST /bookings/{bookingId}/check-in
Check whether booking can be extended GET /bookings/{bookingId}/extendable
Estimate booking extension GET /bookings/{bookingId}/estimate-extension

Recalculate availability and price before updating a booking’s time, station, category, vehicle, additions, or business context. Re-fetch the booking after updates, pickup, check-in, extension, or cancellation.

Booking management guidance:

  1. Use GET /bookings/active for the app home screen or upcoming trip widget.
  2. Use GET /bookings/{bookingId} before showing high-impact actions.
  3. Before PATCH /bookings/{bookingId}, re-run availability and price checks for the proposed change.
  4. For check-in flows, call POST /bookings/{bookingId}/check-in and re-fetch the booking.
  5. For extension flows, call GET /bookings/{bookingId}/extendable, then GET /bookings/{bookingId}/estimate-extension before presenting the extension action.
  6. For pickup, call POST /bookings/{bookingId}. Pickup can fail if the booking is in the wrong state, the pickup window is invalid, requirements are no longer fulfilled, payment is not ready, or the vehicle/station/category configuration changed.
  7. After pickup, continue with the rental flow and show the linked or returned rental state.

Most Relevant APIs

Area Endpoints
Booking CRUD POST /bookings, GET /bookings, GET /bookings/active, GET /bookings/{bookingId}, PATCH /bookings/{bookingId}, DELETE /bookings/{bookingId}
Booking actions POST /bookings/{bookingId}, POST /bookings/{bookingId}/check-in, GET /bookings/{bookingId}/extendable, GET /bookings/{bookingId}/estimate-extension
Availability GET /bookings/availability, GET /bookings/available-categories, GET /bookings/bookable-categories, GET /bookings/available-stations, POST /bookings/available-stations
Pricing and groups GET /booking-price-calculator, GET /bookings/user-group/{userGroupId}

Implementation Notes