A reservation holds one spot for one vehicle until it arrives. This guide covers how long a hold lasts, how to change or give it up, and what to do when there is no spot to hold. It assumes you have read Your first reservation.
How a hold works
When you reserve, you say when the vehicle will arrive, as arrive_by. The staging area keeps the spot a little longer than that, by its hold_minutes rule. The reservation tells you exactly when the hold runs out:
held_until = arrive_by + hold_minutesAt Nørreport, hold_minutes is 5. A vehicle due at 14:02 has its spot held until 14:07:
{ "id": "res_8f2c41", "object": "reservation", "vehicle_id": "rt-0417", "staging_area": "sa_norreport", "spot": "2", "status": "held", "arrive_by": "2026-11-02T14:02:00Z", "held_until": "2026-11-02T14:07:00Z"}Each staging area sets its own rules. Read them from the staging area before you reserve:
curl https://api.golanoo.com/v1/staging_areas/sa_norreport \ -H "Authorization: Bearer lk_test_..."{ "rules": { "hold_minutes": 5, "book_ahead_minutes": 120, "max_stay_minutes": 45, "max_vehicle_length_m": 5.2 }}Rules can change. When they do, updated_at on the staging area changes too. See Staging areas.
arrive_by has to be in the future, and no more than the staging area's book_ahead_minutes ahead: 120 at Nørreport. Otherwise the call fails with arrive_by_out_of_range.
If the staging area has a max_vehicle_length_m, send your vehicle's length as vehicle_length_m. A longer vehicle fails with vehicle_too_large. An unknown staging_area fails with 404 and not_found, with param set to staging_area.
Running late
If the vehicle will arrive later, or earlier, than you said, change arrive_by. Only a reservation that is still held can be changed.
curl -X PATCH https://api.golanoo.com/v1/reservations/res_8f2c41 \ -H "Authorization: Bearer lk_test_..." \ -H "Idempotency-Key: 7d3a1f9e-4c2b-4a8d-b6e0-1f5c9a2e8d47" \ -H "Content-Type: application/json" \ -d '{ "arrive_by": "2026-11-02T14:10:00Z" }'The reservation comes back with its new arrive_by and held_until:
{ "id": "res_8f2c41", "object": "reservation", "spot": "2", "status": "held", "arrive_by": "2026-11-02T14:10:00Z", "held_until": "2026-11-02T14:15:00Z"}The spot stays the same if it is free at the new time. If no spot is free then, the call fails with no_spot_available and the reservation is unchanged: your vehicle still holds its spot until the old held_until. The same goes for staging_area_closed, if the staging area is closed at the new time. If the reservation is no longer held, the call fails with reservation_not_held. The new arrive_by follows the same rule as when you reserve, or the call fails with arrive_by_out_of_range.
Change arrive_by before the hold runs out. Once it has, there is nothing left to change.
Cancelling
If the vehicle will not come, give the spot up, so another vehicle can have it.
curl -X POST https://api.golanoo.com/v1/reservations/res_8f2c41/cancel \ -H "Authorization: Bearer lk_test_..." \ -H "Idempotency-Key: 3e8b5c2a-9f14-4d7e-a0c6-5b2f8e1d9a73"The reservation comes back with status cancelled and cancellation_reason set to requested.
Only a held reservation can be cancelled. A vehicle that has checked in checks out instead; cancelling it fails with reservation_not_held. See Checking in and out.
A staging area can also close while your vehicle holds a spot there. Then we cancel the reservation for you, with cancellation_reason set to staging_area_closed, and send a reservation.cancelled webhook. That webhook is not sent when you cancel yourself. Its data.alternatives lists other staging areas nearby with room. See When a staging area closes.
When a hold runs out
If the vehicle has not checked in by held_until, the hold runs out and the spot goes to whoever is next. Three things follow:
- The reservation's status becomes
expired. - We send a
reservation.expiredwebhook, if your endpoint asks for it. - Checking in fails with
hold_expired.
{ "id": "evt_1c7e55", "object": "event", "type": "reservation.expired", "api_version": "2026-10-30", "created_at": "2026-11-02T14:07:00Z", "data": { "object": { "id": "res_8f2c41", "object": "reservation", "vehicle_id": "rt-0417", "staging_area": "sa_norreport", "status": "expired", "arrive_by": "2026-11-02T14:02:00Z", "held_until": "2026-11-02T14:07:00Z" } }}An expired reservation stays expired. To wait there after all, reserve again. Setting up the endpoint is in Receiving webhooks.
When you cannot get a spot
If the staging area has no free spot at arrive_by, or is closed then, nothing is held. The call fails with 409 and one of two codes:
no_spot_available: the staging area is full at that time.staging_area_closed: the staging area is closed at that time, or has a planned closure then. See When a staging area closes.
Both come with alternatives: other staging areas nearby with room, in the same shape as Availability. An alternative's distance_m is measured from the staging area you asked for.
{ "error": { "type": "conflict", "code": "no_spot_available", "message": "Nørreport has no free spot at 2026-11-02T14:02:00Z.", "alternatives": [ { "object": "availability", "staging_area": "sa_israels_plads", "name": "Israels Plads", "free_spots": 1, "chance_free": 0.61 } ] }}We do not move your vehicle for you. You choose where it waits: reserve one of the alternatives, or look elsewhere. Branch on code, not on message, which is for people and may change. More on errors is in the API overview.
One reservation per vehicle
A vehicle can have only one active reservation at a time: one that is held or checked_in. Reserving a second one for the same vehicle_id fails with 409 and vehicle_already_reserved.
To move a vehicle to another staging area, cancel its held reservation first, then reserve the new spot. If it is checked in, check it out first.
To find a vehicle's current reservation, list its reservations by status, held or checked_in:
curl "https://api.golanoo.com/v1/reservations?vehicle_id=rt-0417&status=held" \ -H "Authorization: Bearer lk_test_..."