> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ocpplab.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ocpplab.io/_mcp/server. # Create a reservation POST https://api.ocpplab.io/booking/bookings Content-Type: application/json Records a reservation request as PENDING; reserve or reject it next. Retrying with the same ``Idempotency-Key`` returns the first result. Reference: https://docs.ocpplab.io/api-reference/booking/bookings/create ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Headers - `Idempotency-Key` (string, required) — A unique key you choose for this call, e.g. a UUID. Retrying with the same key returns the first result instead of acting twice. ### Body (application/json) This endpoint expects a BookingCreate. - `booking_id` (string, required) - `request_id` (string, required) - `location_id` (string, required) - `period` (BookingPeriodInput, required) — When the reservation may be used. - `authorization_reference` (string, required) - `booking_terms` (BookingTermsInput, required) — Terms accepted for the reservation. - `booking_requests` (list of BookingRequestInput, required) - `role` (enum, required) - Allowed values: `CPO`, `EMSP`, `NAP`, `NSP`, `OTHER`, `PTP`, `SCSP` - `country_code` (string, required) - `party_id` (string, required) - `booking_option` (BookingOption, optional, nullable) — OCPI booking option. The gateway stores the object it received. - `booking_tokens` (list of BookingTokenInput, optional, nullable) - `tariff_ids` (list of string, optional, nullable) - `canceled` (BookingCancel, optional, nullable) — OCPI cancellation object. - `access_information` (list of BookingAccess, optional, nullable) - `last_updated` (datetime, optional, nullable) - `origin` (enum, optional, nullable, default: LOCAL) - Allowed values: `LOCAL`, `REMOTE` - `ocpi_version` (enum, optional, nullable, default: 2.3.0) - Allowed values: `2.1.1`, `2.2.1`, `2.3.0` ## Response ### 201 The created reservation, PENDING. - `id` (integer, required) - `booking_id` (string, required) - `request_id` (string, required) - `location_id` (string, required) - `period` (BookingPeriod, required) — When the reservation may be used. - `reservation_status` (BookingOutReservationStatus, required) - `authorization_reference` (string, required) - `booking_terms` (BookingTerms, required) — Terms accepted for the reservation. - `booking_requests` (list of BookingRequest, required) - `last_updated` (datetime, required) - `role` (BookingOutRole, required) - `origin` (BookingOutOrigin, required) - `organization_id` (string, required) - `country_code` (string, required) - `party_id` (string, required) - `ocpi_version` (BookingOutOcpiVersion, required) - `created_at` (datetime, required) - `updated_at` (datetime, required) - `booking_option` (map from string to any, optional, nullable) - `booking_tokens` (list of BookingToken, optional, nullable) - `tariff_ids` (list of string, optional, nullable) - `canceled` (map from string to any, optional, nullable) - `access_information` (list of BookingAccess, optional, nullable) - `deleted_at` (datetime, optional, nullable) ## Errors ### 401 Unauthorized Error Missing or invalid Bearer token - `detail` (string, required) — Human-readable error message returned by the API. ### 409 Conflict Error Conflicts with an existing row, or the same key was reused for another call - `detail` (string, required) — Human-readable error message returned by the API. ### 422 Unprocessable Entity Error The request does not match the schema - `detail` (list of ValidationError, optional) — One entry per invalid field. ### 429 Too Many Requests Error Gateway rate limit reached; retry after the given seconds - `detail` (string, required) — Human-readable error message returned by the API. ### 502 Bad Gateway Error Gateway unreachable, failing, or misconfigured - `detail` (string, required) — Human-readable error message returned by the API. ### 504 Gateway Timeout Error Gateway timed out - `detail` (string, required) — Human-readable error message returned by the API. ## Types ### BookingPeriodInput When the reservation may be used. - `start_date_time` (datetime, required) - `end_date_time` (datetime, optional, nullable) ### BookingTermsInput Terms accepted for the reservation. - `early_start` (integer, optional, nullable) ### BookingRequestInput One OCPI booking request stored on the reservation. - `request_id` (string, required) ### BookingOption OCPI booking option. The gateway stores the object it received. ### BookingTokenInput Token presented with the reservation. - `uid` (string, optional, nullable) - `type` (string, optional, nullable) - `contract_id` (string, optional, nullable) ### BookingCancel OCPI cancellation object. ### BookingAccess One access instruction stored with the reservation. - `text` (string, optional, nullable) ### BookingPeriod When the reservation may be used. - `start_date_time` (datetime, required) - `end_date_time` (datetime, optional, nullable) ### BookingOutReservationStatus ### BookingTerms Terms accepted for the reservation. - `early_start` (integer, optional, nullable) ### BookingRequest One OCPI booking request stored on the reservation. - `request_id` (string, required) ### BookingOutRole ### BookingOutOrigin ### BookingOutOcpiVersion ### BookingToken Token presented with the reservation. - `uid` (string, optional, nullable) - `type` (string, optional, nullable) - `contract_id` (string, optional, nullable) ### ValidationError Why one field is invalid. - `loc` (list of ValidationErrorLocItems, required) — Where the field is: ``body`` / ``query`` / ``path`` / ``header``, then its name. - `msg` (string, required) — What is wrong, in English. - `type` (string, required) — Machine-readable error code, e.g. ``missing``. - `input` (any, optional) — The value that was sent. - `ctx` (ValidationErrorCtx, optional) — Details of the rule that failed, e.g. `{"le": 200}`. ### ValidationErrorLocItems ### ValidationErrorCtx Details of the rule that failed, e.g. `{"le": 200}`. ## Examples **Request** ```json { "booking_id": "BOOK-2026-10-03-0001", "request_id": "REQ-2026-10-03-0001", "location_id": "LOC-AMS-01", "period": { "start_date_time": "2026-10-03T12:00:00Z", "end_date_time": "2026-10-03T13:00:00Z" }, "authorization_reference": "AUTH-7f3c9a", "booking_terms": { "early_start": 10 }, "booking_requests": [ { "request_id": "REQ-2026-10-03-0001" } ], "role": "CPO", "country_code": "NL", "party_id": "OCP", "booking_tokens": [ { "uid": "04A2B3C4D5E6F7", "type": "RFID", "contract_id": "NL-OCP-C12345678-X" } ], "tariff_ids": [ "TARIFF-AC-STD" ], "access_information": [ { "text": "Barrier opens with your charge card." } ], "last_updated": "2026-10-03T10:00:00Z" } ``` **Response** ```json { "id": 3001, "booking_id": "BOOK-2026-10-03-0001", "request_id": "REQ-2026-10-03-0001", "location_id": "LOC-AMS-01", "period": { "start_date_time": "2026-10-03T12:00:00Z", "end_date_time": "2026-10-03T13:00:00Z" }, "reservation_status": "PENDING", "authorization_reference": "AUTH-7f3c9a", "booking_terms": { "early_start": 10 }, "booking_requests": [ { "request_id": "REQ-2026-10-03-0001" } ], "last_updated": "2026-10-03T10:00:00Z", "role": "CPO", "origin": "LOCAL", "organization_id": "550e8400-e29b-41d4-a716-446655440000", "country_code": "NL", "party_id": "OCP", "ocpi_version": "2.3.0", "created_at": "2026-10-03T10:00:00Z", "updated_at": "2026-10-03T10:00:00Z", "booking_tokens": [ { "uid": "04A2B3C4D5E6F7", "type": "RFID", "contract_id": "NL-OCP-C12345678-X" } ], "tariff_ids": [ "TARIFF-AC-STD" ], "access_information": [ { "text": "Barrier opens with your charge card." } ] } ``` **SDK Code** ```python import requests url = "https://api.ocpplab.io/booking/bookings" payload = { "booking_id": "BOOK-2026-10-03-0001", "request_id": "REQ-2026-10-03-0001", "location_id": "LOC-AMS-01", "period": { "start_date_time": "2026-10-03T12:00:00Z", "end_date_time": "2026-10-03T13:00:00Z" }, "authorization_reference": "AUTH-7f3c9a", "booking_terms": { "early_start": 10 }, "booking_requests": [{ "request_id": "REQ-2026-10-03-0001" }], "role": "CPO", "country_code": "NL", "party_id": "OCP", "booking_tokens": [ { "uid": "04A2B3C4D5E6F7", "type": "RFID", "contract_id": "NL-OCP-C12345678-X" } ], "tariff_ids": ["TARIFF-AC-STD"], "access_information": [{ "text": "Barrier opens with your charge card." }], "last_updated": "2026-10-03T10:00:00Z" } headers = { "Idempotency-Key": "7d3f2a9e-5b1c-4e8a-9f0d-2c6b8e1a4f70", "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.ocpplab.io/booking/bookings'; const options = { method: 'POST', headers: { 'Idempotency-Key': '7d3f2a9e-5b1c-4e8a-9f0d-2c6b8e1a4f70', Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: '{"booking_id":"BOOK-2026-10-03-0001","request_id":"REQ-2026-10-03-0001","location_id":"LOC-AMS-01","period":{"start_date_time":"2026-10-03T12:00:00Z","end_date_time":"2026-10-03T13:00:00Z"},"authorization_reference":"AUTH-7f3c9a","booking_terms":{"early_start":10},"booking_requests":[{"request_id":"REQ-2026-10-03-0001"}],"role":"CPO","country_code":"NL","party_id":"OCP","booking_tokens":[{"uid":"04A2B3C4D5E6F7","type":"RFID","contract_id":"NL-OCP-C12345678-X"}],"tariff_ids":["TARIFF-AC-STD"],"access_information":[{"text":"Barrier opens with your charge card."}],"last_updated":"2026-10-03T10:00:00Z"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.ocpplab.io/booking/bookings" payload := strings.NewReader("{\n \"booking_id\": \"BOOK-2026-10-03-0001\",\n \"request_id\": \"REQ-2026-10-03-0001\",\n \"location_id\": \"LOC-AMS-01\",\n \"period\": {\n \"start_date_time\": \"2026-10-03T12:00:00Z\",\n \"end_date_time\": \"2026-10-03T13:00:00Z\"\n },\n \"authorization_reference\": \"AUTH-7f3c9a\",\n \"booking_terms\": {\n \"early_start\": 10\n },\n \"booking_requests\": [\n {\n \"request_id\": \"REQ-2026-10-03-0001\"\n }\n ],\n \"role\": \"CPO\",\n \"country_code\": \"NL\",\n \"party_id\": \"OCP\",\n \"booking_tokens\": [\n {\n \"uid\": \"04A2B3C4D5E6F7\",\n \"type\": \"RFID\",\n \"contract_id\": \"NL-OCP-C12345678-X\"\n }\n ],\n \"tariff_ids\": [\n \"TARIFF-AC-STD\"\n ],\n \"access_information\": [\n {\n \"text\": \"Barrier opens with your charge card.\"\n }\n ],\n \"last_updated\": \"2026-10-03T10:00:00Z\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Idempotency-Key", "7d3f2a9e-5b1c-4e8a-9f0d-2c6b8e1a4f70") req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.ocpplab.io/booking/bookings") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Idempotency-Key"] = '7d3f2a9e-5b1c-4e8a-9f0d-2c6b8e1a4f70' request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"booking_id\": \"BOOK-2026-10-03-0001\",\n \"request_id\": \"REQ-2026-10-03-0001\",\n \"location_id\": \"LOC-AMS-01\",\n \"period\": {\n \"start_date_time\": \"2026-10-03T12:00:00Z\",\n \"end_date_time\": \"2026-10-03T13:00:00Z\"\n },\n \"authorization_reference\": \"AUTH-7f3c9a\",\n \"booking_terms\": {\n \"early_start\": 10\n },\n \"booking_requests\": [\n {\n \"request_id\": \"REQ-2026-10-03-0001\"\n }\n ],\n \"role\": \"CPO\",\n \"country_code\": \"NL\",\n \"party_id\": \"OCP\",\n \"booking_tokens\": [\n {\n \"uid\": \"04A2B3C4D5E6F7\",\n \"type\": \"RFID\",\n \"contract_id\": \"NL-OCP-C12345678-X\"\n }\n ],\n \"tariff_ids\": [\n \"TARIFF-AC-STD\"\n ],\n \"access_information\": [\n {\n \"text\": \"Barrier opens with your charge card.\"\n }\n ],\n \"last_updated\": \"2026-10-03T10:00:00Z\"\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.ocpplab.io/booking/bookings") .header("Idempotency-Key", "7d3f2a9e-5b1c-4e8a-9f0d-2c6b8e1a4f70") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"booking_id\": \"BOOK-2026-10-03-0001\",\n \"request_id\": \"REQ-2026-10-03-0001\",\n \"location_id\": \"LOC-AMS-01\",\n \"period\": {\n \"start_date_time\": \"2026-10-03T12:00:00Z\",\n \"end_date_time\": \"2026-10-03T13:00:00Z\"\n },\n \"authorization_reference\": \"AUTH-7f3c9a\",\n \"booking_terms\": {\n \"early_start\": 10\n },\n \"booking_requests\": [\n {\n \"request_id\": \"REQ-2026-10-03-0001\"\n }\n ],\n \"role\": \"CPO\",\n \"country_code\": \"NL\",\n \"party_id\": \"OCP\",\n \"booking_tokens\": [\n {\n \"uid\": \"04A2B3C4D5E6F7\",\n \"type\": \"RFID\",\n \"contract_id\": \"NL-OCP-C12345678-X\"\n }\n ],\n \"tariff_ids\": [\n \"TARIFF-AC-STD\"\n ],\n \"access_information\": [\n {\n \"text\": \"Barrier opens with your charge card.\"\n }\n ],\n \"last_updated\": \"2026-10-03T10:00:00Z\"\n}") .asString(); ``` ```php request('POST', 'https://api.ocpplab.io/booking/bookings', [ 'body' => '{ "booking_id": "BOOK-2026-10-03-0001", "request_id": "REQ-2026-10-03-0001", "location_id": "LOC-AMS-01", "period": { "start_date_time": "2026-10-03T12:00:00Z", "end_date_time": "2026-10-03T13:00:00Z" }, "authorization_reference": "AUTH-7f3c9a", "booking_terms": { "early_start": 10 }, "booking_requests": [ { "request_id": "REQ-2026-10-03-0001" } ], "role": "CPO", "country_code": "NL", "party_id": "OCP", "booking_tokens": [ { "uid": "04A2B3C4D5E6F7", "type": "RFID", "contract_id": "NL-OCP-C12345678-X" } ], "tariff_ids": [ "TARIFF-AC-STD" ], "access_information": [ { "text": "Barrier opens with your charge card." } ], "last_updated": "2026-10-03T10:00:00Z" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', 'Idempotency-Key' => '7d3f2a9e-5b1c-4e8a-9f0d-2c6b8e1a4f70', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.ocpplab.io/booking/bookings"); var request = new RestRequest(Method.POST); request.AddHeader("Idempotency-Key", "7d3f2a9e-5b1c-4e8a-9f0d-2c6b8e1a4f70"); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"booking_id\": \"BOOK-2026-10-03-0001\",\n \"request_id\": \"REQ-2026-10-03-0001\",\n \"location_id\": \"LOC-AMS-01\",\n \"period\": {\n \"start_date_time\": \"2026-10-03T12:00:00Z\",\n \"end_date_time\": \"2026-10-03T13:00:00Z\"\n },\n \"authorization_reference\": \"AUTH-7f3c9a\",\n \"booking_terms\": {\n \"early_start\": 10\n },\n \"booking_requests\": [\n {\n \"request_id\": \"REQ-2026-10-03-0001\"\n }\n ],\n \"role\": \"CPO\",\n \"country_code\": \"NL\",\n \"party_id\": \"OCP\",\n \"booking_tokens\": [\n {\n \"uid\": \"04A2B3C4D5E6F7\",\n \"type\": \"RFID\",\n \"contract_id\": \"NL-OCP-C12345678-X\"\n }\n ],\n \"tariff_ids\": [\n \"TARIFF-AC-STD\"\n ],\n \"access_information\": [\n {\n \"text\": \"Barrier opens with your charge card.\"\n }\n ],\n \"last_updated\": \"2026-10-03T10:00:00Z\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Idempotency-Key": "7d3f2a9e-5b1c-4e8a-9f0d-2c6b8e1a4f70", "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "booking_id": "BOOK-2026-10-03-0001", "request_id": "REQ-2026-10-03-0001", "location_id": "LOC-AMS-01", "period": [ "start_date_time": "2026-10-03T12:00:00Z", "end_date_time": "2026-10-03T13:00:00Z" ], "authorization_reference": "AUTH-7f3c9a", "booking_terms": ["early_start": 10], "booking_requests": [["request_id": "REQ-2026-10-03-0001"]], "role": "CPO", "country_code": "NL", "party_id": "OCP", "booking_tokens": [ [ "uid": "04A2B3C4D5E6F7", "type": "RFID", "contract_id": "NL-OCP-C12345678-X" ] ], "tariff_ids": ["TARIFF-AC-STD"], "access_information": [["text": "Barrier opens with your charge card."]], "last_updated": "2026-10-03T10:00:00Z" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.ocpplab.io/booking/bookings")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```