List available time slots for a date

GET/v2/experiences/{experienceId}/availability/slots

Requires your API key in the X-API-Key header.

Returns slot-level availability for a single date, broken down by option. Every active option of the experience appears in the response (or just one when optionId is passed): options with bookable slots carry them sorted by start time with unavailabilityReason: null; options without carry an empty slots array and a machine-readable reason. Visibility and participant semantics are identical to the dates endpoint.

For experiences synced from an external provider (Bokun/Regiondo/Kompas), the provider's availability for the requested date is refreshed best-effort before computing the response.

Option unavailability reasons

PARTICIPANT_TYPE_MISMATCH — the option disables one of the requested participant types. MAX_PARTICIPANTS_EXCEEDED — no visible variant can hold the requested party. NO_SLOTS — no availability slots exist for the option on this date. SOLD_OUT — slots exist but none has sufficient remaining capacity.

Variants

Each option also lists its visible variants with a per-variant isAvailable flag; the only per-variant reason is MAX_PARTICIPANTS_EXCEEDED (the variant's maxParticipants is below the requested party size).

Discounts

Each bookable slot carries the discount a booking made now would get: the option's early-bird discount when booking far enough in advance (type: EARLY_BIRD) or the best matching scheduled availability discount (type: AVAILABILITY), or null.

Requestbash
curl "https://api.turneo.co/v2/experiences/8e7d6c5b-4a39-4281-90ef-1a2b3c4d5e6f/availability/slots?date=2026-07-14" \
  -H "X-API-Key: <your-api-key>"

Path parameters

  • experienceIdstring (uuid)required

    UUID of the parent experience.

    Example:
    8e7d6c5b-4a39-4281-90ef-1a2b3c4d5e6f

Query parameters

  • datestring (date)required

    The date to check, local to the experience, YYYY-MM-DD.

    Example:
    2026-07-14
  • participantsstring

    Requested party as comma-separated participantTypeId:count pairs (counts must be positive; all type ids must be active types of this experience). When omitted, availability is evaluated for a single participant with no type filtering; the real party is validated at booking time.

    Example:
    a7c53f01-6f9c-4d1c-9c30-1c19a1a5bd44:2,b8d64e12-7a0d-4e2d-8d41-2d2ab2b6ce55:1
  • optionIdstring (uuid)

    Narrow the availability check to a single option. Must be a valid UUID (400 otherwise). The snake_case alias option_id is accepted during migration.

    Example:
    3d3f9c2a-1b2c-4d5e-8f90-a1b2c3d4e5f6
  • restrictedboolean

    Variant visibility filter. false — public variants only; true — restricted (member-only) variants, falling back to public ones when the option has no active restricted variants; omitted — no filtering. Any value other than true is treated as false.

    Example:
    false

Responses

200object

Per-option slot availability for the date.

  • experienceIdstring (uuid)

    The experience id from the URL.

    Example:
    8e7d6c5b-4a39-4281-90ef-1a2b3c4d5e6f
  • datestring (date)

    Echo of the requested date.

    Example:
    2026-07-14
  • optionsmap of object

    Map of option id → availability. Every active (non-custom) option of the experience is present (or only the requested one when optionId is passed). Keys are option UUIDs.

    Child fields
    • slotsobject[]

      Bookable slots sorted by start time. Empty when the option is unavailable — see unavailabilityReason.

      Child fields
      • slotIdstring (uuid)

        The availability slot id — pass it when creating a booking on this slot.

        Example:
        6a5b4c3d-2e1f-4a9b-8c7d-6e5f4a3b2c1d
      • startTimestringnullable

        Local start time, HH:MM:SS. null for DATE_ONLY options (the slot spans the whole day).

        Example:
        10:00:00
      • discountobjectnullable

        Discount a booking made right now would receive on the slot, or null.

        Child fields
        • percentagenumber

          Discount percentage.

          Example:
          15
        • typestring

          EARLY_BIRD — the option's early-bird rule matched (booked far enough in advance); AVAILABILITY — the best matching scheduled option discount.

          Allowed values:
          EARLY_BIRDAVAILABILITY
          Example:
          EARLY_BIRD
    • variantsobject[]

      Visible variants with per-variant availability. Empty when the option was skipped before variant evaluation (PARTICIPANT_TYPE_MISMATCH).

      Child fields
      • variantIdstring (uuid)

        Variant id.

        Example:
        4c9c2ab7-9a1d-4b8a-b6a0-5f2f8d3f7e21
      • namemap of stringnullable

        Multilingual variant name.

      • maxParticipantsintegernullable

        Variant capacity per booking; null means unlimited.

        Example:
        2
      • isAvailableboolean

        Whether this variant can hold the requested party.

        Example:
        false
      • unavailabilityReasonstringnullable

        Why the variant is unavailable — currently only MAX_PARTICIPANTS_EXCEEDED (the party exceeds maxParticipants). null when available.

        Allowed values:
        MAX_PARTICIPANTS_EXCEEDEDnull
        Example:
        MAX_PARTICIPANTS_EXCEEDED
    • unavailabilityReasonstringnullable

      null when the option has bookable slots. Otherwise: PARTICIPANT_TYPE_MISMATCH — the option disables a requested participant type; MAX_PARTICIPANTS_EXCEEDED — no variant fits the party; NO_SLOTS — no slots exist on this date; SOLD_OUT — slots exist but none has capacity.

      Allowed values:
      PARTICIPANT_TYPE_MISMATCHMAX_PARTICIPANTS_EXCEEDEDNO_SLOTSSOLD_OUTnull
Response 200json
{
  "experienceId": "8e7d6c5b-4a39-4281-90ef-1a2b3c4d5e6f",
  "date": "2026-07-14",
  "options": {
    "3d3f9c2a-1b2c-4d5e-8f90-a1b2c3d4e5f6": {
      "slots": [
        {
          "slotId": "6a5b4c3d-2e1f-4a9b-8c7d-6e5f4a3b2c1d",
          "startTime": "10:00:00",
          "discount": {
            "percentage": 15,
            "type": "EARLY_BIRD"
          }
        },
        {
          "slotId": "7b6c5d4e-3f2a-4b8c-9d0e-1f2a3b4c5d6e",
          "startTime": "14:00:00",
          "discount": null
        }
      ],
      "variants": [
        {
          "variantId": "4c9c2ab7-9a1d-4b8a-b6a0-5f2f8d3f7e21",
          "name": {
            "en": "Standard"
          },
          "maxParticipants": 4,
          "isAvailable": true,
          "unavailabilityReason": null
        }
      ],
      "unavailabilityReason": null
    },
    "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b": {
      "slots": [],
      "variants": [],
      "unavailabilityReason": "SOLD_OUT"
    }
  }
}

Errors

400

Validation failed. Inspect errors[].field and errors[].code.

401

Missing or invalid X-API-Key header.

403

The API key is valid but not allowed to perform this action on this resource.

404

The resource does not exist or belongs to another partner (existence is not leaked across partners).

Error body
  • typestring

    Error class.

    Allowed values:
    validation_errorclient_errorserver_error
    Example:
    validation_error
  • errorsobject[]
    Child fields
    • codestring

      Machine-readable error code.

      Example:
      required
    • fieldstringnullable

      Offending field, or null/'general' for non-field errors.

      Example:
      startTime
    • messagestring

      Human-readable message.

      Example:
      This field is required.
Response 400json
{
  "type": "validation_error",
  "errors": [
    {
      "code": "required",
      "field": "startTime",
      "message": "This field is required."
    }
  ]
}