Bookings API: Lifecycle Management for Vehicle Bookings

The Bookings API is the central workflow engine of KaroKar’s B2B2C mobility marketplace. A booking represents a corporate organisation’s request to reserve a vendor-owned vehicle for a named employee over a defined date range. Every state change is driven through a strict set of allowed transitions, guarded by per-permission decorators, and broadcasts a domain event so downstream modules — availability, assignment, and billing — can react without tight coupling. All endpoints live under the PermissionGuard; callers must supply a valid JWT and hold the required permission for each operation.

All requests require an Authorization: Bearer <token> header. Tokens are issued by the authentication service and encode the caller’s permissions.

State Transitions

The table below shows every legal transition. Attempting any other transition returns a DomainException with code INVALID_BOOKING_TRANSITION.

From \ To	REQUESTED	APPROVED	REJECTED	ASSIGNED	ACTIVE	COMPLETED	TERMINATED	CANCELLED
DRAFT	✅
REQUESTED	—	✅	✅					✅
APPROVED	—	—		✅				✅
ASSIGNED	—	—		—	✅			✅
ACTIVE	—	—		—	—	✅	✅

COMPLETED, TERMINATED, REJECTED, and CANCELLED are terminal states — no further transitions are permitted.

POST /bookings

Create a new booking in DRAFT status. The draft is not yet visible to the vendor; call PATCH /bookings/:id/submit to send it. Required permission: booking.create

Request Body

vehicleId

string (UUID)

required

UUID of the vehicle being booked.

vendorOrganizationId

string (UUID)

required

UUID of the vendor organisation that owns the vehicle.

corporateOrganizationId

string (UUID)

required

UUID of the corporate organisation making the booking request.

requestedBy

string (UUID)

required

UUID of the user (employee or fleet manager) who initiated the request.

startDate

string (ISO 8601 date-time)

required

Inclusive start date-time for the booking period, e.g. "2025-09-01T08:00:00Z".

endDate

string (ISO 8601 date-time)

required

Inclusive end date-time for the booking period, e.g. "2025-09-30T17:00:00Z".

Response

Returns the newly created Booking with status: "DRAFT".

string (UUID)

Unique identifier for the booking, auto-generated.

vehicleId

string (UUID)

UUID of the booked vehicle.

vendorOrganizationId

string (UUID)

UUID of the vendor organisation.

corporateOrganizationId

string (UUID)

UUID of the corporate organisation.

requestedBy

string (UUID)

UUID of the requesting user.

startDate

string (ISO 8601)

Booking start date-time.

endDate

string (ISO 8601)

Booking end date-time.

status

BookingStatus

Always DRAFT on creation.

createdAt

string (ISO 8601)

Record creation timestamp.

updatedAt

string (ISO 8601)

Last update timestamp.

Example

curl -X POST http://localhost:3000/bookings \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "vehicleId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "vendorOrganizationId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "corporateOrganizationId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "requestedBy": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "startDate": "2025-09-01T08:00:00Z",
    "endDate": "2025-09-30T17:00:00Z"
  }'

GET /bookings/:id

Retrieve a single booking by its UUID. No permission is required beyond a valid authentication token. Required permission: none

Path Parameters

string (UUID)

required

UUID of the booking to retrieve.

Response

Returns the Booking object, or null if not found. Fields are identical to the POST /bookings response above.

Example

curl http://localhost:3000/bookings/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <token>"

PATCH /bookings/:id/submit

Submit a DRAFT booking to the vendor for review. Transitions the status from DRAFT → REQUESTED and emits a BookingRequested domain event that notifies downstream listeners (e.g. the availability module). Required permission: booking.create

Path Parameters

string (UUID)

required

UUID of the booking to submit.

Request Body

No request body required.

Response

Returns the updated Booking with status: "REQUESTED".

Errors

HTTP	Code	Condition
404	—	Booking not found
422	`INVALID_BOOKING_TRANSITION`	Booking is not in `DRAFT` status

Example

curl -X PATCH http://localhost:3000/bookings/a1b2c3d4-e5f6-7890-abcd-ef1234567890/submit \
  -H "Authorization: Bearer <token>"

PATCH /bookings/:id/approve

Approve a booking that is in REQUESTED status. Transitions the status to APPROVED and emits a BookingApproved event. Downstream listeners create an availability record in RESERVED state. Required permission: booking.approve

Path Parameters

string (UUID)

required

UUID of the booking to approve.

Request Body

notes

string

Optional free-text notes from the approver (e.g. conditions or references).

Response

Returns the updated Booking with status: "APPROVED".

Errors

HTTP	Code	Condition
403	—	Caller lacks `booking.approve` permission
404	—	Booking not found
422	`INVALID_BOOKING_TRANSITION`	Booking is not in `REQUESTED` status

Example

curl -X PATCH http://localhost:3000/bookings/a1b2c3d4-e5f6-7890-abcd-ef1234567890/approve \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"notes": "Approved subject to valid insurance certificate."}'

PATCH /bookings/:id/reject

Reject a booking in REQUESTED status. Transitions to REJECTED, which is a terminal state. Emits a BookingRejected event. Required permission: booking.approve

Path Parameters

string (UUID)

required

UUID of the booking to reject.

Request Body

No request body required.

Response

Returns the updated Booking with status: "REJECTED".

REJECTED is a terminal state. A rejected booking cannot be resubmitted or transitioned to any other status.

Errors

HTTP	Code	Condition
403	—	Caller lacks `booking.approve` permission
404	—	Booking not found
422	`INVALID_BOOKING_TRANSITION`	Booking is not in `REQUESTED` status

Example

curl -X PATCH http://localhost:3000/bookings/a1b2c3d4-e5f6-7890-abcd-ef1234567890/reject \
  -H "Authorization: Bearer <token>"

PATCH /bookings/:id/assign

Assign an employee to an APPROVED booking. Transitions the booking from APPROVED → ASSIGNED, emits a BookingAssigned event, and triggers creation of an Assignment record. Availability transitions from RESERVED → ALLOCATED. Required permission: booking.approve

Path Parameters

string (UUID)

required

UUID of the booking to assign.

Request Body

employeeId

string (UUID)

required

UUID of the employee to be assigned to this booking.

Response

Returns the updated Booking with status: "ASSIGNED".

The Assignment record is created automatically in response to the BookingAssigned event. You can query it via GET /assignments/:id once the event is processed.

Errors

HTTP	Code	Condition
403	—	Caller lacks `booking.approve` permission
404	—	Booking not found
422	`INVALID_BOOKING_TRANSITION`	Booking is not in `APPROVED` status

Example

curl -X PATCH http://localhost:3000/bookings/a1b2c3d4-e5f6-7890-abcd-ef1234567890/assign \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"employeeId": "e5f6a7b8-c9d0-1234-efab-345678901234"}'

PATCH /bookings/:id/activate

Activate an ASSIGNED booking, marking the employee-vehicle handover as having taken effect. Transitions from ASSIGNED → ACTIVE and emits a BookingActivated event. Required permission: booking.approve

Path Parameters

string (UUID)

required

UUID of the booking to activate.

Request Body

No request body required.

Response

Returns the updated Booking with status: "ACTIVE".

Errors

HTTP	Code	Condition
403	—	Caller lacks `booking.approve` permission
404	—	Booking not found
422	`INVALID_BOOKING_TRANSITION`	Booking is not in `ASSIGNED` status

Example

curl -X PATCH http://localhost:3000/bookings/a1b2c3d4-e5f6-7890-abcd-ef1234567890/activate \
  -H "Authorization: Bearer <token>"

PATCH /bookings/:id/complete

Mark an ACTIVE booking as successfully completed at end of the rental period. Transitions from ACTIVE → COMPLETED, emits a BookingCompleted event, and triggers release of the vehicle’s availability record. Required permission: booking.approve

Path Parameters

string (UUID)

required

UUID of the booking to complete.

Request Body

No request body required.

Response

Returns the updated Booking with status: "COMPLETED".

COMPLETED is a terminal state. No further transitions are possible once a booking is completed.

Errors

HTTP	Code	Condition
403	—	Caller lacks `booking.approve` permission
404	—	Booking not found
422	`INVALID_BOOKING_TRANSITION`	Booking is not in `ACTIVE` status

Example

curl -X PATCH http://localhost:3000/bookings/a1b2c3d4-e5f6-7890-abcd-ef1234567890/complete \
  -H "Authorization: Bearer <token>"

PATCH /bookings/:id/cancel

Cancel a booking that has not yet reached an active or terminal state. Valid from REQUESTED, APPROVED, or ASSIGNED. Emits a BookingCancelled event; any existing availability reservation is released. Required permission: booking.cancel

Path Parameters

string (UUID)

required

UUID of the booking to cancel.

Request Body

No request body required.

Response

Returns the updated Booking with status: "CANCELLED".

CANCELLED is a terminal state. Cancellation is not available from ACTIVE — use the terminate endpoint instead.

Errors

HTTP	Code	Condition
403	—	Caller lacks `booking.cancel` permission
404	—	Booking not found
422	`INVALID_BOOKING_TRANSITION`	Booking is in `DRAFT`, `ACTIVE`, `COMPLETED`, `TERMINATED`, `REJECTED`, or `CANCELLED`

Example

curl -X PATCH http://localhost:3000/bookings/a1b2c3d4-e5f6-7890-abcd-ef1234567890/cancel \
  -H "Authorization: Bearer <token>"

PATCH /bookings/:id/terminate

Forcibly end an ACTIVE booking before its natural completion date. This is the only route from ACTIVE to a non-COMPLETED terminal state. The call creates a BookingTermination record capturing the reason, actor, and timestamp, then emits a BookingTerminated event. Required permission: booking.terminate

Path Parameters

string (UUID)

required

UUID of the booking to terminate.

Request Body

reason

TerminationReason (enum)

required

The reason for early termination. Must be one of the TerminationReason values listed below.

terminatedBy

string (UUID)

required

UUID of the user or system actor performing the termination.

notes

string

Optional free-text notes providing additional context for the termination.

TerminationReason Enum

Value	Description
`VEHICLE_BREAKDOWN`	The vehicle suffered a mechanical or technical failure.
`ACCIDENT`	The vehicle was involved in an accident.
`VENDOR_RECALL`	The vendor recalled the vehicle for operational reasons.
`CORPORATE_RECALL`	The corporate organisation recalled the vehicle or the assignment.
`EMPLOYEE_EXIT`	The assigned employee left the organisation or had their access revoked.
`COMPLIANCE_VIOLATION`	A compliance or policy rule was breached.
`INSURANCE_EXPIRED`	The vehicle’s or driver’s insurance lapsed during the booking.
`ADMIN_ACTION`	An administrator terminated the booking for platform-level reasons.
`OTHER`	None of the above categories apply; use `notes` to describe.

Response

Returns the updated Booking with status: "TERMINATED". A BookingTermination record is created separately and contains the following fields:

string (UUID)

Unique identifier of the termination record.

bookingId

string (UUID)

UUID of the booking that was terminated.

reason

TerminationReason

Enum value indicating why the booking was terminated.

terminatedBy

string (UUID)

UUID of the actor who triggered the termination.

terminatedAt

string (ISO 8601)

Timestamp at which the termination was recorded.

notes

string | null

Optional supplementary notes; null if not provided.

Errors

HTTP	Code	Condition
403	—	Caller lacks `booking.terminate` permission
404	—	Booking not found
422	`INVALID_BOOKING_TRANSITION`	Booking is not in `ACTIVE` status

Example

curl -X PATCH http://localhost:3000/bookings/a1b2c3d4-e5f6-7890-abcd-ef1234567890/terminate \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "EMPLOYEE_EXIT",
    "terminatedBy": "f6a7b8c9-d0e1-2345-fabc-456789012345",
    "notes": "Employee resigned effective 2025-09-15."
  }'

Overview

Identity

Fleet

Operations

Documentation Index

​State Transitions

​POST /bookings

​Request Body

​Response

​Example

​GET /bookings/:id

​Path Parameters

​Response

​Example

​PATCH /bookings/:id/submit

​Path Parameters

​Request Body

​Response

​Errors

​Example

​PATCH /bookings/:id/approve

​Path Parameters

​Request Body

​Response

​Errors

​Example

​PATCH /bookings/:id/reject

​Path Parameters

​Request Body

​Response

​Errors

​Example

​PATCH /bookings/:id/assign

​Path Parameters

​Request Body

​Response

​Errors

​Example

​PATCH /bookings/:id/activate

​Path Parameters

​Request Body

​Response

​Errors

​Example

​PATCH /bookings/:id/complete

​Path Parameters

​Request Body

​Response

​Errors

​Example

​PATCH /bookings/:id/cancel

​Path Parameters

​Request Body

​Response

​Errors

​Example

​PATCH /bookings/:id/terminate

​Path Parameters

​Request Body

​TerminationReason Enum

​Response

​Errors

​Example

Build docs developers (and LLMs) love

State Transitions

POST /bookings

Request Body

Response

Example

GET /bookings/:id

Path Parameters

Response

Example

PATCH /bookings/:id/submit

Path Parameters

Request Body

Response

Errors

Example

PATCH /bookings/:id/approve

Path Parameters

Request Body

Response

Errors

Example

PATCH /bookings/:id/reject

Path Parameters

Request Body

Response

Errors

Example

PATCH /bookings/:id/assign

Path Parameters

Request Body

Response

Errors

Example

PATCH /bookings/:id/activate

Path Parameters

Request Body

Response

Errors

Example

PATCH /bookings/:id/complete

Path Parameters

Request Body

Response

Errors

Example

PATCH /bookings/:id/cancel

Path Parameters

Request Body

Response

Errors

Example

PATCH /bookings/:id/terminate

Path Parameters

Request Body

TerminationReason Enum

Response

Errors

Example