POST
/
reservations
curl --request POST \
  --url https://api.chargeapi.co/v1/reservations
{
  "id": null,
  "object": null,
  "cancellation_policy": {
    "type": null,
    "free_until_before": null
  },
  "charging_station": null,
  "connector_type": null,
  "created": null,
  "currency": null,
  "driver": null,
  "location": {
    "latitude": null,
    "longitude": null,
    "radius": null
  },
  "metadata": null,
  "payment_method": null,
  "reservation_fee": null,
  "reserved_start": null,
  "reserved_end": null,
  "status": null,
  "updated": null,
  "vehicle": null
}

Response

200 - application/json
A newly created reservation.

A Reservation represents a driver's intent to charge within a specific time window and geographic area. Reservations are initially virtual and managed by Charge. Around 30 minutes before the reserved window, Charge attempts to assign a real charging station and lock the reservation. This enables advanced scheduling even when underlying CPOs do not support native future reservations.

​
id
string

Unique identifier for the reservation object.

Example:

null

​
object
string

String representing the object’s type. Always reservation.

Example:

null

​
cancellation_policy
object

Defines how and when a reservation can be cancelled without a fee.

​
charging_station
string | null

ID of the assigned charging station once the reservation is locked. May be null until resolved.

Example:

null

​
connector_type
string

Type(s) of connector requested for this reservation (e.g., CCS, CHAdeMO). Can represent fallback options.

Example:

null

​
created
integer

Time at which the reservation was created.

Example:

null

​
currency
string

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

Example:

null

​
driver
string

ID of the driver who initiated the reservation.

Example:

null

​
location
object

Location and radius indicating where the driver intends to charge.

​
metadata
object

Set of key-value pairs for attaching custom structured data to the reservation.

Example:

null

​
payment_method
string

ID of the payment method provided for charging the reservation fee.

Example:

null

​
reservation_fee
integer

Amount charged for creating the reservation, in the smallest currency unit (e.g., cents).

Example:

null

​
reserved_start
integer

Desired start time for the reservation window.

Example:

null

​
reserved_end
integer

Desired end time for the reservation window.

Example:

null

​
status
enum<string>

Current status of the reservation in its lifecycle.

Available options:
pending,
locked,
failed,
cancelled,
expired,
completed
Example:

null

​
updated
integer

Time at which the reservation was last updated.

Example:

null

​
vehicle
string

ID of the vehicle associated with this reservation.

Example:

null