AI experience recommendations for a guest

GET/v2/experiences/experience_recommendations

Works without an API key; send X-API-Key to act as your partner account.

Returns AI-generated experience recommendations for a guest of a store, with an explanatory text per recommendation. Used for personalized storefront and pre-arrival recommendations.

Guest resolution

Pass guestId directly, or pass email — when guestId is absent the guest is looked up by exact email match. If neither resolves, recommendations are computed without guest personalization.

Store resolution

storeId may be passed as a query parameter or as the x-store-id header; one of the two is required (400 otherwise).

Degradation

When AI recommendations are disabled on the environment, the store's top experiences are returned with an empty recommendationText. When the AI call fails, the error is captured and the endpoint still returns 200 with an empty recommendation. from/until values that fail to parse are silently ignored.

The response echoes the request's query parameters (except name and email) as top-level keys alongside recommendationText, experiences and experienceExplanations.

Requestbash
curl "https://api.turneo.co/v2/experiences/experience_recommendations" \
  -H "X-API-Key: <your-api-key>"

Query parameters

  • storeIdstring

    Store to recommend from. Falls back to the x-store-id header; one of the two is required.

    Example:
    64a1f0c2e4b0a1b2c3d4e5f6
  • resellerIdstring

    Reseller (hotel) partner ID, used as additional personalization context.

    Example:
    reseller-123
  • guestIdstring

    Guest UUID to personalize for. Takes precedence over email.

    Example:
    0d9f4a3e-6a7b-4c1d-8e2f-3a4b5c6d7e8f
  • emailstring (email)

    Guest email; used to resolve the guest when guestId is absent (exact match). Never echoed back in the response.

    Example:
    guest@example.com
  • languagestring

    Language for the recommendation text and localized fields.

    Default:
    en
    Example:
    en
  • fromstring (date-time)

    Start of the guest's stay / date window (ISO 8601). Unparseable values are ignored.

    Example:
    2026-05-01T10:00:00Z
  • untilstring (date-time)

    End of the guest's stay / date window (ISO 8601). Unparseable values are ignored.

    Example:
    2026-05-03T10:00:00Z
  • groupstring

    Free-text description of the travel party.

    Example:
    2 adults, 1 child
  • interestsstring

    Free-text guest interests to steer the recommendation.

    Example:
    wellness,food

Responses

200object

Recommendations plus echoed request parameters.

  • recommendationTextstring

    Conversational recommendation text generated for the guest. Empty string when AI recommendations are disabled or the AI call failed.

    Example:
    Based on your love of the outdoors, we picked these for your stay.
  • experiencesobject[]

    Recommended experiences in recommendation order.

    Child fields
    • idstring (uuid)

      Experience UUID.

      Example:
      5f8b8c1e-3f8a-4a1e-9d2b-1c2d3e4f5a6b
    • namestring or map of string

      Multilingual text field. Stored as an object keyed by language code (en, de, it, es, fr, hr, sl, pt, zh, zh-hant, ja, ko, ru; machine translations are stored under <lang>_auto keys internally). On read it is returned as a single string resolved for the requested language (falling back to English when the object is not consistently translated), or as the full per-language object when showTranslations=true is passed. On write, either a plain string (stored as English) or a partial per-language object is accepted.

      Accepted shapes
      • Either string

      • Or map of string

    • descriptionstring or map of string

      Multilingual text field. Stored as an object keyed by language code (en, de, it, es, fr, hr, sl, pt, zh, zh-hant, ja, ko, ru; machine translations are stored under <lang>_auto keys internally). On read it is returned as a single string resolved for the requested language (falling back to English when the object is not consistently translated), or as the full per-language object when showTranslations=true is passed. On write, either a plain string (stored as English) or a partial per-language object is accepted.

      Accepted shapes
      • Either string

      • Or map of string

    • highlightstring or map of string

      Multilingual text field. Stored as an object keyed by language code (en, de, it, es, fr, hr, sl, pt, zh, zh-hant, ja, ko, ru; machine translations are stored under <lang>_auto keys internally). On read it is returned as a single string resolved for the requested language (falling back to English when the object is not consistently translated), or as the full per-language object when showTranslations=true is passed. On write, either a plain string (stored as English) or a partial per-language object is accepted.

      Accepted shapes
      • Either string

      • Or map of string

    • otherNotesstring or map of string

      Multilingual text field. Stored as an object keyed by language code (en, de, it, es, fr, hr, sl, pt, zh, zh-hant, ja, ko, ru; machine translations are stored under <lang>_auto keys internally). On read it is returned as a single string resolved for the requested language (falling back to English when the object is not consistently translated), or as the full per-language object when showTranslations=true is passed. On write, either a plain string (stored as English) or a partial per-language object is accepted.

      Accepted shapes
      • Either string

      • Or map of string

    • noReservationNotestring or map of string

      Multilingual text field. Stored as an object keyed by language code (en, de, it, es, fr, hr, sl, pt, zh, zh-hant, ja, ko, ru; machine translations are stored under <lang>_auto keys internally). On read it is returned as a single string resolved for the requested language (falling back to English when the object is not consistently translated), or as the full per-language object when showTranslations=true is passed. On write, either a plain string (stored as English) or a partial per-language object is accepted.

      Accepted shapes
      • Either string

      • Or map of string

    • codestringnullable

      Optional internal reference code of the organizer.

      Example:
      KAYAK-01
    • statusstring

      Lifecycle status. Only ACTIVE experiences are visible to other partners by default.

      Allowed values:
      ACTIVEDRAFTINACTIVECATALOGUE
      Example:
      ACTIVE
    • experienceTypestring

      EXPERIENCE is bookable through options and slots. RETAIL is a retail product and VOUCHER a gift voucher; both sell from SKUs instead (see the Retail group) and have no options, slots or participant types.

      Allowed values:
      EXPERIENCERETAILVOUCHER
      Example:
      EXPERIENCE
    • organizerobject

      Embedded summary of the organizer (owner) of the experience.

      Child fields
      • namestring

        Organizer display name.

        Example:
        Acme Tours
      • partnerIdstring

        Organizer's public partner ID.

        Example:
        acme-tours
      • phonestringnullable

        Contact phone number.

        Example:
        +385911234567
      • partnerEmailstring (email)

        Organizer's email address.

        Example:
        hello@acmetours.com
      • partnerRatingnumber (double)nullable

        Aggregate partner rating.

        Example:
        4.8
      • partnerReviewsintegernullable

        Number of reviews contributing to the partner rating.

        Example:
        132
      • logostring (uri)nullable

        Organizer logo URL.

        Example:
        https://res.cloudinary.com/turneo/image/upload/logo.png
      • websitestring (uri)nullable

        Organizer website.

        Example:
        https://acmetours.com
      • aboutUsstringnullable

        Organizer self-description.

        Example:
        Family-run kayak outfitter since 2005.
      • supportEmailstring (email)nullable

        Dedicated support email, when different from the main address.

        Example:
        support@acmetours.com
      • featureFlagsobject

        Feature flags enabled for this organizer.

    • categoriesobjectnullable

      Category assignment, e.g. {"type": "Water sports", "theme": [...]}.

    • categoryThemesobject[]

      Custom category themes attached to the experience.

      Child fields
      • idstring (uuid)

        Category theme ID.

        Example:
        2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e
      • namestring or map of string

        Multilingual text field. Stored as an object keyed by language code (en, de, it, es, fr, hr, sl, pt, zh, zh-hant, ja, ko, ru; machine translations are stored under <lang>_auto keys internally). On read it is returned as a single string resolved for the requested language (falling back to English when the object is not consistently translated), or as the full per-language object when showTranslations=true is passed. On write, either a plain string (stored as English) or a partial per-language object is accepted.

        Accepted shapes
        • Either string

        • Or map of string

      • nameDefaultstring

        Default (untranslated) name of the theme.

        Example:
        Family friendly
      • isDefaultboolean

        Whether this is one of the partner's default themes.

        Example:
        false
      • descriptionstringnullable

        Optional description of the theme.

        Example:
        Great for kids of all ages.
    • locationobjectnullable

      Where the experience takes place. Coordinates drive geo search and the local timezone.

      Child fields
      • citystring

        City name. Required (with country and coordinates) while the experience is ACTIVE.

        Example:
        Split
      • countrystring

        Country name.

        Example:
        Croatia
      • addressstringnullable

        Street address.

        Example:
        Riva 1
      • latitudenumber (double)

        Latitude in decimal degrees.

        Example:
        43.508
      • longitudenumber (double)

        Longitude in decimal degrees.

        Example:
        16.44
      • descriptionstringnullable

        Free-text directions or notes about the location.

        Example:
        Next to the ferry terminal.
    • meetingPointobjectnullabledeprecated

      Deprecated single meeting point — use meetingPoints instead.

    • meetingPointsobject[]

      All meeting points of the experience.

      Child fields
      • idstring (uuid)

        Meeting point ID. Include on update to modify an existing point.

        Example:
        7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d
      • typestringnullable

        Meeting point type (e.g. CENTRAL_MEETING_POINT).

        Example:
        CENTRAL_MEETING_POINT
      • citystringnullable

        City of the meeting point.

        Example:
        Split
      • countrystringnullable

        Country of the meeting point.

        Example:
        Croatia
      • addressstringnullable

        Street address.

        Example:
        Riva 1
      • descriptionstringnullable

        How to find the guide / extra instructions.

        Example:
        Look for the yellow flag.
      • latitudenumber (double)

        Latitude in decimal degrees.

        Example:
        43.508
      • longitudenumber (double)

        Longitude in decimal degrees.

        Example:
        16.44
      • timeBeforeStartintegernullable

        Minutes before the start time the traveler should arrive.

        Example:
        15
      • titlestringnullable

        Short display title of the meeting point.

        Example:
        Riva promenade
    • pickupobjectnullable

      Pickup configuration for the experience.

      Child fields
      • valuestring

        Pickup offering (free-form configuration value).

        Example:
        Hotel pickup available
      • rulesstring

        Rules or conditions attached to pickup.

        Example:
        Within 5 km of the city center only.
    • allowFreePickupboolean

      Whether the traveler may enter a free-form pickup location.

      Example:
      true
    • durationobjectnullable

      Duration split into days/hours/minutes. On experience reads this is computed from the first active, non-custom option that defines a duration — null when no active option has one.

      Child fields
      • daysinteger

        Whole days component.

        Example:
        0
      • hoursinteger

        Hours component.

        Example:
        2
      • minutesinteger

        Minutes component.

        Example:
        30
    • ratingobjectnullabledeprecated

      Deprecated legacy rating blob — use reviews instead.

    • videosstring (uri)[]

      Video URLs (max 20). Always an array, never null.

    • maxPriceobjectnullable

      A price boundary condition (used by maxPrice / minPrice).

      Child fields
      • amountnumber (double)

        Monetary amount over every active variant, members-only included.

        Example:
        79
      • freeOfChargeboolean

        True when every variant in scope is free. Present on minPrice only.

        Example:
        false
      • publicobjectnullable

        Same boundary over public variants only (restricted=false). null when no public variant is priced; absent until the experience is recomputed.

        Child fields
        • amountnumber (double)
          Example:
          99
        • unitstringnullable

          Pricing unit the amount applies to (e.g. per person).

          Example:
          Person
        • freeOfChargeboolean

          Present on minPrice scopes only.

          Example:
          false
      • privateobjectnullable

        Same boundary over what a restricted=true viewer can book: an option's members-only variants when it has any, else its public ones. null when nothing priced qualifies; absent until the experience is recomputed.

        Child fields
        • amountnumber (double)
          Example:
          99
        • unitstringnullable

          Pricing unit the amount applies to (e.g. per person).

          Example:
          Person
        • freeOfChargeboolean

          Present on minPrice scopes only.

          Example:
          false
      • currencystring

        ISO 4217 currency code.

        Example:
        EUR
      • unitstringnullable

        Pricing unit the amount applies to (e.g. per person).

        Example:
        person
    • minPriceobjectnullable

      A price boundary condition (used by maxPrice / minPrice).

      Child fields
      • amountnumber (double)

        Monetary amount over every active variant, members-only included.

        Example:
        79
      • freeOfChargeboolean

        True when every variant in scope is free. Present on minPrice only.

        Example:
        false
      • publicobjectnullable

        Same boundary over public variants only (restricted=false). null when no public variant is priced; absent until the experience is recomputed.

        Child fields
        • amountnumber (double)
          Example:
          99
        • unitstringnullable

          Pricing unit the amount applies to (e.g. per person).

          Example:
          Person
        • freeOfChargeboolean

          Present on minPrice scopes only.

          Example:
          false
      • privateobjectnullable

        Same boundary over what a restricted=true viewer can book: an option's members-only variants when it has any, else its public ones. null when nothing priced qualifies; absent until the experience is recomputed.

        Child fields
        • amountnumber (double)
          Example:
          99
        • unitstringnullable

          Pricing unit the amount applies to (e.g. per person).

          Example:
          Person
        • freeOfChargeboolean

          Present on minPrice scopes only.

          Example:
          false
      • currencystring

        ISO 4217 currency code.

        Example:
        EUR
      • unitstringnullable

        Pricing unit the amount applies to (e.g. per person).

        Example:
        person
    • languagesstringnullable

      Comma-separated languages the experience is conducted in.

      Example:
      English,German
    • cutOffTimeinteger

      Latest possible booking, in hours before the start time.

      Example:
      4
    • refundPolicyobjectnullable

      Tiered refund policy. Tiers are evaluated by hours remaining before the experience start; the matching tier's percentage is refunded on cancellation.

      Child fields
      • tiersobject[]

        Refund tiers, typically ordered from most to least generous.

        Child fields
        • hoursBeforeStartinteger

          Minimum hours before start for this tier to apply.

          Example:
          48
        • refundPercentageinteger

          Percentage of the price refunded in this tier (0-100).

          Example:
          100
    • supportContactobject[]nullable

      Support contacts overriding the organizer defaults, as {type, value} pairs.

      Child fields
      • typestring

        Contact channel (email, phone, whatsapp).

        Example:
        email
      • valuestring

        The address / number.

        Example:
        support@acmetours.com
    • travellerTypeScoresobjectnullable

      AI-computed suitability scores per traveler type.

    • availableFromstring (date)nullable

      When the experience has no bookable future availability, the date we expect it to become available again; null when it is currently available.

      Example:
      2026-09-01
    • publishedAtstring (date-time)nullable

      When the experience was (last) activated. null for never-published drafts.

      Example:
      2026-04-02T09:15:00Z
    • commissioninteger

      Commission percentage that applies to the requesting partner — their private reseller rate when one exists, the marketplace rate otherwise, and 0 for organizers selling their own experience (Hub requests see the marketplace rate).

      Example:
      20
    • commissionSettingsobject[]nullable

      On the public shape, only populated (with a single row) when the requesting partner has a private reseller commission on this experience; otherwise null. Owners see the complete list.

      Child fields
      • idstring (uuid)

        Commission row ID. Submit on update to edit in place; omit to create.

        Example:
        4c5d6e7f-8a9b-4c0d-9e1f-2a3b4c5d6e7f
      • typestring

        Whether this is the default marketplace rate or a per-reseller override.

        Allowed values:
        MARKETPLACERESELLER
        Example:
        MARKETPLACE
      • resellerstringnullable

        Partner ID of the reseller this row applies to. Must be null/absent for MARKETPLACE rows.

        Example:
        grand-hotel
      • valueinteger

        Commission percentage.

        Example:
        20
    • includedobject[]

      What the price includes.

      Child fields
      • namestring or map of string

        Multilingual text field. Stored as an object keyed by language code (en, de, it, es, fr, hr, sl, pt, zh, zh-hant, ja, ko, ru; machine translations are stored under <lang>_auto keys internally). On read it is returned as a single string resolved for the requested language (falling back to English when the object is not consistently translated), or as the full per-language object when showTranslations=true is passed. On write, either a plain string (stored as English) or a partial per-language object is accepted.

        Accepted shapes
        • Either string

        • Or map of string

      • inclusionIdstring

        Stable identifier of the inclusion (auto-generated when omitted on create). On update, submit it to edit the row in place; rows whose ID is missing from the submitted list are deleted.

        Example:
        64a1f0c2e4b0a1b2c3d4e5f6
    • excludedobject[]

      What the price excludes.

      Child fields
      • namestring or map of string

        Multilingual text field. Stored as an object keyed by language code (en, de, it, es, fr, hr, sl, pt, zh, zh-hant, ja, ko, ru; machine translations are stored under <lang>_auto keys internally). On read it is returned as a single string resolved for the requested language (falling back to English when the object is not consistently translated), or as the full per-language object when showTranslations=true is passed. On write, either a plain string (stored as English) or a partial per-language object is accepted.

        Accepted shapes
        • Either string

        • Or map of string

      • exclusionIdstring

        Stable identifier of the exclusion; same update semantics as inclusionId.

        Example:
        64a1f0c2e4b0a1b2c3d4e5f7
    • imagesobject[]

      Experience photos.

      Child fields
      • urlHighstring (uri)

        High-resolution image URL (Cloudinary URLs are normalized on write).

        Example:
        https://res.cloudinary.com/turneo/image/upload/hi.jpg
      • urlLowstring (uri)nullable

        Low-resolution/thumbnail image URL.

        Example:
        https://res.cloudinary.com/turneo/image/upload/lo.jpg
      • altTextstringnullable

        Accessibility alt text for the image.

        Example:
        Kayaks lined up at sunset
    • externalLinksobject[]

      Links to external systems (external IDs, booking links).

      Child fields
      • idstring (uuid)

        Link ID.

        Example:
        3f1c2b4d-5e6f-4a1b-8c9d-0e1f2a3b4c5d
      • typestring

        Link type (e.g. EXTERNAL_ID, BOOKING_LINK).

        Example:
        EXTERNAL_ID
      • namestring

        Display label for the link. May be blank.

        Example:
        Bokun activity ID
      • valuestring

        The URL or external identifier.

        Example:
        1189606
    • bookingTypestring

      EXTERNAL when a BOOKING_LINK external link exists (booked off-platform), else INTERNAL.

      Allowed values:
      INTERNALEXTERNAL
      Example:
      INTERNAL
    • participantTypesobject[]

      Active participant types, ordered by sortOrder.

      Child fields
      • idstring (uuid)

        Participant type ID.

        Example:
        6d7e8f9a-0b1c-4d2e-8f3a-4b5c6d7e8f9a
      • experienceIdstring (uuid)

        ID of the owning experience.

        Example:
        5f8b8c1e-3f8a-4a1e-9d2b-1c2d3e4f5a6b
      • namestring or map of string

        Multilingual text field. Stored as an object keyed by language code (en, de, it, es, fr, hr, sl, pt, zh, zh-hant, ja, ko, ru; machine translations are stored under <lang>_auto keys internally). On read it is returned as a single string resolved for the requested language (falling back to English when the object is not consistently translated), or as the full per-language object when showTranslations=true is passed. On write, either a plain string (stored as English) or a partial per-language object is accepted.

        Accepted shapes
        • Either string

        • Or map of string

      • descriptionstring or map of string

        Multilingual text field. Stored as an object keyed by language code (en, de, it, es, fr, hr, sl, pt, zh, zh-hant, ja, ko, ru; machine translations are stored under <lang>_auto keys internally). On read it is returned as a single string resolved for the requested language (falling back to English when the object is not consistently translated), or as the full per-language object when showTranslations=true is passed. On write, either a plain string (stored as English) or a partial per-language object is accepted.

        Accepted shapes
        • Either string

        • Or map of string

      • minAgeintegernullable

        Minimum age for this participant type.

        Example:
        18
      • maxAgeintegernullable

        Maximum age for this participant type.

        Example:
        99
      • capacityExemptboolean

        When true, participants of this type do not count toward slot capacity.

        Example:
        false
      • sortOrderinteger

        Display order (ascending).

        Example:
        0
      • isDefaultboolean

        True for the auto-created Adult/Child/Infant types (cannot be deleted).

        Example:
        true
      • externalIdstringnullable

        Provider-side identifier for externally synced participant types.

        Example:
        BOKUN-ADULT
      • isEnabledOnBookableOptionsboolean

        True when this type is offered on at least one option a guest can actually book going forward (active, non-custom option with a future bookable availability slot that does not disable this type).

        Example:
        true
    • optionsobject[]

      Only present on retrieve when includeOptions=1 is passed — absent otherwise (including on list responses). Same item shape and filtering as the /options sub-endpoint.

      Child fields
      • idstring (uuid)

        Option ID.

        Example:
        9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f
      • statusstring

        Option status. Embedded lists default to ACTIVE options only.

        Allowed values:
        DRAFTACTIVEINACTIVE
        Example:
        ACTIVE
      • namestring or map of string

        Multilingual text field. Stored as an object keyed by language code (en, de, it, es, fr, hr, sl, pt, zh, zh-hant, ja, ko, ru; machine translations are stored under <lang>_auto keys internally). On read it is returned as a single string resolved for the requested language (falling back to English when the object is not consistently translated), or as the full per-language object when showTranslations=true is passed. On write, either a plain string (stored as English) or a partial per-language object is accepted.

        Accepted shapes
        • Either string

        • Or map of string

    • tagsobjectnullable

      Computed marketing tags. exclusive/private are recalculated from the current options and allowedPartners on every read; the remaining flags come from stored data.

      Child fields
      • likelyToSellOutboolean

        Whether the experience is flagged as likely to sell out.

        Example:
        false
      • popularboolean

        Whether the experience is flagged as popular.

        Example:
        true
      • exclusiveboolean

        True when the experience is shared with exactly one partner.

        Example:
        false
      • privatestring

        Private-group availability across active options — NO (no private options), YES (mix of private and shared), ONLY_PRIVATE (all options are private).

        Allowed values:
        NOYESONLY_PRIVATE
        Example:
        NO
    • localizedobject[]nullable

      Translation completeness per language, or null when nothing is translated. Non-owners only see complete (ACTIVE) languages; the owner also sees incomplete (DRAFT) ones.

      Child fields
      • languagestring

        2-letter language code.

        Example:
        de
      • statusstring

        ACTIVE when every translatable field across the experience, inclusions, category themes, participant types and active options/variants/add-ons is translated; DRAFT (owner-only) when a partial translation exists.

        Allowed values:
        ACTIVEDRAFT
        Example:
        ACTIVE
      • sourcestring

        Whether the translation is fully machine-generated or contains organizer-authored text.

        Allowed values:
        AIORGANIZER
        Example:
        ORGANIZER
    • reviewsobjectnullable

      Aggregated traveler reviews. null when the experience has no (visible) reviews. By default only ACCEPTED reviews are included; pass unapproved_reviews=true to include the rest. Reviews are ordered by rating, then insightfulness.

      Child fields
      • recommendedPercentinteger

        Percentage of visible reviews rated 3 stars or higher.

        Example:
        96
      • ratingnumber (double)

        Average rating across visible reviews, rounded to one decimal.

        Example:
        4.8
      • summarystringnullable

        AI-generated summary of the reviews, when available.

        Example:
        Guests consistently praise the guides and the sunset views.
      • reviewsobject[]

        The individual reviews.

        Child fields
        • ratinginteger

          Star rating (1-5).

          Example:
          5
        • reviewTextstringnullable

          Review text, translated to the requested language when a translation exists.

          Example:
          Fantastic sunset tour, our guide was brilliant.
        • reviewerNamestringnullable

          Reviewer display name; falls back to the booking's traveler first name.

          Example:
          Anna
        • datestring

          Review date (ISO 8601).

          Example:
          2026-05-14T18:03:00
        • sourcestring

          RESELLER when the requesting partner posted the review themselves, OTHER otherwise.

          Example:
          OTHER
        • storeIdstringnullable

          Store the review was posted from — only exposed for the poster's own reviews, null otherwise.

          Example:
          64a1f0c2e4b0a1b2c3d4e5f6
        • statusstring

          Moderation status. Non-ACCEPTED reviews appear only with unapproved_reviews=true.

          Allowed values:
          PENDINGACCEPTEDREJECTED
          Example:
          ACCEPTED
        • insightfulnessScorenumber (double)nullable

          AI-scored insightfulness, used for ordering reviews.

          Example:
          0.87
    • discountobjectnullable

      The single highest currently valid discount across all active, non-custom options — either an availability discount or an early-bird discount. null when no discount applies or when availability comes from an external provider.

      Child fields
      • percentageAmountnumber (double)

        Discount percentage.

        Example:
        15
      • typestring

        Which kind of discount is the highest.

        Allowed values:
        AVAILABILITYEARLY_BIRD
        Example:
        AVAILABILITY
    • propertyIdstring (uuid)nullable

      UUID of the property (hotel) associated with this experience, if any.

      Example:
      8e9f0a1b-2c3d-4e5f-8a6b-7c8d9e0f1a2b
    • retailAttributesobject[]nullable

      The variation axes of a RETAIL or VOUCHER product, on GET /v2/experiences/{id} only. Null on list rows and on bookable experiences.

      Child fields
      • idstring (uuid)

        Axis UUID.

        Example:
        2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e
      • namestring or map of string

        Multilingual text field. Stored as an object keyed by language code (en, de, it, es, fr, hr, sl, pt, zh, zh-hant, ja, ko, ru; machine translations are stored under <lang>_auto keys internally). On read it is returned as a single string resolved for the requested language (falling back to English when the object is not consistently translated), or as the full per-language object when showTranslations=true is passed. On write, either a plain string (stored as English) or a partial per-language object is accepted.

        Accepted shapes
        • Either string

        • Or map of string

      • sortOrderinteger

        Position of the axis among the product's axes.

        Example:
        0
      • valuesobject[]

        The axis's values, in sortOrder.

        Child fields
        • idstring (uuid)

          Value UUID. SKUs list the values they are made of in attributeValueIds.

          Example:
          9a8b7c6d-5e4f-4a3b-8c1d-0e9f8a7b6c5d
        • labelstring or map of string

          Multilingual text field. Stored as an object keyed by language code (en, de, it, es, fr, hr, sl, pt, zh, zh-hant, ja, ko, ru; machine translations are stored under <lang>_auto keys internally). On read it is returned as a single string resolved for the requested language (falling back to English when the object is not consistently translated), or as the full per-language object when showTranslations=true is passed. On write, either a plain string (stored as English) or a partial per-language object is accepted.

          Accepted shapes
          • Either string

          • Or map of string

        • sortOrderinteger

          Position of the value within its axis.

          Example:
          0
    • retailSkusobject[]nullable

      The SKUs a shopper can buy, with live availability, for a RETAIL or VOUCHER product on GET /v2/experiences/{id} only. Null on list rows and on bookable experiences.

      Child fields
      • idstring (uuid)

        SKU UUID. Send it as retailSkuId to buy this SKU on an order.

        Example:
        8f14e45f-ceea-4e5b-b0d4-9f3c1a2b3c4d
      • skuCodestringnullable

        The seller's stock-keeping code for this SKU.

        Example:
        TSHIRT-RED-M
      • attributeValueIdsstring (uuid)[]

        The variation values this SKU is made of; match them against retailAttributes to label it.

      • sortOrderinteger

        Display position.

        Example:
        0
      • pricestring

        Unit price as a decimal string, in the organizer's default currency.

        Example:
        24.00
      • availableQuantityintegernullable

        Units available to buy now (on hand minus units held in unconfirmed orders). Null means unlimited.

        Example:
        3
      • extraFieldsobject[]

        Questions the buyer answers when buying this SKU.

        Child fields
        • idstring (uuid)

          Question UUID. Answers are keyed by it.

          Example:
          aa1bb2cc-3dd4-4ee5-9ff6-0a1b2c3d4e5f
        • namestring or map of string

          Multilingual text field. Stored as an object keyed by language code (en, de, it, es, fr, hr, sl, pt, zh, zh-hant, ja, ko, ru; machine translations are stored under <lang>_auto keys internally). On read it is returned as a single string resolved for the requested language (falling back to English when the object is not consistently translated), or as the full per-language object when showTranslations=true is passed. On write, either a plain string (stored as English) or a partial per-language object is accepted.

          Accepted shapes
          • Either string

          • Or map of string

        • sortOrderinteger

          Order the questions are asked in.

          Example:
          0
        • fieldTypestring

          QUESTION takes free text; CHECKBOX takes "true" or "false".

          Allowed values:
          QUESTIONCHECKBOX
          Example:
          QUESTION
        • requiredboolean

          Whether the question must be answered before the order can be confirmed. A required CHECKBOX must be ticked.

          Example:
          false
      • imageUrlstring (uri)nullable

        The SKU's own image, or null when it has none.

        Example:
        https://images.example.com/tshirt-red.jpg
    • retailVoucherConfigobjectnullable

      Redemption rules of a VOUCHER product, on GET /v2/experiences/{id} only. Null otherwise, and while no rules are set.

      Child fields
      • redemptionsPerUnitinteger

        How many uses one voucher grants. One use covers one booking.

        Limits:
        minimum 1
        Example:
        5
      • scopeExperienceIdsstring (uuid)[]

        The experiences the voucher can be redeemed against.

      • includesAddonboolean

        Whether a redeemed booking may include one add-on of its option at no charge.

        Example:
        false
  • experienceExplanationsobject[]

    Per-experience explanation of why it was recommended.

    Child fields
    • experienceIdstring (uuid)

      The recommended experience.

      Example:
      5f8b8c1e-3f8a-4a1e-9d2b-1c2d3e4f5a6b
    • explanationstring

      Human-readable reason for the recommendation.

      Example:
      A strong fit for this guest.
    • orderinteger

      Zero-based recommendation rank.

      Example:
      0
Response 200json
{
  "recommendationText": "Based on your love of the outdoors, we picked these for your stay.",
  "experiences": [
    {
      "id": "5f8b8c1e-3f8a-4a1e-9d2b-1c2d3e4f5a6b",
      "name": "Sunset Kayak Tour",
      "description": "Sunset Kayak Tour",
      "highlight": "Sunset Kayak Tour",
      "otherNotes": "Sunset Kayak Tour",
      "noReservationNote": "Sunset Kayak Tour",
      "code": "KAYAK-01",
      "status": "ACTIVE",
      "experienceType": "EXPERIENCE",
      "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."
      },
      "meetingPoint": null,
      "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
      },
      "rating": null,
      "videos": [
        "https://youtube.com/watch?v=abc123"
      ],
      "maxPrice": {
        "amount": 79,
        "freeOfCharge": false,
        "public": {
          "amount": 99,
          "unit": "Person",
          "freeOfCharge": false
        },
        "private": {
          "amount": 99,
          "unit": "Person",
          "freeOfCharge": false
        },
        "currency": "EUR",
        "unit": "person"
      },
      "minPrice": {
        "amount": 79,
        "freeOfCharge": false,
        "public": {
          "amount": 99,
          "unit": "Person",
          "freeOfCharge": false
        },
        "private": {
          "amount": 99,
          "unit": "Person",
          "freeOfCharge": false
        },
        "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,
          "capacityExempt": false,
          "sortOrder": 0,
          "isDefault": true,
          "externalId": "BOKUN-ADULT",
          "isEnabledOnBookableOptions": true
        }
      ],
      "options": [
        {
          "id": "9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
          "status": "ACTIVE",
          "name": "Sunset Kayak Tour"
        }
      ],
      "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",
      "retailAttributes": [
        {
          "id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
          "name": "Sunset Kayak Tour",
          "sortOrder": 0,
          "values": [
            {
              "id": "9a8b7c6d-5e4f-4a3b-8c1d-0e9f8a7b6c5d",
              "label": "Sunset Kayak Tour",
              "sortOrder": 0
            }
          ]
        }
      ],
      "retailSkus": [
        {
          "id": "8f14e45f-ceea-4e5b-b0d4-9f3c1a2b3c4d",
          "skuCode": "TSHIRT-RED-M",
          "attributeValueIds": [
            "9a8b7c6d-5e4f-4a3b-8c1d-0e9f8a7b6c5d"
          ],
          "sortOrder": 0,
          "price": "24.00",
          "availableQuantity": 3,
          "extraFields": [
            {
              "id": "aa1bb2cc-3dd4-4ee5-9ff6-0a1b2c3d4e5f",
              "name": "Sunset Kayak Tour",
              "sortOrder": 0,
              "fieldType": "QUESTION",
              "required": false
            }
          ],
          "imageUrl": "https://images.example.com/tshirt-red.jpg"
        }
      ],
      "retailVoucherConfig": {
        "redemptionsPerUnit": 5,
        "scopeExperienceIds": [
          "0d4dbb2e-8a51-4a4b-9d3e-6f2b7c1a9e55"
        ],
        "includesAddon": false
      }
    }
  ],
  "experienceExplanations": [
    {
      "experienceId": "5f8b8c1e-3f8a-4a1e-9d2b-1c2d3e4f5a6b",
      "explanation": "A strong fit for this guest.",
      "order": 0
    }
  ]
}

Errors

400

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

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."
    }
  ]
}