Bookings Module

Introduction

The Bookings module has two main objects and one with a sub object: Booking and BookingLocation. The BookingLocation also has a submodule Calendar object for availability. To make a booking, first a BookingLocation should be published to an eMSP or be requested from the CPO backoffice.

The CPO communicates a BookingLocation to the eMSP. The BookingLocation covers the information per location, and then can either choose to have the possible bookable parking options or provide a list of bookable EVSE UIDs.

Booking State Diagram

A Booking typically follows the following lifecycle:

• A Booking starts in a PENDING state when initially requested by the eMSP.
• From PENDING, the CPO can move the booking to:
  • RESERVED if the booking request is successful.
  • REJECTED if the requested timeslot or booking option isn't available.
  • FAILED if there's an error processing the request.
• From RESERVED, the Booking can transition to:
  • FULFILLED when successfully utilized.
  • CANCELED if the eMSP or CPO cancels the booking.
  • NO_SHOW if the booking is not utilized within the timeframe specified by the booking terms.

                    ┌──────────┐
                    │ PENDING  │
                    └────┬─────┘
                   /     |      \
                  v      v       v
          ┌────────┐ ┌────────┐ ┌──────────┐
          │REJECTED│ │ FAILED │ │ RESERVED │
          └────────┘ └────────┘ └────┬─────┘
                                /    |     \
                               v     v      v
                      ┌────────┐ ┌───────┐ ┌──────────┐
                      │CANCELED│ │NO_SHOW│ │FULFILLED │
                      └────────┘ └───────┘ └──────────┘

17.1.1. Booking Lifecycle from Making to Fulfillment

Steps in a booking as described in "Successfully book a location and make a change to that booking":

17.2.1. Sender Interface

Typically implemented by market roles like: CPO. The Bookings interface can be used to retrieve Bookings, BookingLocations and calendars, but also to request a booking or to change a booking. The interface is split up in BookingLocation with Calendar, and Booking interface.

17.2.1.3. GET BookingLocations

This endpoint returns a list of BookingLocation objects. Each object must contain all required fields. Fields that are not specified may be considered as null values. Any old information that is not specified in the response is considered no longer valid.

{bookings_endpoint_url}/booking_locations

https://www.server.com/ocpi/2.3/bookings/booking_locations/?date_from=2025-01-29T12:00:00&limit=100
https://www.server.com/ocpi/cpo/2.3/bookings/booking_locations/?offset=50&limit=100

Request Parameters

If the optional parameters date_from and/or date_to are provided, only BookingLocations with last_updated between the given date_from (including) and date_to (excluding) will be returned. This request is paginated.

Response Data

17.2.1.4. GET BookingLocation or Calendar

For retrieving a single BookingLocation or Calendar the endpoint is the following:

{bookings_endpoint_url}/booking_locations/{booking_location_id}/{calendar_id}

https://www.server.com/ocpi/cpo/2.3/bookings/booking_locations/BL01
https://www.server.com/ocpi/cpo/2.3/bookings/booking_locations/BL01/23423

URL Parameters

Response Data

17.2.1.5. GET Bookings

This endpoint returns a list of Booking objects. Each object must contain all required fields. Fields that are not specified may be considered as null values. Any old information that is not specified in the response is considered no longer valid.

{bookings_endpoint_url}

https://www.server.com/ocpi/2.3/bookings/?date_from=2025-01-29T12:00:00&limit=100
https://www.server.com/ocpi/cpo/2.3/bookings/?offset=50&limit=100

Request Parameters

If the optional parameters date_from and/or date_to are provided, only Bookings with last_updated between the given date_from (including) and date_to (excluding) will be returned. This request is paginated.

Response Data

17.2.1.6. POST Method

Send a Booking request to book a BookingLocation.

{bookings_endpoint_url}

https://www.server.com/ocpi/cpo/2.3/bookings/

Request Body

Response Data

The response contains the direct response from the Receiver. If however the response is pending, the definite result will be sent async back.

17.2.2. Receiver Interface

Typically implemented by market roles like: eMSP. Bookings and BookingLocation are Client Owned Objects, so the end-points need to contain the required extra fields: party_id and country_code.

{booking_endpoint_url}/{country_code}/{party_id}/booking_locations/{booking_location_id}
{booking_endpoint_url}/{country_code}/{party_id}/booking_locations/{booking_location_id}/{calendar_id}

https://server.com/ocpi/2.3/bookings/NL/INF/booking_locations/LOC1
https://ocpi.server.com/2.3/bookings/SE/VOL/booking_locations/LOC2/3255

{booking_endpoint_url}/{country_code}/{party_id}/{booking_id}

https://www.server.com/ocpi/emsp/2.3/bookings/SE/VOL/BOK213

17.2.2.3. GET BookingLocation Method

If the CPO wants to check the status of a BookingLocation in the eMSP's system, it might GET the object from the eMSP's system for validation purposes. After all, the CPO is the owner of the object, so it would be illogical if the eMSP's system had a different version or was missing the object entirely.

Request Parameters

Response Data

17.2.2.4. PUT Method

New or updated BookingLocation objects are pushed from the CPO to the eMSP.

Request Body

Request Parameters

17.2.2.5. PATCH Method

Same as the PUT method, but only the fields/objects that have to be updated have to be present. Other fields/objects that are not specified as part of the request are considered unchanged. Therefore, this method is not suitable to remove information shared earlier.

PATCH To URL: https://www.server.com/ocpi/emsp/2.3/bookings/bookinglocations/NL/INF/BL0123

{
  "booking_terms": {
    "RFID_auth_required": true,
    "token_groups_supported": false,
    "remote_auth_supported": true,
    "late_stop_allowed": false,
    "overlapping_bookings_allowed": true,
    "booking_terms": "/https://example.com/booking-a-charger"
  },
  "last_updated": "2024-12-05T20:02:13Z"
}

PATCH To URL: https://www.server.com/ocpi/emsp/2.3/bookings/bookinglocations/NL/INF/BL0123/C0123

{
  "step_size": 1,
  "available_timeslots": [{
    "start_from": "2025-03-23T00:00:00Z",
    "end_before": "2025-03-23T08:59:99Z",
    "min_power": 12,
    "max_power": 12,
    "green_power_support": false
  }],
  "last_updated": "2024-12-05T20:02:13Z"
}

17.2.2.6. GET Booking Method

If the CPO wants to check the status of a Booking in the eMSP's system, it might GET the object from the eMSP's system for validation purposes. After all, the CPO is the owner of the object, so it would be illogical if the eMSP's system had a different version or was missing the object entirely.

Request Parameters

Response Data

17.2.2.7. PUT Method (Booking)

New or updated Booking objects are pushed from the CPO to the eMSP.

Request Body

Request Parameters

17.3.1. BookingLocation Object

Each BookingLocation should include either the bookable_parking_option or the evse_uid. One of them is mandatory.

17.3.1.1. Example BookingLocation

This is an example of a booking location. Can be used by any EV Driver as long as his eMSP has a roaming agreement with the CPO, or the Charge Point has an ad-hoc payment possibility.

{
  "country_code": "NL",
  "party_id": "IHO",
  "id": "12345",
  "location_id": "LOC1",
  "evse_uid": "6583",
  "bookable_parking_options": [{
    "evse_position": "LEFT",
    "vehicle_types": ["MOTORCYCLE", "TRUCK_WITH_TRAILER", "SEMI_TRACTOR"],
    "format": "SOCKET",
    "max_vehicle_weight": 5000,
    "max_vehicle_height": 300,
    "max_vehicle_length": 900,
    "max_vehicle_width": 250,
    "parking_space_length": 1000,
    "drive_through": false,
    "restricted_to_type": true,
    "refrigeration_outlet": true
  }],
  "booking_required": true,
  "tariffs": ["32423328", "24091999", "23415239", "12072017"],
  "booking_terms": {
    "RFID_auth_required": true,
    "token_groups_supported": false,
    "remote_auth_supported": true,
    "supported_access_methods": ["ACCESS_CODE", "TOKEN"],
    "change_until_minutes": 200,
    "cancel_until_minutes": 600,
    "change_not_allowed": false,
    "early_start_allowed": true,
    "early_start_time": 20,
    "noshow_timeout": 25,
    "max_power_bookable": 400,
    "late_stop_allowed": false,
    "overlapping_bookings_allowed": true,
    "booking_terms": "/https://server.com/booking-a-charger"
  },
  "calenders": [{
    "id": "CA112",
    "begin_from": "2025-03-23T00:00:00Z",
    "end_before": "2025-03-23T23:59:99Z",
    "step_size": 1,
    "available_timeslots": [{
      "start_from": "2025-03-23T00:00:00Z",
      "end_before": "2025-03-23T08:59:99Z",
      "min_power": 12,
      "max_power": 600,
      "green_power_support": false
    },{
      "start_from": "2025-03-23T12:00:00Z",
      "end_before": "2025-03-23T13:00:00Z",
      "min_power": 12,
      "max_power": 12,
      "green_power_support": false
    }],
    "last_updated": "2024-12-05T20:02:13Z"
  },{
    "id": "CA112",
    "begin_from": "2025-03-23T00:00:00Z",
    "end_before": "2025-03-23T23:59:99Z",
    "step_size": 1,
    "available_timeslots": [{
      "start_from": "2025-03-23T00:00:00Z",
      "end_before": "2025-03-23T08:59:99Z",
      "min_power": 12,
      "max_power": 12,
      "green_power_support": false
    },{
      "start_from": "2025-03-23T12:00:00Z",
      "end_before": "2025-03-23T13:00:00Z",
      "min_power": 12,
      "max_power": 12,
      "green_power_support": false
    }],
    "last_updated": "2024-12-05T20:02:13Z"
  }],
  "last_updated": "2024-12-05T20:02:13Z"
}

17.3.2. Calendar Object

17.3.3. Booking Object

Object used for booking a booking location.

17.4.1. BookingRequest class

17.4.2. BookingTerms class

17.4.3. BookableParkingOptions class

17.4.4. Cancellation class

17.4.5. AccessMethod class

17.4.6. BookingRequestStatus class

17.4.7. Timeslot class

17.4.8. BookingToken class

17.4.9. Bookable class

17.4.10. LocationAccess enum

Describes ways to get access to a reserved charger.

17.4.11. ReservationStatus enum

17.4.12. ReservationRequestStatus enum