Skip to main content

The Reservation object represents a driver's intent to charge their vehicle within a specific time window (ideal_start/ideal_end) and geographic area (location). Initially, a reservation is in a pending state. Charge automatically attempts to assign an available charging station and confirm the reservation approximately 30 minutes before the desired start time. If successful, the reservation status updates to confirmed, locking a connector at the assigned charging station. If no suitable charging station is available, the reservation status changes to failed with a failed_reason. Once charging successfully occurs, the reservation status becomes completed. Reservations can also be cancelled by the driver or automatically expired if unused.

​
id
string
required

Unique identifier for the reservation.

​
object
enum<string>
required

String representing the object's type. Always reservation.

Available options:
reservation
​
created
integer
required

Timestamp when reservation was created.

​
ideal_end
integer
required

Ideal reservation end time (requested by driver).

​
ideal_start
integer
required

Ideal reservation start time (requested by driver).

​
status
enum<string>
required

Current status of the reservation.

  • pending: Created intent, awaiting confirmation.
  • confirmed: Connector reserved successfully.
  • completed: Charging session occurred successfully.
  • cancelled: Cancelled by driver before start.
  • failed: Unable to assign a connector.
  • expired: Reservation window passed without use.
Available options:
pending,
confirmed,
completed,
cancelled,
failed,
expired
​
updated
integer
required

Timestamp when reservation was last updated.

​
cancellation_policy
object

Defines conditions for reservation cancellation.

​
charging_station
string | null

ID of assigned charging station (populated once confirmed).

​
confirmed_at
integer | null

Timestamp when reservation status changed to confirmed.

​
connector_type
string[]

Acceptable connector types for charging.

​
currency
string

ISO currency code for the reservation fee (e.g., usd).

​
driver
string

ID of the driver associated with the reservation.

​
earliest_start
integer | null

Earliest acceptable reservation start time.

​
failed_reason
enum<string> | null

Reason why reservation failed, if applicable.

Available options:
no_available_connectors,
payment_failed,
other
​
latest_end
integer | null

Latest acceptable reservation end time.

​
location
object

Geographic area where reservation is requested.

​
metadata
object

Custom metadata (key-value pairs).

​
payment_method
string

ID of the payment method used for the reservation fee.

​
reservation_fee
integer

Reservation fee amount in smallest currency unit (e.g., cents).

​
reserved_end
integer | null

Finalized end time after confirmation.

​
reserved_start
integer | null

Finalized start time after confirmation.

​
vehicle
string

ID of the vehicle associated with the reservation.