Skip to main content
POST
/
reservations
Create a reservation intent
curl --request POST \
  --url https://api.chargeapi.co/v1/reservations \
  --header 'Content-Type: application/json' \
  --data '{
  "connector_type": [
    "CHAdeMO"
  ],
  "driver": "<string>",
  "earliest_start": 123,
  "ideal_end": 123,
  "ideal_start": 123,
  "latest_end": 123,
  "location": {
    "latitude": 123,
    "longitude": 123,
    "radius": 123
  },
  "metadata": {},
  "payment_method": "<string>",
  "vehicle": "<string>"
}'
{
  "id": "<string>",
  "object": "reservation",
  "cancellation_policy": {
    "free_until_before": 123,
    "type": "free_cancellation"
  },
  "charging_station": "<string>",
  "confirmed_at": 123,
  "connector_type": [
    "<string>"
  ],
  "created": 123,
  "currency": "<string>",
  "driver": "<string>",
  "earliest_start": 123,
  "failed_reason": "no_available_connectors",
  "ideal_end": 123,
  "ideal_start": 123,
  "latest_end": 123,
  "location": {
    "latitude": 123,
    "longitude": 123,
    "radius": 123
  },
  "metadata": {},
  "payment_method": "<string>",
  "reservation_fee": 123,
  "reserved_end": 123,
  "reserved_start": 123,
  "status": "pending",
  "updated": 123,
  "vehicle": "<string>"
}

Body

application/json
​
connector_type
enum<string>[]
required

Preferred connector types for charging.

​
driver
string
required

ID of the driver creating the reservation.

​
ideal_end
integer
required

Preferred charging end time (UNIX timestamp).

​
ideal_start
integer
required

Preferred charging start time (UNIX timestamp).

​
location
object
required

Geographic area within which Charge will attempt to assign a station.

​
vehicle
string
required

ID of the vehicle to charge.

​
earliest_start
integer | null

Earliest acceptable charging start time.

​
latest_end
integer | null

Latest acceptable charging end time.

​
metadata
object

Custom key-value pairs for integration needs.

​
payment_method
string | null

PaymentMethod ID for reservation fees.

Response

Returns the newly created Reservation object. Initially, the reservation is in a pending state, indicating your intent. Charge will attempt to confirm the reservation closer to your requested charging window.

​
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.