public-api-docs

Operations API Booking Guide

Overview

Bookings are scheduled reservations for a vehicle category, vehicle, branch, station, user, or business account context. Use the Operations API booking endpoints when building operator tools for booking search, booking creation, availability validation, approval workflows, pickup/delivery support, cancellation, billing review, and station utilization.

Bookings are different from on-demand rentals. 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.

Related reference: Operations API

Operations API Guide

Rental Guide

Vehicle Guide

Vehicle Category Guide

Pricing Guide

Error Codes

Core Concepts

Booking State

Booking state describes where the reservation is in its lifecycle:

State	Meaning
`BOOKED`	Booking was created and is waiting for normal processing or approval, depending on tenant configuration.
`APPROVED`	Booking request was approved and can continue toward pickup.
`DELIVERED`	A vehicle is associated with the booking and is ready for the user to pick up or start the rental.
`SUCCESSFUL`	Booking completed successfully.
`CANCELED`	Booking was canceled.
`ABORTED`	Booking was aborted after it could not continue normally.
`EXPIRED`	Booking expired because the user or operator did not complete it in the required time window.
`DECLINED`	Booking request was rejected.

Operator tools should show the state and the next available action together. For example, approval actions only make sense for bookings that are still waiting for approval, while pickup and delivery actions depend on the booking state, time window, vehicle assignment, and user requirements.

Booking Type And Rental Type

The booking response can expose both type and rentalType:

Field	Meaning
`type`	Booking layout, such as `STATION` or `FLOATING`.
`rentalType`	Rental business type, such as private or business usage depending on tenant configuration.

Station bookings normally use start and end branches/stations. Floating bookings can use a start position and radius. Business bookings can also include user group, reason, and cost center context.

Booking Stations

Booking stations are branch-like booking locations used for station-based reservations. They can expose opening information, time zone, vehicle categories, vehicle capacity, expected vehicles, and conflicts.

Use booking station endpoints when building station planning screens, capacity views, and operator tools that need to understand which vehicles or categories are expected at a station during a time range.

Availability And Conflicts

Availability is time-window based. A category or vehicle can be available for one booking window and unavailable for another because of existing bookings, station capacity, opening hours, cooldowns, branch configuration, vehicle category configuration, rental requirements, or pricing configuration.

For create/update workflows, validate availability before writing:

Use /bookings/bookable-categories to discover categories that are generally configured for a branch.
Use /bookings/available-categories to find categories with at least one bookable vehicle in the requested time window.
Use POST /bookings/availability/validate before creating or updating a booking.
Use booking station conflict endpoints when building station capacity planning tools.

The deprecated station availability endpoint should not be used for new tooling. Use POST /bookings/availability/validate instead.

Cooldowns

Bookings can include startStationCooldown and endStationCooldown. Cooldowns represent buffer time around bookings, usually to support operational processes such as turnaround, inspection, cleaning, charging, or relocation.

Use GET /bookings/cooldowns when an operator tool needs to calculate cooldowns for a branch, end branch, and vehicle category before creating or updating a booking.

Booking Pricing

Bookings use booking pricing, not on-demand time-slot pricing. Booking pricing is configured through BOOKING pricing bundles and booking pricing bundle versions.

Important pricing fields:

Field	Meaning
`pricingBundleId`	Optional override for which booking pricing bundle should apply.
`pricingBundleVersion`	The pricing bundle version that was applied to the booking.
`price` / `estimatedPrice`	Booking price information, usually estimated before final billing.
`cancellationInformation`	Whether the booking can be canceled, the free-cancellation deadline, and estimated cancellation fee.

When updating a booking, be careful with pricingBundleId. If it is not provided in the update request, the existing pricing configuration can be reset and the default pricing bundle or pricing strategy can be used.

For pricing setup and simulation, see the Operations API Pricing Guide.

Rental Requirements

Booking creation and pickup can depend on the same requirement model used by rentals. Requirements are configured by branch and vehicle category and can include user verification, accepted terms, payment method, payment pre-authorization, rental authority, age/license checks, balance, or business-account context.

Use GET /rental-requirements/start with bookingStartTime and bookingEndTime when an operator tool needs to explain why a user can or cannot start a booking-related rental.

Common Operator Workflows

Search And Review Bookings

Use GET /bookings for branch-scoped booking lists.

Useful filters:

Filter	Use it for
`branchId`	Required branch scope.
`includeChildren` / `includeChildBranches`	Include child branch bookings where relevant.
`activeWithin`	Return bookings active within a time range. Send the parameter twice: start and end.
`intersectTime`	Find bookings intersecting a specific time.
`searchText`	Search booking list text.
`onlyOverdueBookings`	Build overdue booking queues.
`hasRatingDescription`	Review bookings with or without rating feedback.
`directionsRelativeToBranch`	Filter station movement as `INBOUND`, `OUTBOUND`, or `ROUND_TRIP`.

Use GET /bookings/{bookingId} for the detail view before showing high-impact actions such as cancel, approve, deliver, or pickup.

Create A Booking

Use POST /bookings.

Common request fields:

Field	Purpose
`guserId`	User for whom the booking is created.
`branchId`	Start branch/station.
`endBranchId`	End branch/station for one-way station bookings.
`vehicleCategoryId`	Requested vehicle category.
`vehicleId`	Optional concrete vehicle assignment. If provided, the booking can become `DELIVERED`.
`startTime` / `endTime`	Booking window.
`rentalType`	Private/business rental context.
`userGroupId`	Business account/group context. Prefer this over deprecated `userGroupCode`.
`costCenterId`	Cost center for business bookings.
`additions`	Addition codes selected for the booking.
`pricingBundleId`	Optional booking pricing override.
`notes`	Operator notes attached to the booking.
`externalReference`	External system reference.

Use ignoreTimeConstraints=true only for privileged administrative workflows where the operator intentionally overrides time constraints. Normal custom tooling should validate availability and time constraints instead of bypassing them.

Update A Booking

Use PATCH /bookings/{bookingId}.

Updates can change time, vehicle category, vehicle assignment, start/end branch, additions, notes, pricing bundle, business context, and selected metadata. Changing the vehicle category resets previously assigned additions, so tools should ask the operator to confirm additions again after a category change.

When updating time or vehicle/category assignment:

Validate the proposed time window with POST /bookings/availability/validate.
Pass bookingId in the validation request so the current booking is excluded from conflict checks.
Recalculate pricing if the pricing bundle, category, branch, additions, or time window changes.
Re-fetch the booking detail after the update.

Approve Or Decline A Booking

Use PATCH /bookings/{bookingId}/approval.

The request contains a target state and, for declined bookings, a rejectionReason. Operator tools should require a rejection reason when declining a booking and should show the current booking state before submitting approval changes.

Deliver A Vehicle To A Booking

Use POST /bookings/{bookingId}/deliver?vehicleId={vehicleId}.

Delivery associates a concrete vehicle with the booking. The vehicle must match the booking context, such as branch, category, availability, and configured booking rules. A delivery action can fail if the vehicle is not suitable for the booking window or station.

Pick Up A Booking

Use POST /bookings/{bookingId}.

Pickup converts the booking into the next live workflow, usually by associating or starting the rental. It can fail if the booking is in the wrong state, the pickup window is not valid, a rental already exists, the user no longer fulfills start requirements, or the vehicle/branch/category configuration no longer allows pickup.

The rentalAuthOverride query parameter is an administrative override. Expose it only to privileged operator roles and make the override explicit in the UI.

Cancel A Booking

Use POST /bookings/{bookingId}/cancel.

The request can include:

Field	Purpose
`waiveCancellationFee`	Whether the operator waives the cancellation fee.
`reason`	Operator cancellation reason.

Use cancellationInformation from the booking detail to show whether cancellation is allowed and whether a fee may apply. The estimated fee can change by the time cancellation is executed, so treat it as an estimate.

Review Billing

Use GET /bookings/{bookingId}/billing-overview for billing review screens. This is useful for support and finance workflows where the operator needs to understand booking costs, related billing items, or invoice context.

For recurring reporting or analytics, use Data Exports or the data warehouse instead of repeatedly polling booking lists.

Work With Booking Stations

Use booking station endpoints for station-level planning:

Task	Endpoint
List booking stations for a branch	`GET /booking-stations`
List categories at a booking station	`GET /booking-stations/{bookingStationId}/vehicle-categories`
List vehicles expected at a booking station	`GET /booking-stations/{bookingStationId}/vehicles`
List station conflicts	`GET /booking-stations/{bookingStationId}/conflicts`
Validate booking availability	`POST /bookings/availability/validate`

When using activeWithin, pass exactly two date-time values for the range. Station vehicle lists can include vehicles currently assigned to the station and vehicles moving through the station because of inbound or outbound bookings.

Most Relevant APIs

Task	Endpoint
List bookings	`GET /bookings`
Create booking	`POST /bookings`
Get booking detail	`GET /bookings/{bookingId}`
Update booking	`PATCH /bookings/{bookingId}`
Pick up booking	`POST /bookings/{bookingId}`
Approve or decline booking	`PATCH /bookings/{bookingId}/approval`
Cancel booking	`POST /bookings/{bookingId}/cancel`
Deliver vehicle to booking	`POST /bookings/{bookingId}/deliver`
Get booking billing overview	`GET /bookings/{bookingId}/billing-overview`
List booking availability days	`GET /bookings/availability`
Validate booking availability	`POST /bookings/availability/validate`
List available categories for a time window	`GET /bookings/available-categories`
List generally bookable categories	`GET /bookings/bookable-categories`
Get booking utilization	`GET /bookings/utilization`
Calculate booking cooldowns	`GET /bookings/cooldowns`
List booking stations	`GET /booking-stations`
List station vehicle categories	`GET /booking-stations/{bookingStationId}/vehicle-categories`
List station vehicles	`GET /booking-stations/{bookingStationId}/vehicles`
List station conflicts	`GET /booking-stations/{bookingStationId}/conflicts`

Permissions And Settings

Booking workflows are permission-gated and branch-scoped. A user may be able to view bookings in one branch but not create, approve, cancel, deliver, or pick up bookings in another branch.

Common permission considerations:

Workflow	Permission consideration
List and view bookings	Booking read permission for the branch.
Create or update bookings	Booking create/update permission and access to the affected branch, user, category, and vehicle.
Approve or decline bookings	Booking approval permission.
Cancel bookings	Booking cancellation permission, especially when waiving fees.
Deliver or pick up bookings	Booking action permissions, plus vehicle/rental permissions where applicable.
Billing overview	Booking billing, invoice, or finance visibility permissions.
Booking station planning	Booking station and branch visibility permissions.

Use GET /roles/assignments/exists before showing high-impact booking actions, and still handle insufficient-permission errors from the booking endpoint itself.

Settings and configuration that can affect bookings include:

Area	Why it matters
Branch booking settings	Enable booking behavior and define branch-specific booking rules.
Vehicle category configuration	Controls whether a category is bookable and which booking/rental behavior applies.
Booking station configuration	Controls station capacity, opening information, and station-based booking behavior.
Rental requirements	Control whether the user can start or pick up the booking-related rental.
Pricing bundles	Control booking price calculation and cancellation fee behavior.
Additions configuration	Controls which extras can be selected for a booking and how they are priced.
Business account settings	Affect group bookings, cost centers, reasons, and user-group context.

Use GET /settings only when your tool already knows which DASHBOARD or SHARED setting keys it needs. Use /settings-management for administrative settings discovery and configuration workflows.

Implementation Notes For Custom Tools

Always validate booking availability before create/update workflows that change time, category, vehicle, or branch.
Use bookingId in validation requests when updating an existing booking so the booking does not conflict with itself.
Prefer userGroupId over deprecated userGroupCode.
Treat ignoreTimeConstraints, rentalAuthOverride, cancellation-fee waivers, approval state changes, and delivery/pickup actions as privileged operator actions.
Recalculate or re-fetch pricing after changing booking time, vehicle category, branch, additions, or pricing bundle.
Do not assume a booking price is final until the booking/rental is completed and billing is settled.
Do not use booking lists for recurring analytical data replication. Use Data Exports or the data warehouse.
Show time zones clearly in station-based booking tools. Booking stations can expose timeZoneId.
Use booking station conflict endpoints for station planning, but use POST /bookings/availability/validate as the main create/update validation endpoint.
Re-fetch booking detail after writes because state, pricing, cancellation information, annotations, rental links, and cooldowns can change.

Review Notes

The following product decisions are reflected in this guide:

Bookings are documented as scheduled reservations, separate from live rentals and on-demand rentals.
Booking availability validation is documented as the preferred create/update validation path.
Deprecated station availability checks are not recommended for new tooling.
Booking pricing is documented as booking-specific pricing, separate from on-demand rate selector or staircase pricing.
Rental requirements are linked because pickup/start can depend on branch and vehicle-category requirements.
Booking station endpoints are included because station capacity and movement planning are common operator workflows.