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.
curl "https://api.turneo.co/v2/experiences/experience_recommendations" \
-H "X-API-Key: <your-api-key>"Query parameters
storeIdstringStore to recommend from. Falls back to the
x-store-idheader; one of the two is required.- Example:
64a1f0c2e4b0a1b2c3d4e5f6
resellerIdstringReseller (hotel) partner ID, used as additional personalization context.
- Example:
reseller-123
guestIdstringGuest UUID to personalize for. Takes precedence over
email.- Example:
0d9f4a3e-6a7b-4c1d-8e2f-3a4b5c6d7e8f
emailstring (email)Guest email; used to resolve the guest when
guestIdis absent (exact match). Never echoed back in the response.- Example:
guest@example.com
languagestringLanguage 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
groupstringFree-text description of the travel party.
- Example:
2 adults, 1 child
interestsstringFree-text guest interests to steer the recommendation.
- Example:
wellness,food
Responses
200object
Recommendations plus echoed request parameters.
recommendationTextstringConversational 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 stringMultilingual 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>_autokeys internally). On read it is returned as a single string resolved for the requestedlanguage(falling back to English when the object is not consistently translated), or as the full per-language object whenshowTranslations=trueis 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 stringMultilingual 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>_autokeys internally). On read it is returned as a single string resolved for the requestedlanguage(falling back to English when the object is not consistently translated), or as the full per-language object whenshowTranslations=trueis 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 stringMultilingual 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>_autokeys internally). On read it is returned as a single string resolved for the requestedlanguage(falling back to English when the object is not consistently translated), or as the full per-language object whenshowTranslations=trueis 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 stringMultilingual 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>_autokeys internally). On read it is returned as a single string resolved for the requestedlanguage(falling back to English when the object is not consistently translated), or as the full per-language object whenshowTranslations=trueis 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 stringMultilingual 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>_autokeys internally). On read it is returned as a single string resolved for the requestedlanguage(falling back to English when the object is not consistently translated), or as the full per-language object whenshowTranslations=trueis 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
codestringnullableOptional internal reference code of the organizer.
- Example:
KAYAK-01
statusstringLifecycle status. Only ACTIVE experiences are visible to other partners by default.
- Allowed values:
ACTIVEDRAFTINACTIVECATALOGUE- Example:
ACTIVE
experienceTypestringEXPERIENCEis bookable through options and slots.RETAILis a retail product andVOUCHERa gift voucher; both sell from SKUs instead (see the Retail group) and have no options, slots or participant types.- Allowed values:
EXPERIENCERETAILVOUCHER- Example:
EXPERIENCE
organizerobjectEmbedded summary of the organizer (owner) of the experience.
Child fields
namestringOrganizer display name.
- Example:
Acme Tours
partnerIdstringOrganizer's public partner ID.
- Example:
acme-tours
phonestringnullableContact phone number.
- Example:
+385911234567
partnerEmailstring (email)Organizer's email address.
- Example:
hello@acmetours.com
partnerRatingnumber (double)nullableAggregate partner rating.
- Example:
4.8
partnerReviewsintegernullableNumber of reviews contributing to the partner rating.
- Example:
132
logostring (uri)nullableOrganizer logo URL.
- Example:
https://res.cloudinary.com/turneo/image/upload/logo.png
websitestring (uri)nullableOrganizer website.
- Example:
https://acmetours.com
aboutUsstringnullableOrganizer self-description.
- Example:
Family-run kayak outfitter since 2005.
supportEmailstring (email)nullableDedicated support email, when different from the main address.
- Example:
support@acmetours.com
featureFlagsobjectFeature flags enabled for this organizer.
categoriesobjectnullableCategory 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 stringMultilingual 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>_autokeys internally). On read it is returned as a single string resolved for the requestedlanguage(falling back to English when the object is not consistently translated), or as the full per-language object whenshowTranslations=trueis 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
nameDefaultstringDefault (untranslated) name of the theme.
- Example:
Family friendly
isDefaultbooleanWhether this is one of the partner's default themes.
- Example:
false
descriptionstringnullableOptional description of the theme.
- Example:
Great for kids of all ages.
locationobjectnullableWhere the experience takes place. Coordinates drive geo search and the local timezone.
Child fields
citystringCity name. Required (with country and coordinates) while the experience is ACTIVE.
- Example:
Split
countrystringCountry name.
- Example:
Croatia
addressstringnullableStreet address.
- Example:
Riva 1
latitudenumber (double)Latitude in decimal degrees.
- Example:
43.508
longitudenumber (double)Longitude in decimal degrees.
- Example:
16.44
descriptionstringnullableFree-text directions or notes about the location.
- Example:
Next to the ferry terminal.
meetingPointobjectnullabledeprecatedDeprecated single meeting point — use
meetingPointsinstead.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
typestringnullableMeeting point type (e.g.
CENTRAL_MEETING_POINT).- Example:
CENTRAL_MEETING_POINT
citystringnullableCity of the meeting point.
- Example:
Split
countrystringnullableCountry of the meeting point.
- Example:
Croatia
addressstringnullableStreet address.
- Example:
Riva 1
descriptionstringnullableHow 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
timeBeforeStartintegernullableMinutes before the start time the traveler should arrive.
- Example:
15
titlestringnullableShort display title of the meeting point.
- Example:
Riva promenade
pickupobjectnullablePickup configuration for the experience.
Child fields
valuestringPickup offering (free-form configuration value).
- Example:
Hotel pickup available
rulesstringRules or conditions attached to pickup.
- Example:
Within 5 km of the city center only.
allowFreePickupbooleanWhether the traveler may enter a free-form pickup location.
- Example:
true
durationobjectnullableDuration split into days/hours/minutes. On experience reads this is computed from the first active, non-custom option that defines a duration —
nullwhen no active option has one.Child fields
daysintegerWhole days component.
- Example:
0
hoursintegerHours component.
- Example:
2
minutesintegerMinutes component.
- Example:
30
ratingobjectnullabledeprecatedDeprecated legacy rating blob — use
reviewsinstead.videosstring (uri)[]Video URLs (max 20). Always an array, never null.
maxPriceobjectnullableA price boundary condition (used by
maxPrice/minPrice).Child fields
amountnumber (double)Monetary amount over every active variant, members-only included.
- Example:
79
freeOfChargebooleanTrue when every variant in scope is free. Present on
minPriceonly.- Example:
false
publicobjectnullableSame boundary over public variants only (
restricted=false).nullwhen no public variant is priced; absent until the experience is recomputed.Child fields
amountnumber (double)- Example:
99
unitstringnullablePricing unit the amount applies to (e.g. per person).
- Example:
Person
freeOfChargebooleanPresent on
minPricescopes only.- Example:
false
privateobjectnullableSame boundary over what a
restricted=trueviewer can book: an option's members-only variants when it has any, else its public ones.nullwhen nothing priced qualifies; absent until the experience is recomputed.Child fields
amountnumber (double)- Example:
99
unitstringnullablePricing unit the amount applies to (e.g. per person).
- Example:
Person
freeOfChargebooleanPresent on
minPricescopes only.- Example:
false
currencystringISO 4217 currency code.
- Example:
EUR
unitstringnullablePricing unit the amount applies to (e.g. per person).
- Example:
person
minPriceobjectnullableA price boundary condition (used by
maxPrice/minPrice).Child fields
amountnumber (double)Monetary amount over every active variant, members-only included.
- Example:
79
freeOfChargebooleanTrue when every variant in scope is free. Present on
minPriceonly.- Example:
false
publicobjectnullableSame boundary over public variants only (
restricted=false).nullwhen no public variant is priced; absent until the experience is recomputed.Child fields
amountnumber (double)- Example:
99
unitstringnullablePricing unit the amount applies to (e.g. per person).
- Example:
Person
freeOfChargebooleanPresent on
minPricescopes only.- Example:
false
privateobjectnullableSame boundary over what a
restricted=trueviewer can book: an option's members-only variants when it has any, else its public ones.nullwhen nothing priced qualifies; absent until the experience is recomputed.Child fields
amountnumber (double)- Example:
99
unitstringnullablePricing unit the amount applies to (e.g. per person).
- Example:
Person
freeOfChargebooleanPresent on
minPricescopes only.- Example:
false
currencystringISO 4217 currency code.
- Example:
EUR
unitstringnullablePricing unit the amount applies to (e.g. per person).
- Example:
person
languagesstringnullableComma-separated languages the experience is conducted in.
- Example:
English,German
cutOffTimeintegerLatest possible booking, in hours before the start time.
- Example:
4
refundPolicyobjectnullableTiered 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
hoursBeforeStartintegerMinimum hours before start for this tier to apply.
- Example:
48
refundPercentageintegerPercentage of the price refunded in this tier (0-100).
- Example:
100
supportContactobject[]nullableSupport contacts overriding the organizer defaults, as
{type, value}pairs.Child fields
typestringContact channel (
email,phone,whatsapp).- Example:
email
valuestringThe address / number.
- Example:
support@acmetours.com
travellerTypeScoresobjectnullableAI-computed suitability scores per traveler type.
availableFromstring (date)nullableWhen the experience has no bookable future availability, the date we expect it to become available again;
nullwhen it is currently available.- Example:
2026-09-01
publishedAtstring (date-time)nullableWhen the experience was (last) activated.
nullfor never-published drafts.- Example:
2026-04-02T09:15:00Z
commissionintegerCommission 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[]nullableOn 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
typestringWhether this is the default marketplace rate or a per-reseller override.
- Allowed values:
MARKETPLACERESELLER- Example:
MARKETPLACE
resellerstringnullablePartner ID of the reseller this row applies to. Must be null/absent for MARKETPLACE rows.
- Example:
grand-hotel
valueintegerCommission percentage.
- Example:
20
includedobject[]What the price includes.
Child fields
namestring or map of stringMultilingual 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>_autokeys internally). On read it is returned as a single string resolved for the requestedlanguage(falling back to English when the object is not consistently translated), or as the full per-language object whenshowTranslations=trueis 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
inclusionIdstringStable 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 stringMultilingual 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>_autokeys internally). On read it is returned as a single string resolved for the requestedlanguage(falling back to English when the object is not consistently translated), or as the full per-language object whenshowTranslations=trueis 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
exclusionIdstringStable 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)nullableLow-resolution/thumbnail image URL.
- Example:
https://res.cloudinary.com/turneo/image/upload/lo.jpg
altTextstringnullableAccessibility 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
typestringLink type (e.g.
EXTERNAL_ID,BOOKING_LINK).- Example:
EXTERNAL_ID
namestringDisplay label for the link. May be blank.
- Example:
Bokun activity ID
valuestringThe URL or external identifier.
- Example:
1189606
bookingTypestringEXTERNALwhen aBOOKING_LINKexternal link exists (booked off-platform), elseINTERNAL.- 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 stringMultilingual 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>_autokeys internally). On read it is returned as a single string resolved for the requestedlanguage(falling back to English when the object is not consistently translated), or as the full per-language object whenshowTranslations=trueis 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 stringMultilingual 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>_autokeys internally). On read it is returned as a single string resolved for the requestedlanguage(falling back to English when the object is not consistently translated), or as the full per-language object whenshowTranslations=trueis 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
minAgeintegernullableMinimum age for this participant type.
- Example:
18
maxAgeintegernullableMaximum age for this participant type.
- Example:
99
capacityExemptbooleanWhen true, participants of this type do not count toward slot capacity.
- Example:
false
sortOrderintegerDisplay order (ascending).
- Example:
0
isDefaultbooleanTrue for the auto-created Adult/Child/Infant types (cannot be deleted).
- Example:
true
externalIdstringnullableProvider-side identifier for externally synced participant types.
- Example:
BOKUN-ADULT
isEnabledOnBookableOptionsbooleanTrue 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=1is passed — absent otherwise (including on list responses). Same item shape and filtering as the/optionssub-endpoint.Child fields
idstring (uuid)Option ID.
- Example:
9c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f
statusstringOption status. Embedded lists default to ACTIVE options only.
- Allowed values:
DRAFTACTIVEINACTIVE- Example:
ACTIVE
namestring or map of stringMultilingual 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>_autokeys internally). On read it is returned as a single string resolved for the requestedlanguage(falling back to English when the object is not consistently translated), or as the full per-language object whenshowTranslations=trueis 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
tagsobjectnullableComputed marketing tags.
exclusive/privateare recalculated from the current options andallowedPartnerson every read; the remaining flags come from stored data.Child fields
likelyToSellOutbooleanWhether the experience is flagged as likely to sell out.
- Example:
false
popularbooleanWhether the experience is flagged as popular.
- Example:
true
exclusivebooleanTrue when the experience is shared with exactly one partner.
- Example:
false
privatestringPrivate-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[]nullableTranslation completeness per language, or
nullwhen nothing is translated. Non-owners only see complete (ACTIVE) languages; the owner also sees incomplete (DRAFT) ones.Child fields
languagestring2-letter language code.
- Example:
de
statusstringACTIVEwhen 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
sourcestringWhether the translation is fully machine-generated or contains organizer-authored text.
- Allowed values:
AIORGANIZER- Example:
ORGANIZER
reviewsobjectnullableAggregated traveler reviews.
nullwhen the experience has no (visible) reviews. By default only ACCEPTED reviews are included; passunapproved_reviews=trueto include the rest. Reviews are ordered by rating, then insightfulness.Child fields
recommendedPercentintegerPercentage of visible reviews rated 3 stars or higher.
- Example:
96
ratingnumber (double)Average rating across visible reviews, rounded to one decimal.
- Example:
4.8
summarystringnullableAI-generated summary of the reviews, when available.
- Example:
Guests consistently praise the guides and the sunset views.
reviewsobject[]The individual reviews.
Child fields
ratingintegerStar rating (1-5).
- Example:
5
reviewTextstringnullableReview text, translated to the requested
languagewhen a translation exists.- Example:
Fantastic sunset tour, our guide was brilliant.
reviewerNamestringnullableReviewer display name; falls back to the booking's traveler first name.
- Example:
Anna
datestringReview date (ISO 8601).
- Example:
2026-05-14T18:03:00
sourcestringRESELLERwhen the requesting partner posted the review themselves,OTHERotherwise.- Example:
OTHER
storeIdstringnullableStore the review was posted from — only exposed for the poster's own reviews,
nullotherwise.- Example:
64a1f0c2e4b0a1b2c3d4e5f6
statusstringModeration status. Non-ACCEPTED reviews appear only with
unapproved_reviews=true.- Allowed values:
PENDINGACCEPTEDREJECTED- Example:
ACCEPTED
insightfulnessScorenumber (double)nullableAI-scored insightfulness, used for ordering reviews.
- Example:
0.87
discountobjectnullableThe single highest currently valid discount across all active, non-custom options — either an availability discount or an early-bird discount.
nullwhen no discount applies or when availability comes from an external provider.Child fields
percentageAmountnumber (double)Discount percentage.
- Example:
15
typestringWhich kind of discount is the highest.
- Allowed values:
AVAILABILITYEARLY_BIRD- Example:
AVAILABILITY
propertyIdstring (uuid)nullableUUID of the property (hotel) associated with this experience, if any.
- Example:
8e9f0a1b-2c3d-4e5f-8a6b-7c8d9e0f1a2b
retailAttributesobject[]nullableThe variation axes of a
RETAILorVOUCHERproduct, onGET /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 stringMultilingual 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>_autokeys internally). On read it is returned as a single string resolved for the requestedlanguage(falling back to English when the object is not consistently translated), or as the full per-language object whenshowTranslations=trueis 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
sortOrderintegerPosition 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 stringMultilingual 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>_autokeys internally). On read it is returned as a single string resolved for the requestedlanguage(falling back to English when the object is not consistently translated), or as the full per-language object whenshowTranslations=trueis 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
sortOrderintegerPosition of the value within its axis.
- Example:
0
retailSkusobject[]nullableThe SKUs a shopper can buy, with live availability, for a
RETAILorVOUCHERproduct onGET /v2/experiences/{id}only. Null on list rows and on bookable experiences.Child fields
idstring (uuid)SKU UUID. Send it as
retailSkuIdto buy this SKU on an order.- Example:
8f14e45f-ceea-4e5b-b0d4-9f3c1a2b3c4d
skuCodestringnullableThe 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
retailAttributesto label it.sortOrderintegerDisplay position.
- Example:
0
pricestringUnit price as a decimal string, in the organizer's default currency.
- Example:
24.00
availableQuantityintegernullableUnits 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 stringMultilingual 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>_autokeys internally). On read it is returned as a single string resolved for the requestedlanguage(falling back to English when the object is not consistently translated), or as the full per-language object whenshowTranslations=trueis 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
sortOrderintegerOrder the questions are asked in.
- Example:
0
fieldTypestringQUESTIONtakes free text;CHECKBOXtakes"true"or"false".- Allowed values:
QUESTIONCHECKBOX- Example:
QUESTION
requiredbooleanWhether the question must be answered before the order can be confirmed. A required
CHECKBOXmust be ticked.- Example:
false
imageUrlstring (uri)nullableThe SKU's own image, or null when it has none.
- Example:
https://images.example.com/tshirt-red.jpg
retailVoucherConfigobjectnullableRedemption rules of a
VOUCHERproduct, onGET /v2/experiences/{id}only. Null otherwise, and while no rules are set.Child fields
redemptionsPerUnitintegerHow 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.
includesAddonbooleanWhether 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
explanationstringHuman-readable reason for the recommendation.
- Example:
A strong fit for this guest.
orderintegerZero-based recommendation rank.
- Example:
0
{
"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[].fieldanderrors[].code.
Error body
typestringError class.
- Allowed values:
validation_errorclient_errorserver_error- Example:
validation_error
errorsobject[]Child fields
codestringMachine-readable error code.
- Example:
required
fieldstringnullableOffending field, or null/'general' for non-field errors.
- Example:
startTime
messagestringHuman-readable message.
- Example:
This field is required.
{
"type": "validation_error",
"errors": [
{
"code": "required",
"field": "startTime",
"message": "This field is required."
}
]
}