List options across experiences
GET/v2/options
Requires your API key in the X-API-Key header.
Lists active (non-deleted) options across all experiences. This is the cross-experience read surface used by the booking flow to load the bookable products for one or more experiences in a single call — typically narrowed with experienceIds.
Status
Defaults to ACTIVE options only. Pass a comma-separated status list (e.g. ACTIVE,INACTIVE) to widen the result.
Variant visibility
Each option embeds its variants. Use restricted=true to get the member-only variants (falling back to public ones when an option has none), restricted=false for public variants only, or omit the parameter to get all active variants.
Multilingual fields
name and note (and nested variant/add-on/extra-field names) resolve to a single string in the requested language by default. Pass showTranslations=true to get the full per-language object instead (e.g. {"en": "Shared", "de": "Geteilt"}).
Soft-deleted options never appear. Results are ordered by each option's score, ascending.
curl "https://api.turneo.co/v2/options" \
-H "X-API-Key: <your-api-key>"Query parameters
experienceIdsstringComma-separated list of experience UUIDs to narrow the result to. Only options belonging to these experiences are returned. The legacy snake_case alias
experience_idsis also accepted during the frontend migration;experienceIdsis canonical.- Example:
8f14e45f-ceea-467f-a34e-4a3d1a3f5b6a,6512bd43-d9ca-4e90-b1aa-cf1c75f6d9e1
statusstringComma-separated option statuses to include (
DRAFT,ACTIVE,INACTIVE). Defaults toACTIVEwhen omitted. Unknown values return a 400 listing the allowed statuses.- Example:
ACTIVE,INACTIVE
restrictedstringVariant visibility filter.
truereturns restricted (member-only) variants per option, falling back to public variants when an option has none;falsereturns only public variants; omit to return all active variants. Any value other thantruecounts asfalse.- Allowed values:
truefalse- Example:
false
languagestringLanguage code used to resolve multilingual fields (e.g.
de). Falls back to the default language when a translation is missing.- Example:
de
showTranslationsstringSet to
trueto return multilingual fields as full per-language objects instead of a single resolved string.- Allowed values:
truefalse- Example:
false
pageinteger1-based page number for pagination.
- Limits:
- minimum 1
- Default:
1- Example:
1
page_sizeintegerNumber of results per page (server default applies when omitted).
- Limits:
- minimum 1
- Example:
50
nopaginationstringSet to
trueto return the full result set as a flat array without the pagination envelope.- Allowed values:
truefalse- Example:
false
Responses
200object
Paginated list of options (or a flat array when nopagination=true).
countintegerTotal number of options matching the query across all pages.
- Example:
42
nextstringnullableAbsolute URL of the next page, or null on the last page.
- Example:
https://api.turneo.co/v2/options?page=2
previousstringnullableAbsolute URL of the previous page, or null on the first page.
resultsobject[]The options on this page.
Child fields
idstring (uuid)UUID of the option.
- Example:
0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d
experienceIdstring (uuid)UUID of the experience this option belongs to. Read-only.
- Example:
8f14e45f-ceea-467f-a34e-4a3d1a3f5b6a
statusstringLifecycle status. Only
ACTIVEoptions are sellable; the list endpoint defaults toACTIVE. Once an option leavesDRAFTit can never return to it.- Allowed values:
DRAFTACTIVEINACTIVE- Example:
ACTIVE
namestring or map of stringMultilingual text field. By default resolves to a single string in the requested
language(with fallback to the default language); whenshowTranslations=trueis passed, the full per-language object is returned instead (e.g.{"en": "Shared boat tour", "de": "Geteilte Bootstour"}). Null when the field is unset.Accepted shapes
Either string
Language-resolved text (default representation).
Or map of string
Full per-language object (only when
showTranslations=true). Keys are language codes.
codestringnullableOptional organizer-facing short code for the option. Null when not set.
- Example:
SHARED-AM
scoreintegerSort weight — options are ordered ascending by score. Deactivated options are automatically pushed to the bottom.
- Example:
100
externalIdstringnullableIdentifier of the option in an external availability provider (Bokun/Regiondo/Kompas). Read-only; null for native Turneo options.
notestring or map of stringMultilingual text field. By default resolves to a single string in the requested
language(with fallback to the default language); whenshowTranslations=trueis passed, the full per-language object is returned instead (e.g.{"en": "Shared boat tour", "de": "Geteilte Bootstour"}). Null when the field is unset.Accepted shapes
Either string
Language-resolved text (default representation).
Or map of string
Full per-language object (only when
showTranslations=true). Keys are language codes.
instantUntilDurationobjectnullableBooking confirmation threshold. Null means bookings always require manual organizer confirmation; a zero duration means bookings are always confirmed instantly; a positive duration means bookings are instant only when made farther in advance than this threshold.
Child fields
daysintegerWhole days component of the duration.
- Example:
0
hoursintegerHours component of the duration.
- Example:
2
minutesintegerMinutes component of the duration.
- Example:
30
disabledParticipantTypesstring (uuid)[]UUIDs of the experience's participant types NOT offered on this option. An empty list means all of the experience's participant types are enabled.
startDatestring (date)nullableFirst date of the option's availability period. Required for active options; may be null on drafts.
- Example:
2026-07-01
endDatestring (date)nullableLast date of the option's availability period. Null means open-ended; cannot be before
startDate.- Example:
2026-09-30
slotTypestringnullableHow availability slots are scheduled —
FLEXIBLEgenerates slots on an interval within a daily time window,FIXEDuses explicit start times per weekday,DATE_ONLYhas one dateless slot per day. Required for active options.- Allowed values:
FLEXIBLEFIXEDDATE_ONLYnull- Example:
FLEXIBLE
flexibleSlotConfigobjectnullableSlot generation config for
FLEXIBLEoptions: slots are generated everyintervalbetweenfromTimeandtoTimeon the configured weekdays. Null unlessslotTypeisFLEXIBLE.Child fields
fromTimestringLocal time of day the first slot starts (HH:MM).
- Example:
08:00
toTimestringLocal time of day after which no more slots start (HH:MM).
- Example:
18:00
intervalstringGap between consecutive slot start times (HH:MM).
- Example:
01:00
daysOfWeekinteger[]Weekdays on which slots are generated. Integers 0-6 where 0 is Monday and 6 is Sunday.
fixedSlotConfigobject[]nullableSlot schedule for
FIXEDoptions — a list of fixed start times per weekday set. Null unlessslotTypeisFIXED.Child fields
timestringLocal start time of the slot (HH:MM).
- Example:
09:30
daysOfWeekinteger[]Weekdays on which this slot occurs. Integers 0-6 where 0 is Monday and 6 is Sunday.
groupTypestringnullableWhether a slot is sold to a single party (
PRIVATE) or shared across bookings (PUBLIC). Required when resource groups are configured; must be null when they are not.- Allowed values:
PRIVATEPUBLICnull- Example:
PRIVATE
slotCapacityintegernullableMaximum participants per slot. Null when capacity is driven by resource groups instead (the two are mutually exclusive).
- Example:
10
pricingModelstringnullableHow the option is priced. Determines which pricing fields are populated on each variant. Required for active options. Existing non-draft options can never switch to or from
DURATION_BASED.- Allowed values:
FLAT_RATEPER_PERSONPER_GROUP_SIZEDURATION_BASEDnull- Example:
PER_PERSON
durationobjectnullableFixed duration of the experience for FLAT_RATE / PER_PERSON / PER_GROUP_SIZE options. Must be empty for DURATION_BASED options (use
durationIncrement). Required to be non-zero when the option has resource groups and is not DATE_ONLY.Child fields
daysintegerWhole days component of the duration.
- Example:
0
hoursintegerHours component of the duration.
- Example:
2
minutesintegerMinutes component of the duration.
- Example:
30
durationIncrementobjectnullableBookable duration unit for DURATION_BASED options — guests book N multiples of this increment (e.g. increment of 30 minutes, 3 units = 90 minutes). Null for other pricing models.
Child fields
daysintegerWhole days component of the duration.
- Example:
0
hoursintegerHours component of the duration.
- Example:
2
minutesintegerMinutes component of the duration.
- Example:
30
durationPricingUnitstringnullableUI-only hint for DURATION_BASED options: whether the per-increment price scales by headcount (
PER_PERSON) or is flat per resource (PER_RESOURCE). Not consulted by backend pricing.- Allowed values:
PER_PERSONPER_RESOURCEnull
multiDayModestringnullableFor rentals of one day or more, how the duration maps to the resource occupancy window's end —
CALENDAR_DAY(default) runs until the Nth rental day's working-hours close,ROLLING_24Hruns N x 24 hours from the start instant. Ignored for sub-day options.- Allowed values:
ROLLING_24HCALENDAR_DAYnull- Example:
CALENDAR_DAY
allowPartialDaybooleanFor sub-day fixed-duration options with resources: when true, a booking whose full duration does not fit the day's remaining working hours is accepted clamped to those hours at the unchanged fixed price ("up to N hours" day passes). When false such bookings are rejected. Not applicable to DURATION_BASED options or multi-day rentals.
- Example:
false
custombooleanTrue for one-off options created for a specific custom booking. Custom options are excluded from all public catalog queries.
- Example:
false
earlyBirdAdvanceDaysintegernullableMinimum days in advance a booking must be made to earn the early bird discount. Set together with
earlyBirdDiscountor not at all.- Example:
30
earlyBirdDiscountstringnullableEarly bird discount percentage as a decimal string. Set together with
earlyBirdAdvanceDaysor not at all.- Example:
10.00
variantsobject[]Active variants of the option, subject to the
restrictedquery parameter filter. Every option has at least one variant (a default one is created automatically when none is supplied).Child fields
idstring (uuid)UUID of the variant.
- Example:
9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
namestring or map of stringMultilingual text field. By default resolves to a single string in the requested
language(with fallback to the default language); whenshowTranslations=trueis passed, the full per-language object is returned instead (e.g.{"en": "Shared boat tour", "de": "Geteilte Bootstour"}). Null when the field is unset.Accepted shapes
Either string
Language-resolved text (default representation).
Or map of string
Full per-language object (only when
showTranslations=true). Keys are language codes.
imagestringnullableURL of an illustrative image for the variant. Null when not set.
- Example:
https://cdn.turneo.com/variants/boat-morning.jpg
maxParticipantsintegernullableMaximum participants a single booking of this variant may include. Null means no variant-level cap.
- Example:
8
sortOrderintegerAscending display position among the option's variants.
- Example:
0
flatPricestringnullableFixed price per booking, as a decimal string. Only set for FLAT_RATE options; null otherwise.
- Example:
150.00
groupSizeUnitstringnullableHow PER_GROUP_SIZE tier prices are applied — per person in the group or once per group. Null for other pricing models.
- Allowed values:
PER_PERSONPER_GROUPnull- Example:
PER_GROUP
pricingTiersobject[]Quantity-banded prices. Populated for PER_GROUP_SIZE and DURATION_BASED options; empty otherwise. Only active tiers are returned.
Child fields
idstring (uuid)UUID of the pricing tier.
- Example:
3c9a7b1d-2e4f-4a5b-8c6d-7e8f9a0b1c2d
minQuantityintegerInclusive lower bound of the quantity band. The first tier always starts at 1.
- Example:
1
maxQuantityintegernullableInclusive upper bound of the quantity band. Null means open-ended ("7+"); only the last tier may be open-ended.
- Example:
6
pricestringPrice for this band, as a decimal string in the experience currency.
- Example:
120.00
participantPricesobject[]Per-participant-type prices. Populated for PER_PERSON options; empty otherwise. Only active prices are returned.
Child fields
idstring (uuid)UUID of the participant price row.
- Example:
5e2d1c0b-9a8f-4e7d-b6c5-a4b3c2d1e0f9
participantTypeIdstring (uuid)UUID of the participant type (e.g. Adult, Child) this price applies to.
- Example:
1f2e3d4c-5b6a-4978-8d0e-9f8a7b6c5d4e
pricestringPrice per participant of this type, as a decimal string.
- Example:
45.00
restrictedbooleanMarks the variant as exclusive/member-only with special pricing. Filterable via the
restrictedquery parameter on option reads.- Example:
false
addonsobject[]Active add-ons purchasable with the option.
Child fields
idstring (uuid)UUID of the add-on.
- Example:
2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a
namestring or map of stringMultilingual text field. By default resolves to a single string in the requested
language(with fallback to the default language); whenshowTranslations=trueis passed, the full per-language object is returned instead (e.g.{"en": "Shared boat tour", "de": "Geteilte Bootstour"}). Null when the field is unset.Accepted shapes
Either string
Language-resolved text (default representation).
Or map of string
Full per-language object (only when
showTranslations=true). Keys are language codes.
sortOrderintegerAscending display position among the option's add-ons.
- Example:
0
addonTypestringUI behaviour —
CHECKBOXis a yes/no extra,QUANTITY_SELECTORlets the traveler pick a quantity.- Allowed values:
CHECKBOXQUANTITY_SELECTOR- Example:
QUANTITY_SELECTOR
perPersonbooleanWhen true the add-on price is charged once per participant rather than per booking.
- Example:
false
maxQuantityintegernullableMaximum quantity a booking may add. Null means unlimited.
- Example:
5
pricestringnullablePrice per unit of the add-on, as a decimal string. Null means free.
- Example:
12.50
nonCommissionablebooleanWhen true the add-on amount is excluded from commission calculations.
- Example:
false
extraFieldsobject[]Active custom booking questions for the option.
Child fields
idstring (uuid)UUID of the extra field.
- Example:
4a5b6c7d-8e9f-4a0b-9c1d-2e3f4a5b6c7d
namestring or map of stringMultilingual text field. By default resolves to a single string in the requested
language(with fallback to the default language); whenshowTranslations=trueis passed, the full per-language object is returned instead (e.g.{"en": "Shared boat tour", "de": "Geteilte Bootstour"}). Null when the field is unset.Accepted shapes
Either string
Language-resolved text (default representation).
Or map of string
Full per-language object (only when
showTranslations=true). Keys are language codes.
sortOrderintegerAscending display position among the option's extra fields.
- Example:
0
fieldTypestringInput type —
QUESTIONcollects free text,CHECKBOXcollects a yes/no answer.- Allowed values:
QUESTIONCHECKBOX- Example:
QUESTION
requiredbooleanWhen true the traveler must answer this field to complete the booking.
- Example:
true
discountsobject[]Active discounts configured on the option.
Child fields
idstring (uuid)UUID of the discount.
- Example:
6c7d8e9f-0a1b-4c2d-8e3f-4a5b6c7d8e9f
percentageAmountstringDiscount percentage as a decimal string (e.g. "15.00" = 15% off).
- Example:
15.00
startDatestring (date)nullableFirst date (inclusive) the discount applies. Null means no lower bound.
- Example:
2026-06-01
endDatestring (date)nullableLast date (inclusive) the discount applies. Null means no upper bound.
- Example:
2026-06-30
fromTimestringnullableLocal time of day (HH:MM:SS) from which slots qualify. Null means from midnight.
- Example:
14:00:00
untilTimestringnullableLocal time of day (HH:MM:SS) until which slots qualify. Null means until midnight.
- Example:
18:00:00
daysOfWeekinteger[]nullableWeekdays the discount applies on (0 = Monday … 6 = Sunday). Null means every day.
resourceGroupsobject[]Active resource groups backing the option's capacity. Empty when capacity is driven by
slotCapacity.Child fields
idstring (uuid)UUID of the resource group.
- Example:
8e9f0a1b-2c3d-4e4f-8a5b-6c7d8e9f0a1b
namestringnullableDisplay name of the group. Null when not set.
- Example:
Kayaks
resourcesstring (uuid)[]UUIDs of the resources in the group. Legacy shape kept for backwards compatibility —
resourceDetailscarries the richer form.resourceDetailsobject[]Embedded summary of each resource in the group.
Child fields
idstring (uuid)UUID of the resource.
- Example:
a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
namestringnullableResource name.
- Example:
Double kayak #3
capacityintegernullableMaximum participants the resource can carry (the resource's
maxParticipants). Null means uncapped.- Example:
2
{
"count": 42,
"next": "https://api.turneo.co/v2/options?page=2",
"previous": null,
"results": [
{
"id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"experienceId": "8f14e45f-ceea-467f-a34e-4a3d1a3f5b6a",
"status": "ACTIVE",
"name": "Shared boat tour",
"code": "SHARED-AM",
"score": 100,
"externalId": null,
"note": "Shared boat tour",
"instantUntilDuration": {
"days": 0,
"hours": 2,
"minutes": 30
},
"disabledParticipantTypes": [],
"startDate": "2026-07-01",
"endDate": "2026-09-30",
"slotType": "FLEXIBLE",
"flexibleSlotConfig": {
"fromTime": "08:00",
"toTime": "18:00",
"interval": "01:00",
"daysOfWeek": [
0,
1,
2,
3,
4
]
},
"fixedSlotConfig": [
{
"time": "09:30",
"daysOfWeek": [
5,
6
]
}
],
"groupType": "PRIVATE",
"slotCapacity": 10,
"pricingModel": "PER_PERSON",
"duration": {
"days": 0,
"hours": 2,
"minutes": 30
},
"durationIncrement": {
"days": 0,
"hours": 2,
"minutes": 30
},
"durationPricingUnit": null,
"multiDayMode": "CALENDAR_DAY",
"allowPartialDay": false,
"custom": false,
"earlyBirdAdvanceDays": 30,
"earlyBirdDiscount": "10.00",
"variants": [
{
"id": "9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
"name": "Shared boat tour",
"image": "https://cdn.turneo.com/variants/boat-morning.jpg",
"maxParticipants": 8,
"sortOrder": 0,
"flatPrice": "150.00",
"groupSizeUnit": "PER_GROUP",
"pricingTiers": [
{
"id": "3c9a7b1d-2e4f-4a5b-8c6d-7e8f9a0b1c2d",
"minQuantity": 1,
"maxQuantity": 6,
"price": "120.00"
}
],
"participantPrices": [
{
"id": "5e2d1c0b-9a8f-4e7d-b6c5-a4b3c2d1e0f9",
"participantTypeId": "1f2e3d4c-5b6a-4978-8d0e-9f8a7b6c5d4e",
"price": "45.00"
}
],
"restricted": false
}
],
"addons": [
{
"id": "2d3e4f5a-6b7c-4d8e-9f0a-1b2c3d4e5f6a",
"name": "Shared boat tour",
"sortOrder": 0,
"addonType": "QUANTITY_SELECTOR",
"perPerson": false,
"maxQuantity": 5,
"price": "12.50",
"nonCommissionable": false
}
],
"extraFields": [
{
"id": "4a5b6c7d-8e9f-4a0b-9c1d-2e3f4a5b6c7d",
"name": "Shared boat tour",
"sortOrder": 0,
"fieldType": "QUESTION",
"required": true
}
],
"discounts": [
{
"id": "6c7d8e9f-0a1b-4c2d-8e3f-4a5b6c7d8e9f",
"percentageAmount": "15.00",
"startDate": "2026-06-01",
"endDate": "2026-06-30",
"fromTime": "14:00:00",
"untilTime": "18:00:00",
"daysOfWeek": [
0,
1,
2,
3
]
}
],
"resourceGroups": [
{
"id": "8e9f0a1b-2c3d-4e4f-8a5b-6c7d8e9f0a1b",
"name": "Kayaks",
"resources": [
"a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
],
"resourceDetails": [
{
"id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"name": "Double kayak #3",
"capacity": 2
}
]
}
]
}
]
}Errors
- 400
Validation failed. Inspect
errors[].fieldanderrors[].code.- 401
Missing or invalid
X-API-Keyheader.
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."
}
]
}