Activity bookings
Book a product-type for a date and travellers. Creating a booking places a hold; it does not issue or charge anything with the supplier. You then confirm it to proceed, or cancel to release the hold.
Lifecycle
| status | Meaning |
|---|---|
held | The booking is reserved and the amount is held on your wallet. Nothing is issued yet. |
confirmed | You confirmed the booking; issuance is in progress. |
issued | The booking is issued and a voucher is available. |
cancelled | The booking was cancelled and the hold released. |
Create a booking
Requires the activities:write scope.
Body
| Field | Type | Required | Description |
|---|---|---|---|
product_type_id | string | Yes | The apt_ product-type to book. |
date | string | Yes | Activity date, YYYY-MM-DD. |
timeslot | string | No | Start time from availability, e.g. 09:00. |
travelers.adults | integer | Yes | Number of adults. |
travelers.children | integer | No | Number of children. |
travelers.seniors | integer | No | Number of seniors. |
customer.given_name | string | Yes | Lead customer first name. |
customer.family_name | string | Yes | Lead customer last name. |
customer.email | string | Yes | Contact email. |
customer.phone | string | No | Contact phone. |
client_reference | string | No | Your own reference. |
options | object | Cond. | Answers to the product-type's booking options. Required when the activity has required options. |
options.per_booking[] | array | No | One { "id", "value" } per per-booking option. |
options.per_pax[][] | array | No | An array per traveller (adults, then children, then seniors); each inner array holds that traveller's { "id", "value" } answers. |
Get the option definitions (ids, types, whether required, item choices) from the availability response's booking_options. The id in each answer is the option's id; value is what the guest entered (for a list option, an item's value).
curl -X POST https://api.hermeseus.com/v3/HAPI/activities/bookings \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5f2b8c1a-3e4d-4a6b-9c7e-1d2f3a4b5c6d" \
-d '{
"product_type_id": "apt_88213",
"date": "2026-11-14",
"timeslot": "09:00",
"travelers": { "adults": 2 },
"customer": { "given_name": "Jane", "family_name": "Doe", "email": "jane@example.com" },
"options": {
"per_booking": [
{ "id": "46db421e-5727-46fc-9f2c-10679e026582", "value": "EK202" }
],
"per_pax": [
[ { "id": "543f0e45-bdfe-4dc7-af73-e7fd5eda8246", "value": "zone_1" } ],
[ { "id": "543f0e45-bdfe-4dc7-af73-e7fd5eda8246", "value": "zone_2" } ]
]
}
}'required option is missing — including a per_pax option not answered for every traveller — the request fails with 422 and a message naming the option, e.g. Missing required per-guest booking option: "Full name" (traveller 2). No wallet hold is created. Add-on option prices (an option or item price) are surcharges the guest pays on top of the ticket rates.
Response
{
"object": "activity_booking",
"id": "abk_7Q2F9K",
"status": "held",
"code": "7Q2F9K",
"product_type_id": "apt_88213",
"title": "Old Town Walking Tour — Adult ticket",
"date": "2026-11-14",
"timeslot": "09:00",
"total": { "amount": "58.00", "currency": "USD" },
"breakdown": [
{ "category": "adult", "quantity": 2, "price": { "amount": "29.00", "currency": "USD" } }
],
"customer": { "given_name": "Jane", "family_name": "Doe", "email": "jane@example.com" },
"created_at": "2026-08-27T10:15:00Z"
}Read a booking
Requires activities:read. Returns the activity_booking with its current status.
Confirm a booking
Requires activities:write. Moves a held booking toward issuance. Poll the booking until it becomes issued, then fetch the voucher.
Cancel a booking
Requires activities:write. Cancels the booking and releases the hold; the status becomes cancelled.
List bookings
Requires activities:read. Lists your activity bookings, filterable by status, email, and date range.