← All guidesAPI Reference

Getting Started with Experiences

The Turneo API provides a single API to search, book and manage experience bookings for in-house and 3rd party external experiences.

Overview

Everything we do boils down to giving guests great experiences, so in this guide we'll follow a guest's journey through a scenario:

Meet the 'Tropical Troop': Tim, Tara, and their tiny treasure Tina. They are visiting Barbados and staying in Jade Beach Resort from October 11th to 17th. They are looking to do a mix of adventurous and relaxing activities during their stay.

To complete this scenario, we'll be:

  1. Searching for experiences
  2. Getting prices and availability for a selected experience
  3. Making a booking (order) for the selected experience

Each step returns an ID, or a set of IDs, you use in the next step.

All requests below use the production base URL https://api.turneo.co and require an X-API-Key header identifying your partner account. See the API reference for the full request/response shapes.

1. Searching for experiences

There are many ways to search for experiences, but the two most typical are:

  • A specific store, set up in Turneo Hub
  • A destination the traveller is in

Both can be combined with date filters.

Searching by store

In Turneo Hub, sellers of experiences (e.g. hotels) can create stores — a curated collection of experiences with their own URL, branding, and analytics. A common integration filters experiences down to those in a store by passing a storeId query parameter:

curl -X GET "https://api.turneo.co/v2/experiences?storeId=123456789" \
     -H "Accept: application/json" \
     -H "X-API-Key: <your-api-key>"

Searching by destination

Instead of a store, you can search by city or country. country matches the meeting point's country exactly; city matches experiences within EXPERIENCE_SEARCH_CITY_RADIUS_KM of the named city (falling back to an exact city match when the city isn't in our geo-location table).

For our Barbados example:

curl -X GET "https://api.turneo.co/v2/experiences?country=Barbados" \
     -H "Accept: application/json" \
     -H "X-API-Key: <your-api-key>"

Date search

To only see experiences with bookable capacity in a given window, add from and until (both required together, YYYY-MM-DD):

curl -X GET "https://api.turneo.co/v2/experiences?country=Barbados&from=2024-10-11&until=2024-10-17" \
     -H "Accept: application/json" \
     -H "X-API-Key: <your-api-key>"

2. Getting options, prices, and availability

Step 1 gives you the id of the experience your guests want to book. In v2, a bookable experience is broken down into options (the v2 replacement for what used to be called "rates") — each option represents a way of booking the experience (e.g. "Shared boat tour" vs. "Private boat tour"), with its own pricing, participant types, and duration.

curl -X GET "https://api.turneo.co/v2/experiences/{experienceId}/options" \
     -H "Accept: application/json" \
     -H "X-API-Key: <your-api-key>"

Replace {experienceId} with the id from step 1. This returns the active options for the experience, each with its pricing tiers, participant types, add-ons, and duration.

Availability is checked separately and gets stale quickly, so always re-check it right before booking. Use the experience's availability endpoints with the date range you're interested in:

curl -X GET "https://api.turneo.co/v2/experiences/{experienceId}/availability/dates?from=2024-10-11&until=2024-10-17" \
     -H "Accept: application/json" \
     -H "X-API-Key: <your-api-key>"

This returns which dates in the range have capacity. To see the bookable time slots (and their availabilitySlotIds) on a specific date, call:

curl -X GET "https://api.turneo.co/v2/experiences/{experienceId}/availability/slots?date=2024-10-12" \
     -H "Accept: application/json" \
     -H "X-API-Key: <your-api-key>"

Both endpoints accept an optional optionId to narrow the check to a single option, and participants (comma-separated participantTypeId:count pairs) to check availability for a specific party size.

Each slot in the response includes an availabilitySlotId, which — together with the option's variantId — is what you'll pass when creating the booking in step 3.

An option's participantTypes describe who can be booked (adult/child/etc. with their own pricing), and its extraFields describe any additional information you must collect at booking time (e.g. dietary restrictions).

3. Making the booking

We're ready to book for Tim and his family. In the Turneo API this is done by creating a booking order.

Orders follow a shopping-cart model with two steps:

  1. Create the order (bookings start ON_HOLD, reserving availability)
  2. Confirm the order (finalizes the bookings)

Order vs. Booking

An order is the parent object you check out in one go. It contains one or more bookings, each corresponding to one availability slot purchased (typically one experience).

Creating an order

Call POST /v2/booking-orders with travelerInformation for the order and one entry per booking you want to make, referencing the variantId and availabilitySlotId from step 2:

curl -X POST "https://api.turneo.co/v2/booking-orders" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "X-API-Key: <your-api-key>" \
     -d '{
           "travelerInformation": {
             "firstName": "Tim",
             "lastName": "Tropical",
             "email": "tim@example.com"
           },
           "bookings": [
             {
               "variantId": "{variantId}",
               "availabilitySlotId": "{availabilitySlotId}",
               "participantCounts": { "{participantTypeId}": 3 }
             }
           ]
         }'

Pay attention to each option's extraFields and participantTypes when building the booking payload — they determine what additional information is required per booking.

(Optional) Add and remove bookings from an order

While an order is still ON_HOLD (not yet confirmed), you can add or remove bookings from it — useful when guests keep adjusting their shopping cart:

  • POST /v2/booking-orders/{id}/add — add more bookings ({"bookings": [...]}, same shape as create)
  • POST /v2/booking-orders/{id}/remove — remove bookings ({"expireBookings": ["bookingId", ...]})

Confirming the purchase

Bookings created above are held ON_HOLD for a limited time (reserving the availability), and are released if not confirmed in time. Typically you'll charge the guest (or record an alternative payment arrangement) before confirming:

curl -X POST "https://api.turneo.co/v2/booking-orders/{orderId}/confirm" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "X-API-Key: <your-api-key>" \
     -d '{}'

This transitions the order's bookings out of ON_HOLD (into PENDING or ACCEPTED, depending on the experience's confirmation settings).

🎉 And that's it — you've made your first booking on Turneo! 🎉

See the API reference for the full set of fields, response shapes, and error cases for every endpoint used above.