Reservation Sync
Use the Get reservation updates for a facility endpoint to get reservations that changed at one facility. This endpoint returns changes made after a time, not reservations with parking dates inside a time range.
Before testing reservation sync, create a test reservation in staging. Then run your first sync with since=1970-01-01T00:00:00Z. The test reservation should appear in the results if it is available to your staging facility.
GET https://integrations.staging.spothero.com/v2/facilities/{facility_id}/reservations?since=1970-01-01T00:00:00Z
Authorization: Bearer <access_token>
Replace {facility_id} with the SpotHero facility ID. The required since parameter is an ISO-8601 timestamp. The endpoint returns reservations modified after that time.
Initial sync
For your first sync, set since to the Unix epoch. This asks for all available reservation changes:
1970-01-01T00:00:00Z
Save your sync position in your system. Do not repeat a full sync each time. The endpoint is rate-limited, and repeated full syncs will quickly use your request allowance.
Incremental sync
For each sync run, send the since timestamp that you saved after the previous successful sync. Request the first page, then follow the exact @next URL until it is null. The URL contains the cursor needed to continue.
Process every reservation from every page. After all pages are processed, find the latest last_modified value among the reservations returned in this sync. Save that timestamp as your new sync position. If no reservations are returned, keep your previous sync position. If a page fails, retry it and do not move the saved position forward until every page is processed.
Set since to the greatest last_modified value returned by the completed sync. Do not set it to the current time or the time you made the API request. Do not use the latest last_modified value in your storage system. Webhook updates may add newer reservation data to your storage, but they must not advance the sync position. Otherwise, the next sync request could skip changes the sync API has not returned yet. If the sync returns no reservations, keep the previous since value.
Example response
The data list contains changed reservations. In this example, the response has two reservations. @next is null, so there are no more pages in this response:
{
"data": [
{
"reservation_id": "3589785",
"facility_id": "cf_01hgh41phpfk8sbdkknw90601s",
"start_date": "2026-06-05T14:36:00Z",
"end_date": "2026-06-10T14:36:00Z",
"max_uses": 1,
"status": "VALID",
"last_modified": "2026-06-05T14:36:12.753623Z",
"payment_info": {
"price": 1200
}
},
{
"reservation_id": "3589790",
"facility_id": "cf_01hgh41phpfk8sbdkknw90601s",
"start_date": "2026-06-06T14:36:00Z",
"end_date": "2026-06-07T14:36:00Z",
"status": "VALID",
"last_modified": "2026-06-05T15:10:00Z",
"payment_info": {
"price": 2400
}
}
],
"@next": null
}
The reservation_id is the unique identifier for a reservation. Use it to recognize the same reservation across sync responses and to refer to that reservation in other SpotHero APIs. A sync can return new reservations as well as changes to reservations you have received before. Use last_modified to see when the reservation data last changed. Prices are in cents, so 1200 means $12.00.
Decide whether to update a reservation
For each reservation in a sync response, compare its last_modified value with the last_modified value you saved for that same reservation. Save the changed reservation only if its last_modified value is later. If it is the same or earlier, keep the version already in your system. This prevents an older copy from replacing newer reservation data.
This comparison is per reservation. Do not compare a reservation's timestamp with the timestamp of a different reservation.
Save the next sync position
Find the greatest last_modified timestamp among all reservations returned in all pages. In the example above, save 2026-06-05T15:10:00Z because it is later than 2026-06-05T14:36:12.753623Z. Use this value as since in the next sync request:
GET https://integrations.staging.spothero.com/v2/facilities/{facility_id}/reservations?since=2026-06-05T15:10:00Z
Authorization: Bearer <access_token>
Get every page
The default page size is 25. You can set page_size from 10 to 100. If @next contains a URL, request that URL to get the next page. Keep following the URL in each response until @next is null. Use each URL exactly as returned; it contains the cursor for the next page. Process all pages before saving your new sync position.
If you enable webhooks, you can reduce how often you poll this endpoint. Keep syncing periodically: webhooks provide faster updates, while sync helps you recover changes missed during an outage. See Webhooks.
Optional reservation fields
The response always includes the basic reservation details. Add one or more projection names to the include parameter to request extra fields. You can separate names with commas or repeat the parameter.
| Projection | Additional response field | Details |
|---|---|---|
license_plate | license_plate | License plate number, state, country, and plate history. |
vehicle | vehicle | Vehicle make, model, and color. |
barcode | barcode | Reservation barcode. |
timestamp | observations | Observed vehicle entry and exit times. |
parker_name | parker.name | Parker's name. |
parker_email | parker.email | Parker's email address. |
parker_phone | parker.phone_number | Parker's phone number. |
oversize_fee | payment_info.oversize_fee, payment_info.oversize_fee_paid | Oversize fee amount and whether it was paid. Amounts are in cents. |
Your account must have access to a projection to receive its fields. If you request a projection your account cannot access, the API ignores it and returns the basic reservation details. Contact your SpotHero integration representative if you need access to a projection.
For example, request license plate and vehicle details:
GET https://integrations.staging.spothero.com/v2/facilities/{facility_id}/reservations?since=1970-01-01T00:00:00Z&include=license_plate,vehicle
Authorization: Bearer <access_token>