Turneo

https://www.turneo.com/developers
Admin
Turneo is an experience booking platform and API that enables hospitality and travel businesses to...
Tokens:28,244
Snippets:223
Trust Score:7.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### GET /v2/experiences response example

Source: https://www.turneo.com/developers/api

Example JSON response for a successful GET /v2/experiences request. Shows a paginated list with count, next, previous, and results array containing experience objects.

```json
{
  "count": 137,
  "next": "https://api.turneo.co/v2/experiences?page=2&page_size=50",
  "previous": null,
  "results": [
    {
      "id": "5f8b8c1e-3f8a-4a1e-9d2b-1c2d3e4f5a6b",
      "name": "Sunset Kayak Tour",
      "description": "Sunset Kayak Tour",
      "highlight": "Sunset Kayak Tour",
      "otherNotes": "Sunset Kayak Tour",
      "code": "KAYAK-01",
      "status": "ACTIVE",
      "organizer": {
        "name": "Acme Tours",
        "partnerId": "acme-tours",
        "phone": "+385911234567",
        "partnerEmail": "hello@acmetours.com",
        "partnerRating": 4.8,
        "partnerReviews": 132,
        "logo": "https://res.cloudinary.com/turneo/image/upload/logo.png",
        "website": "https://acmetours.com",
        "aboutUs": "Family-run kayak outfitter since 2005.",
        "supportEmail": "support@acmetours.com",
        "featureFlags": {}
      },
      "categories": {
        "type": "Water sports"
      },
      "categoryThemes": [
        {
          "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
          "name": "Sunset Kayak Tour",
          "nameDefault": "Family friendly",
          "isDefault": false,
          "description": "Great for kids of all ages."
        }
      ],
      "location": {
        "city": "Split",
        "country": "Croatia",
        "address": "Riva 1",
        "latitude": 43.508,
        "longitude": 16.44,
        "description": "Next to the ferry terminal."
      },
      "meetingPoints": [
        {
          "id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
          "type": "CENTRAL_MEETING_POINT",
          "city": "Split",
          "country": "Croatia",
          "address": "Riva 1",
          "description": "Look for the yellow flag.",
          "latitude": 43.508,
          "longitude": 16.44,
          "timeBeforeStart": 15,
          "title": "Riva promenade"
        }
      ],
      "pickup": {
        "value": "Hotel pickup available",
        "rules": "Within 5 km of the city center only."
      },
      "allowFreePickup": true,
      "duration": {
        "days": 0,
        "hours": 2,
        "minutes": 30
      },
      "videos": [
        "https://youtube.com/watch?v=abc123"
      ],
      "maxPrice": {
        "amount": 79,
        "currency": "EUR",
        "unit": "person"
      },
      "minPrice": {
        "amount": 79,
        "currency": "EUR",
        "unit": "person"
      },
      "languages": "English,German",
      "cutOffTime": 4,
      "refundPolicy": {
        "tiers": [
          {
            "hoursBeforeStart": 48,
            "refundPercentage": 100
          }
        ]
      },
      "supportContact": [
        {
          "type": "email",
          "value": "support@acmetours.com"
        }
      ],
      "travellerTypeScores": {
        "families": 0.9,
        "couples": 0.7
      },
      "availableFrom": "2026-09-01",
      "publishedAt": "2026-04-02T09:15:00Z",
      "commission": 20,
      "commissionSettings": [
        {
          "id": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
          "type": "MARKETPLACE",
          "reseller": "grand-hotel",
          "value": 20
        }
      ],
      "included": [
        {
          "name": "Sunset Kayak Tour",
          "inclusionId": "64a1f0c2e4b0a1b2c3d4e5f6"
        }
      ],
      "excluded": [
        {
          "name": "Sunset Kayak Tour",
          "exclusionId": "64a1f0c2e4b0a1b2c3d4e5f7"
        }
      ],
      "images": [
        {
          "urlHigh": "https://res.cloudinary.com/turneo/image/upload/hi.jpg",
          "urlLow": "https://res.cloudinary.com/turneo/image/upload/lo.jpg",
          "altText": "Kayaks lined up at sunset"
        }
      ],
      "externalLinks": [
        {
          "id": "3f1c2b4d-5e6f-4a1b-8c9d-0e1f2a3b4c5d",
          "type": "EXTERNAL_ID",
          "name": "Bokun activity ID",
          "value": "1189606"
        }
      ],
      "bookingType": "INTERNAL",
      "participantTypes": [
        {
          "id": "6d7e8f9a-0b1c-4d2e-8f3a-4b5c6d7e8f9a",
          "experienceId": "5f8b8c1e-3f8a-4a1e-9d2b-1c2d3e4f5a6b",
          "name": "Sunset Kayak Tour",
          "description": "Sunset Kayak Tour",
          "minAge": 18,
          "maxAge": 99
        }
      ]
    }
  ]
}
```

--------------------------------

### URL with turneoExperience and checkout prefill parameters

Source: https://www.turneo.com/developers/guides/mobile-app-integration

Example URL for opening the Turneo Element directly on a specific experience detail page. Append turneoExperience=<experienceId>_<slug> to the host page URL, and optionally add turneoCheckout_ parameters to prefill checkout fields. The experienceId comes from GET /v2/experiences; the slug is cosmetic.

```text
https://www.yourhotel.com/app/experiences
  ?turneoExperience=8efde4f9-916b-4612-b927-4a4b898183a9_Wine-tasting
  &turneoCheckout_firstName=John
  &turneoCheckout_email=john.smith@example.com
  &turneoCheckout_resellerReference=LOYALTY-48213
```

--------------------------------

### Searching for Experiences

Source: https://www.turneo.com/developers/guides/getting-started

Three curl examples for searching experiences by store, destination, and date range.

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

```

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

```

```bash
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>"

```

--------------------------------

### Create booking order with curl (POST /v2/booking-orders)

Source: https://www.turneo.com/developers/guides/mobile-app-integration

Creates an order with traveler information, resellerReference, and bookings. The order starts ON_HOLD, reserving the slot while the guest pays. Move straight to payment.

```bash
curl -X POST "https://api.turneo.co/v2/booking-orders" \
     -H "Content-Type: application/json" \
     -H "X-API-Key: <your-api-key>" \
     -d '{
           "travelerInformation": {
             "firstName": "John",
             "lastName": "Smith",
             "email": "john.smith@example.com",
             "phone": "+385992101824"
           },
           "resellerReference": "LOYALTY-48213",
           "bookings": [
             {
               "variantId": "<variantId>",
               "availabilitySlotId": "<availabilitySlotId>",
               "participantCounts": { "<participantTypeId>": 2 }
             }
           ]
         }'

```

--------------------------------

### List experiences with curl (GET /v2/experiences)

Source: https://www.turneo.com/developers/guides/mobile-app-integration

Fetches experiences for a store with language parameter. Use 'from' and 'until' to filter by stay dates. Cache the result for a few minutes.

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

```

--------------------------------

### GET /v2/bookings/summary

Source: https://www.turneo.com/developers/api

Retrieves a summary of bookings.

```APIDOC
## GET /v2/bookings/summary

### Description
Retrieves a summary of bookings.

### Method
GET

### Endpoint
/v2/bookings/summary

### Authentication
Requires `x-api-key` and `x-partner-id` headers.

### Response
#### Success Response (200)
- **summary** (object) - The booking summary.

#### Response Example
{
  "summary": {}
}
```

--------------------------------

### GET /v2/experiences with X-API-Key header

Source: https://www.turneo.com/developers/api

Curl command to fetch a paginated list of experiences. Requires a valid X-API-Key header. The response is a paginated list unless nopagination=true is used, which returns a bare array.

```shell
curl https://api.turneo.co/v2/experiences \
  --header 'X-API-Key: YOUR_SECRET_TOKEN'

```

--------------------------------

### GET /v2/experiences

Source: https://www.turneo.com/developers/api

Retrieves a paginated list of experiences. Use the `nopagination` query parameter to return a bare array instead of a paginated response object. Requires a valid X-API-Key header.

```APIDOC
## GET /v2/experiences

### Description
Retrieves a list of experiences. Returns a paginated result by default, or a bare array if `nopagination` is set to true. Requires an API key.

### Method
GET

### Endpoint
/v2/experiences

### Parameters
#### Query Parameters
- **nopagination** (boolean) - Optional - When `true`, returns a bare array of experience objects instead of a paginated response.

#### Authentication Header
- **X-API-Key** (string) - Required - Your secret API token. Must be included in request headers.

### Request Example
```
curl https://api.turneo.co/v2/experiences --header 'X-API-Key: YOUR_SECRET_TOKEN'
```

### Response
#### Success Response (200)
A paginated list of experiences if `nopagination` is not `true`; otherwise, a bare array of experience objects.

#### Error Responses
- **400** - Validation failed. Inspect `errors[].field` and `errors[].code`.
- **401** - Missing or invalid `X-API-Key` header.

#### Response Example (200)
```
{
  "count": 137,
  "next": "https://api.turneo.co/v2/experiences?page=2&page_size=50",
  "previous": null,
  "results": [
    {
      "id": "5f8b8c1e-3f8a-4a1e-9d2b-1c2d3e4f5a6b",
      "name": "Sunset Kayak Tour",
      "description": "Sunset Kayak Tour",
      "highlight": "Sunset Kayak Tour",
      "otherNotes": "Sunset Kayak Tour",
      "code": "KAYAK-01",
      "status": "ACTIVE",
      "organizer": {
        "name": "Acme Tours",
        "partnerId": "acme-tours",
        "phone": "+385911234567",
        "partnerEmail": "hello@acmetours.com",
        "partnerRating": 4.8,
        "partnerReviews": 132,
        "logo": "https://res.cloudinary.com/turneo/image/upload/logo.png",
        "website": "https://acmetours.com",
        "aboutUs": "Family-run kayak outfitter since 2005.",
        "supportEmail": "support@acmetours.com",
        "featureFlags": {}
      },
      "categories": {
        "type": "Water sports"
      },
      "categoryThemes": [
        {
          "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
          "name": "Sunset Kayak Tour",
          "nameDefault": "Family friendly",
          "isDefault": false,
          "description": "Great for kids of all ages."
        }
      ],
      "location": {
        "city": "Split",
        "country": "Croatia",
        "address": "Riva 1",
        "latitude": 43.508,
        "longitude": 16.44,
        "description": "Next to the ferry terminal."
      },
      "meetingPoints": [
        {
          "id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
          "type": "CENTRAL_MEETING_POINT",
          "city": "Split",
          "country": "Croatia",
          "address": "Riva 1",
          "description": "Look for the yellow flag.",
          "latitude": 43.508,
          "longitude": 16.44,
          "timeBeforeStart": 15,
          "title": "Riva promenade"
        }
      ],
      "pickup": {
        "value": "Hotel pickup available",
        "rules": "Within 5 km of the city center only."
      },
      "allowFreePickup": true,
      "duration": {
        "days": 0,
        "hours": 2,
        "minutes": 30
      },
      "videos": [
        "https://youtube.com/watch?v=abc123"
      ],
      "maxPrice": {
        "amount": 79,
        "currency": "EUR",
        "unit": "person"
      },
      "minPrice": {
        "amount": 79,
        "currency": "EUR",
        "unit": "person"
      },
      "languages": "English,German",
      "cutOffTime": 4,
      "refundPolicy": {
        "tiers": [
          {
            "hoursBeforeStart": 48,
            "refundPercentage": 100
          }
        ]
      },
      "supportContact": [
        {
          "type": "email",
          "value": "support@acmetours.com"
        }
      ],
      "travellerTypeScores": {
        "families": 0.9,
        "couples": 0.7
      },
      "availableFrom": "2026-09-01",
      "publishedAt": "2026-04-02T09:15:00Z",
      "commission": 20,
      "commissionSettings": [
        {
          "id": "4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
          "type": "MARKETPLACE",
          "reseller": "grand-hotel",
          "value": 20
        }
      ],
      "included": [
        {
          "name": "Sunset Kayak Tour",
          "inclusionId": "64a1f0c2e4b0a1b2c3d4e5f6"
        }
      ],
      "excluded": [
        {
          "name": "Sunset Kayak Tour",
          "exclusionId": "64a1f0c2e4b0a1b2c3d4e5f7"
        }
      ],
      "images": [
        {
          "urlHigh": "https://res.cloudinary.com/turneo/image/upload/hi.jpg",
          "urlLow": "https://res.cloudinary.com/turneo/image/upload/lo.jpg",
          "altText": "Kayaks lined up at sunset"
        }
      ],
      "externalLinks": [
        {
          "id": "3f1c2b4d-5e6f-4a1b-8c9d-0e1f2a3b4c5d",
          "type": "EXTERNAL_ID",
          "name": "Bokun activity ID",
          "value": "1189606"
        }
      ],
      "bookingType": "INTERNAL",
      "participantTypes": [
        {
          "id": "6d7e8f9a-0b1c-4d2e-8f3a-4b5c6d7e8f9a",
          "experienceId": "5f8b8c1e-3f8a-4a1e-9d2b-1c2d3e4f5a6b",
          "name": "Sunset Kayak Tour",
          "description": "Sunset Kayak Tour",
          "minAge": 18,
          "maxAge": 99
        },
        {
          "id": "7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b",
          "experienceId": "5f8b8c1e-3f8a-4a1e-9d2b-1c2d3e4f5a6b",
          "name": "Child",
          "description": "Child ticket",
          "minAge": 5,
          "maxAge": 17
        }
      ]
    }
  ]
}
```
```

--------------------------------

### GET /v2/activities

Source: https://www.turneo.com/developers/api

Retrieves a list of activity feed events. Visibility mirrors the existing list pages.

```APIDOC
## GET /v2/activities

### Description
Retrieves a list of activity feed events. Visibility mirrors the existing list pages.

### Method
GET

### Endpoint
/v2/activities

### Authentication
Requires `x-api-key` and `x-partner-id` headers.

### Response
#### Success Response (200)
- **activities** (array) - List of activity events.

#### Response Example
{
  "activities": []
}
```

--------------------------------

### GET /v2/booking-orders

Source: https://www.turneo.com/developers/api

Retrieves a list of orders created by the authenticated user.

```APIDOC
## GET /v2/booking-orders

### Description
Retrieves a list of orders created by the authenticated user.

### Method
GET

### Endpoint
/v2/booking-orders

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter by order status (ON_HOLD, BOOKED, EXPIRED).

### Response
#### Success Response (200)
- **orders** (array) - List of orders.

#### Response Example
{
  "orders": [
    {
      "id": "order_123",
      "status": "ON_HOLD"
    }
  ]
}
```

--------------------------------

### Experience object JSON response

Source: https://www.turneo.com/developers/api

Example JSON response for an experience object, showing fields like capacityExempt, options, tags, localized, reviews, and discount. The response is part of a paginated list of experiences; with nopagination=true the body is a bare array of experience objects instead.

```json
"capacityExempt": false,
          "sortOrder": 0,
          "isDefault": true,
          "externalId": "BOKUN-ADULT",
          "isEnabledOnBookableOptions": true
        }
      ],
      "options": [
        {
          "id": "9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
          "status": "ACTIVE",
          "name": "Sunset Kayak Tour",
          "additionalProperty": "anything"
        }
      ],
      "tags": {
        "likelyToSellOut": false,
        "popular": true,
        "exclusive": false,
        "private": "NO"
      },
      "localized": [
        {
          "language": "de",
          "status": "ACTIVE",
          "source": "ORGANIZER"
        }
      ],
      "reviews": {
        "recommendedPercent": 96,
        "rating": 4.8,
        "summary": "Guests consistently praise the guides and the sunset views.",
        "reviews": [
          {
            "rating": 5,
            "reviewText": "Fantastic sunset tour, our guide was brilliant.",
            "reviewerName": "Anna",
            "date": "2026-05-14T18:03:00",
            "source": "OTHER",
            "storeId": "64a1f0c2e4b0a1b2c3d4e5f6",
            "status": "ACCEPTED",
            "insightfulnessScore": 0.87
          }
        ]
      },
      "discount": {
        "percentageAmount": 15,
        "type": "AVAILABILITY"
      },
      "propertyId": "8e9f0a1b-2c3d-4e5f-8a6b-7c8d9e0f1a2b"
    }
  ]
}
```

--------------------------------

### GET /v2/activities/available-filters

Source: https://www.turneo.com/developers/api

Retrieves available filters for activity feed endpoints.

```APIDOC
## GET /v2/activities/available-filters

### Description
Retrieves available filters for activity feed endpoints.

### Method
GET

### Endpoint
/v2/activities/available-filters

### Authentication
Requires `x-api-key` and `x-partner-id` headers.

### Response
#### Success Response (200)
- **filters** (array) - List of available filters.

#### Response Example
{
  "filters": []
}
```

--------------------------------

### GET /experiences

Source: https://www.turneo.com/developers/api

Retrieves a list of experiences filtered by the provided query parameters. Supports filtering by UUIDs, store IDs, element IDs, names, categories, locations, statuses, publication dates, availability windows, organizer details, and more.

```APIDOC
## GET /experiences

### Description
Retrieves a list of experiences filtered by the provided query parameters. Supports filtering by UUIDs, store IDs, element IDs, names, categories, locations, statuses, publication dates, availability windows, organizer details, and more.

### Method
GET

### Endpoint
/experiences

### Parameters
#### Query Parameters
- **ids** (string) - Optional - Comma-separated list of experience UUIDs to fetch. When present, the default ACTIVE-only restriction for non-owned experiences is lifted. Returns 400 when the first value is not a valid UUID.
- **storeId** (string) - Optional - Comma-separated list of store IDs. Restricts results to experiences assigned to those stores (assignments are looked up in the store configuration database).
- **elementId** (string) - Optional - Filter results to experiences belonging to the specified Element(s). When present, results are returned in the sequence configured within each Element — preserving the organizer's hand-curated order across pagination. If multiple Element IDs are supplied, Elements are honoured in the order listed; an experience appearing in more than one Element retains its first position. Experiences the caller cannot access are silently omitted without disrupting the sequence. An explicit `sort` parameter takes precedence over Element order.
- **name** (string) - Optional - Exact name match, checked against every supported language of the multilang name. Partial values will not match — use `nameContains` or `search` for that.
- **nameContains** (string) - Optional - Case-insensitive substring match on the English name only.
- **search** (string) - Optional - Free-text search. Case-insensitive substring match across the multilang name (all languages), category theme names, location city and location country. Whitespace-only terms are ignored.
- **categories** (string) - Optional - Comma-separated list of category names. Each value is matched against the category `type`, the category `theme` list, and custom category-theme default names.
- **country** (string) - Optional - Exact match on `location.country`.
- **city** (string) - Optional - Comma-separated list of cities. Matches experiences whose `location.city` equals one of the values, **or** whose geo-location lies within the configured search radius of a known city with that name (proximity search).
- **location** (string) - Optional - Comma-separated list of cities matched **exactly** against `location.city` — no proximity radius, unlike `city`. Values are trimmed, so `?location=Paris, Rome` works. `location__city` and `meetingPoint__city` are accepted as legacy aliases.
- **status** (string) - Optional - Comma-separated list of experience statuses (`ACTIVE`, `DRAFT`, `INACTIVE`, `CATALOGUE`). Passing this lifts the default ACTIVE-only restriction on non-owned experiences (subject to fencing).
- **publishedAtFrom** (string, date) - Optional - Only experiences first published on or after this date. Must be a plain `YYYY-MM-DD` date — datetimes are rejected with 400.
- **publishedAtUntil** (string, date) - Optional - Only experiences first published on or before this date. Must be a plain `YYYY-MM-DD` date — datetimes are rejected with 400.
- **sort** (string) - Optional - Sort override. Accepts the bracket convention `field[asc|desc]` for `publishedAt`, `createdAt` and `updatedAt` (e.g. `updatedAt[desc]`), plus the legacy forms `publishedAt` / `-publishedAt`. Unrecognized values are silently ignored and the default sort-score ordering applies.
- **from** (string, date) - Optional - Start of an availability window (`YYYY-MM-DD`). Must be passed together with `until` (400 otherwise) and must not be after `until`. Filters to experiences with at least one bookable slot in the window.
- **until** (string, date) - Optional - End of the availability window (`YYYY-MM-DD`). See `from`.
- **organizer__partnerId** (string) - Optional - Comma-separated list of organizer partner IDs to filter by.
- **organizer__partnerType** (string) - Optional - Filter by the organizer's partner type (e.g. `Organizer`, `BOTH`).
- **organizer__name** (string) - Optional - Exact match on the organizer's name.
- **unapproved_reviews** (boolean) - Optional - When `true`, the embedded `reviews` object also includes reviews that have not been approved yet (any status). Default is accepted reviews only.
- **language** (string) - Optional - Language for multilingual fields. Multilang fields resolve to a single string in this language when a complete translation exists, otherwise fall back to English. Default: `en`.
- **showTranslations** (string) - Optional - (Description not provided in source.)

### Request Example
GET /experiences?ids=64a1f0c2e4b0a1b2c3d4e5f6&storeId=64a1f0c2e4b0a1b2c3d4e5f6&elementId=element-123&name=Sunset%20Cruise&nameContains=cruise&search=paris&categories=Day%20trips,Dining&country=France&city=Paris,Rome&location=Paris,%20Rome&status=ACTIVE,DRAFT&publishedAtFrom=2026-01-01&publishedAtUntil=2026-06-30&sort=updatedAt[desc]&from=2026-07-10&until=2026-07-20&organizer__partnerId=partner-abc,partner-def&organizer__partnerType=Organizer&organizer__name=Acme%20Tours&unapproved_reviews=false&language=de

### Response
#### Success Response (200)
- **experiences** (array) - List of experience objects matching the filters.

#### Response Example
{
  "experiences": []
}

#### Error Response (400)
- **error** (string) - Description of the validation error (e.g., invalid UUID, invalid date format, missing `until` when `from` is provided).

```

--------------------------------

### GET /v2/bookings/{id}

Source: https://www.turneo.com/developers/api

Retrieves a single booking by ID. If the booking is outside the caller's scope, it behaves as if it does not exist (404).

```APIDOC
## GET /v2/bookings/{id}

### Description
Retrieves a single booking by ID. If the booking is outside the caller's scope, it behaves as if it does not exist (404).

### Method
GET

### Endpoint
/v2/bookings/{id}

### Path Parameters
- **id** (string) - Required - The booking ID.

### Authentication
Requires `x-api-key` and `x-partner-id` headers.

### Response
#### Success Response (200)
- **id** (string) - The booking ID.
- **status** (string) - The booking status.

#### Response Example
{
  "id": "book_123",
  "status": "PENDING"
}
```

--------------------------------

### Prefill Reservation Date on Booking Page with `turneo_reservationDate`

Source: https://www.turneo.com/developers/guides/adding-turneo-elements

Use `turneo_reservationDate` with format `YYYY-MM-DD` to prefill the reservation date on the booking page. Example URL includes `turneoExperience` and `turneo_reservationDate=2026-07-12`.

```URL
https://www.jadebeachresort.com/experiences?turneoExperience=8efde4f9-916b-4612-b927-4a4b898183a9_Wine-tasting&turneo_reservationDate=2026-07-12
```

--------------------------------

### Get available time slots for a specific date

Source: https://www.turneo.com/developers/guides/getting-started

Returns the bookable time slots and their availabilitySlotId for a specific date. Each slot's availabilitySlotId is used together with the option's variantId when creating a booking.

```bash
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>"
```

--------------------------------

### GET /v2/experiences

Source: https://www.turneo.com/developers/api

Returns a paginated list of experiences visible to the caller. Anonymous and unauthenticated requests see only ACTIVE experiences that are publicly listed; authenticated callers additionally see their own experiences (any status) plus any experiences other organizers have explicitly shared with them.

```APIDOC
## GET /v2/experiences

### Description
Returns a paginated list of experiences visible to the caller. Anonymous and unauthenticated requests see only ACTIVE experiences that are publicly listed; authenticated callers additionally see their own experiences (any status) plus any experiences other organizers have explicitly shared with them.

### Method
GET

### Endpoint
/v2/experiences

### Parameters
#### Query Parameters
- **page** (integer) - Optional - Page number of the paginated result set (1-based). Default: 1. Example: 1.
- **page_size** (integer) - Optional - Number of results per page. Default: 50. Example: 25.
- **nopagination** (boolean) - Optional - When `true`, disables pagination and returns a bare array of experiences instead of the `{count, next, previous, results}` envelope. Currently capped at 500 results as a safety limit. Example: false.
- **id** (string) - Optional - Filter by experience ID. Example: 5f8b8c1e-3f8a-4a1e-9d2b-1c2d3e4f5a6b.

### Response
#### Success Response (200)
- **count** (integer) - Number of results.
- **next** (string) - URL to the next page.
- **previous** (string) - URL to the previous page.
- **results** (array) - List of experience objects.

#### Response Example
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": []
}
```

--------------------------------

### GET /v2/bookings/digest

Source: https://www.turneo.com/developers/api

Retrieves a digest of bookings.

```APIDOC
## GET /v2/bookings/digest

### Description
Retrieves a digest of bookings.

### Method
GET

### Endpoint
/v2/bookings/digest

### Authentication
Requires `x-api-key` and `x-partner-id` headers.

### Response
#### Success Response (200)
- **digest** (object) - The booking digest.

#### Response Example
{
  "digest": {}
}
```

--------------------------------

### Make your first API request

Source: https://www.turneo.com/developers

Use this curl command to authenticate and fetch a list of experiences from the Turneo API.

```bash
curl "https://api.turneo.co/v2/experiences" \
  -H "X-API-Key: <your-api-key>" \
  -H "Accept: application/json"
```

--------------------------------

### GET /v2/bookings/available-filters

Source: https://www.turneo.com/developers/api

Retrieves available filters for booking list endpoints.

```APIDOC
## GET /v2/bookings/available-filters

### Description
Retrieves available filters for booking list endpoints.

### Method
GET

### Endpoint
/v2/bookings/available-filters

### Authentication
Requires `x-api-key` and `x-partner-id` headers.

### Response
#### Success Response (200)
- **filters** (array) - List of available filters.

#### Response Example
{
  "filters": []
}
```

--------------------------------

### Create a booking order via POST /v2/booking-orders

Source: https://www.turneo.com/developers/guides/getting-started

Initializes a booking order with traveler information and specific booking details including variant and availability slot IDs.

```bash
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 }
             }
           ]
         }'
```

--------------------------------

### GET /v2/bookings/{id}/available-emails

Source: https://www.turneo.com/developers/api

Retrieves available email templates for a booking.

```APIDOC
## GET /v2/bookings/{id}/available-emails

### Description
Retrieves available email templates for a booking.

### Method
GET

### Endpoint
/v2/bookings/{id}/available-emails

### Path Parameters
- **id** (string) - Required - The booking ID.

### Authentication
Requires `x-api-key` and `x-partner-id` headers.

### Response
#### Success Response (200)
- **emails** (array) - List of available email templates.

#### Response Example
{
  "emails": []
}
```

--------------------------------

### Fetch options for an experience

Source: https://www.turneo.com/developers/guides/getting-started

Retrieves the active options for a given experience, including pricing, participant types, add-ons, and duration. Replace {experienceId} with the id from the previous step and supply your API key. The response includes variantId used later for booking.

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

--------------------------------

### GET /v2/activities/{activityId}

Source: https://www.turneo.com/developers/api

Retrieves a single activity feed event by ID.

```APIDOC
## GET /v2/activities/{activityId}

### Description
Retrieves a single activity feed event by ID.

### Method
GET

### Endpoint
/v2/activities/{activityId}

### Path Parameters
- **activityId** (string) - Required - The activity event ID.

### Authentication
Requires `x-api-key` and `x-partner-id` headers.

### Response
#### Success Response (200)
- **id** (string) - The activity event ID.
- **type** (string) - The event type.

#### Response Example
{
  "id": "act_123",
  "type": "booking.created"
}
```

--------------------------------

### Host a Turneo Element page for a WebView

Source: https://www.turneo.com/developers/guides/mobile-app-integration

Host this minimal page on your own domain (e.g. https://www.yourhotel.com/app/experiences) and point the WebView at it. Replace <your-element-id> with the id from the Elements tab. The Element is responsive and adapts to the phone's width without further configuration.

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
    <style>
      body { margin: 0; padding: env(safe-area-inset-top) 0 env(safe-area-inset-bottom); }
    </style>
  </head>
  <body>
    <turneo-element element-id="<your-element-id>"></turneo-element>
    <script src="https://widget-turneo.vercel.app/turneo-widget.iife.js"></script>
  </body>
</html>
```

--------------------------------

### Prefill Turneo Checkout Fields via URL Query Parameters

Source: https://www.turneo.com/developers/guides/adding-turneo-elements

URL query parameters such as `turneoCheckout_firstName` prefill the checkout form with known guest data. Use a URL `https://www.jadebeachresort.com/experiences?turneoCheckout_firstName=John&turneoCheckout_lastName=Smith&turneoCheckout_email=john.smith@gmail.com&turneoCheckout_phone=+385992101824&turneoCheckout_resellerReference=TEST_REF_1` to see the checkout form pre-filled.

```URL
https://www.jadebeachresort.com/experiences?turneoCheckout_firstName=John&turneoCheckout_lastName=Smith&turneoCheckout_email=john.smith@gmail.com&turneoCheckout_phone=+385992101824&turneoCheckout_resellerReference=TEST_REF_1
```

--------------------------------

### GET /v2/booking-orders/{id}

Source: https://www.turneo.com/developers/api

Retrieves a specific order by ID. Returns 404 if the order does not belong to the authenticated user.

```APIDOC
## GET /v2/booking-orders/{id}

### Description
Retrieves a specific order by ID. Returns 404 if the order does not belong to the authenticated user.

### Method
GET

### Endpoint
/v2/booking-orders/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The order ID.

### Response
#### Success Response (200)
- **id** (string) - The order ID.
- **bookings** (array) - The bookings in the order.

#### Response Example
{
  "id": "order_123",
  "bookings": [
    {
      "id": "booking_456",
      "status": "ON_HOLD"
    }
  ]
}
```

--------------------------------

### Fetch guest bookings via cURL

Source: https://www.turneo.com/developers/guides/mobile-app-integration

Retrieve bookings for a specific guest using their reseller reference or email. The API returns details like experience names, images, slot times, and booking codes.

```bash
curl -X GET "https://api.turneo.co/v2/bookings?resellerReference=LOYALTY-48213&bookingStatus=PENDING,ACCEPTED&ordering=time" \
     -H "Accept: application/json" \
     -H "X-API-Key: <your-api-key>"
```

--------------------------------

### GET /v2/bookings

Source: https://www.turneo.com/developers/api

Retrieves a list of bookings. The response excludes REMOVED and soft-deleted bookings. Access is scoped to the caller's partner type.

```APIDOC
## GET /v2/bookings

### Description
Retrieves a list of bookings. The response excludes REMOVED and soft-deleted bookings. Access is scoped to the caller's partner type.

### Method
GET

### Endpoint
/v2/bookings

### Authentication
Requires `x-api-key` and `x-partner-id` headers.

### Access Scoping
Resellers see only bookings they sold; organizers see only bookings on their own experiences; BOTH partners see the union.

### Response
#### Success Response (200)
- **bookings** (array) - List of bookings.

#### Response Example
{
  "bookings": []
}
```

--------------------------------

### POST /v2/booking-orders

Source: https://www.turneo.com/developers/api

Creates an order and one or more bookings in ON_HOLD status. Each booking holds its slot for 15 minutes.

```APIDOC
## POST /v2/booking-orders

### Description
Creates an order and one or more bookings in ON_HOLD status. Each booking holds its slot for 15 minutes.

### Method
POST

### Endpoint
/v2/booking-orders

### Parameters
#### Request Body
- **bookings** (array) - Required - List of bookings to create.

### Response
#### Success Response (200)
- **id** (string) - The order ID.
- **bookings** (array) - The created bookings with status ON_HOLD.

#### Response Example
{
  "id": "order_123",
  "bookings": [
    {
      "id": "booking_456",
      "status": "ON_HOLD"
    }
  ]
}
```

--------------------------------

### POST /v2/booking-orders/{id}/bookings

Source: https://www.turneo.com/developers/api

Creates a booking under a specific booking order. The booking is initially set to ON_HOLD, reserved in a shopping cart for approximately 60 minutes.

```APIDOC
## POST /v2/booking-orders/{id}/bookings

### Description
Creates a booking within a booking order. The booking is initially placed in ON_HOLD, reserving capacity on an availability slot for a specific variant.

### Method
POST

### Endpoint
/v2/booking-orders/{id}/bookings

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the booking order.

### Response
#### Success Response (200)
- **booking** (object) - The created booking object containing its ID and current status (ON_HOLD).

```

--------------------------------

### Request German content with language=de

Source: https://www.turneo.com/developers/guides/multi-language-content

Use this curl command to retrieve experience content in German by passing the language=de query parameter. You must include your API key in the X-API-Key header. If German is not available for a resource, English content is returned.

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

```

--------------------------------

### Combine Date Range and Category Filter on Turneo Element

Source: https://www.turneo.com/developers/guides/adding-turneo-elements

You can combine category and date filtering by adding both parameters in one URL. Example: `https://www.jadebeachresort.com/experiences?turneo_startDate=2025-07-10&turneo_endDate=2026-07-15&turneo_categories=Wellness,Adventure`.

```URL
https://www.jadebeachresort.com/experiences?turneo_startDate=2025-07-10&turneo_endDate=2026-07-15&turneo_categories=Wellness,Adventure
```

--------------------------------

### POST /v2/bookings/{id}/accept-alternative

Source: https://www.turneo.com/developers/api

Accepts an alternative for a booking. The booking status will be updated to ACCEPTED.

```APIDOC
## POST /v2/bookings/{id}/accept-alternative

### Description
Accepts an alternative for a booking. The booking status will be updated to ACCEPTED.

### Method
POST

### Endpoint
/v2/bookings/{id}/accept-alternative

### Path Parameters
- **id** (string) - Required - The booking ID.

### Authentication
Requires `x-api-key` and `x-partner-id` headers.

### Response
#### Success Response (200)
- **id** (string) - The booking ID.
- **status** (string) - The new booking status.

#### Response Example
{
  "id": "book_123",
  "status": "ACCEPTED"
}
```

--------------------------------

### POST /v2/bookings/{id}/reviews

Source: https://www.turneo.com/developers/api

Creates a review for a booking. The request body accepts camelCase or snake_case fields.

```APIDOC
## POST /v2/bookings/{id}/reviews

### Description
Creates a review for a booking. The request body accepts camelCase or snake_case fields.

### Method
POST

### Endpoint
/v2/bookings/{id}/reviews

### Path Parameters
- **id** (string) - Required - The booking ID.

### Authentication
Requires `x-api-key` and `x-partner-id` headers.

### Request Body
- **rating** (integer) - Required - The rating (1-5).
- **comment** (string) - Optional - The review comment.

### Request Example
{
  "rating": 5,
  "comment": "Great experience!"
}

### Response
#### Success Response (201)
- **id** (string) - The review ID.
- **bookingId** (string) - The booking ID.

#### Response Example
{
  "id": "rev_123",
  "bookingId": "book_123"
}
```
Tokens:
Raw