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.

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

Query parameters

  • experienceIdsstring

    Comma-separated list of experience UUIDs to narrow the result to. Only options belonging to these experiences are returned. The legacy snake_case alias experience_ids is also accepted during the frontend migration; experienceIds is canonical.

    Example:
    8f14e45f-ceea-467f-a34e-4a3d1a3f5b6a,6512bd43-d9ca-4e90-b1aa-cf1c75f6d9e1
  • statusstring

    Comma-separated option statuses to include (DRAFT, ACTIVE, INACTIVE). Defaults to ACTIVE when omitted. Unknown values return a 400 listing the allowed statuses.

    Example:
    ACTIVE,INACTIVE
  • restrictedstring

    Variant visibility filter. true returns restricted (member-only) variants per option, falling back to public variants when an option has none; false returns only public variants; omit to return all active variants. Any value other than true counts as false.

    Allowed values:
    truefalse
    Example:
    false
  • languagestring

    Language code used to resolve multilingual fields (e.g. de). Falls back to the default language when a translation is missing.

    Example:
    de
  • showTranslationsstring

    Set to true to return multilingual fields as full per-language objects instead of a single resolved string.

    Allowed values:
    truefalse
    Example:
    false
  • pageinteger

    1-based page number for pagination.

    Limits:
    minimum 1
    Default:
    1
    Example:
    1
  • page_sizeinteger

    Number of results per page (server default applies when omitted).

    Limits:
    minimum 1
    Example:
    50
  • nopaginationstring

    Set to true to 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).

  • countinteger

    Total number of options matching the query across all pages.

    Example:
    42
  • nextstringnullable

    Absolute URL of the next page, or null on the last page.

    Example:
    https://api.turneo.co/v2/options?page=2
  • previousstringnullable

    Absolute 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
    • statusstring

      Lifecycle status. Only ACTIVE options are sellable; the list endpoint defaults to ACTIVE. Once an option leaves DRAFT it can never return to it.

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

      Multilingual text field. By default resolves to a single string in the requested language (with fallback to the default language); when showTranslations=true is 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.

    • codestringnullable

      Optional organizer-facing short code for the option. Null when not set.

      Example:
      SHARED-AM
    • scoreinteger

      Sort weight — options are ordered ascending by score. Deactivated options are automatically pushed to the bottom.

      Example:
      100
    • externalIdstringnullable

      Identifier of the option in an external availability provider (Bokun/Regiondo/Kompas). Read-only; null for native Turneo options.

    • notestring or map of string

      Multilingual text field. By default resolves to a single string in the requested language (with fallback to the default language); when showTranslations=true is 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.

    • instantUntilDurationobjectnullable

      Booking 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
      • daysinteger

        Whole days component of the duration.

        Example:
        0
      • hoursinteger

        Hours component of the duration.

        Example:
        2
      • minutesinteger

        Minutes 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)nullable

      First date of the option's availability period. Required for active options; may be null on drafts.

      Example:
      2026-07-01
    • endDatestring (date)nullable

      Last date of the option's availability period. Null means open-ended; cannot be before startDate.

      Example:
      2026-09-30
    • slotTypestringnullable

      How availability slots are scheduled — FLEXIBLE generates slots on an interval within a daily time window, FIXED uses explicit start times per weekday, DATE_ONLY has one dateless slot per day. Required for active options.

      Allowed values:
      FLEXIBLEFIXEDDATE_ONLYnull
      Example:
      FLEXIBLE
    • flexibleSlotConfigobjectnullable

      Slot generation config for FLEXIBLE options: slots are generated every interval between fromTime and toTime on the configured weekdays. Null unless slotType is FLEXIBLE.

      Child fields
      • fromTimestring

        Local time of day the first slot starts (HH:MM).

        Example:
        08:00
      • toTimestring

        Local time of day after which no more slots start (HH:MM).

        Example:
        18:00
      • intervalstring

        Gap 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[]nullable

      Slot schedule for FIXED options — a list of fixed start times per weekday set. Null unless slotType is FIXED.

      Child fields
      • timestring

        Local 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.

    • groupTypestringnullable

      Whether 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
    • slotCapacityintegernullable

      Maximum participants per slot. Null when capacity is driven by resource groups instead (the two are mutually exclusive).

      Example:
      10
    • pricingModelstringnullable

      How 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
    • durationobjectnullable

      Fixed 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
      • daysinteger

        Whole days component of the duration.

        Example:
        0
      • hoursinteger

        Hours component of the duration.

        Example:
        2
      • minutesinteger

        Minutes component of the duration.

        Example:
        30
    • durationIncrementobjectnullable

      Bookable 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
      • daysinteger

        Whole days component of the duration.

        Example:
        0
      • hoursinteger

        Hours component of the duration.

        Example:
        2
      • minutesinteger

        Minutes component of the duration.

        Example:
        30
    • durationPricingUnitstringnullable

      UI-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
    • multiDayModestringnullable

      For 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_24H runs N x 24 hours from the start instant. Ignored for sub-day options.

      Allowed values:
      ROLLING_24HCALENDAR_DAYnull
      Example:
      CALENDAR_DAY
    • allowPartialDayboolean

      For 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
    • customboolean

      True for one-off options created for a specific custom booking. Custom options are excluded from all public catalog queries.

      Example:
      false
    • earlyBirdAdvanceDaysintegernullable

      Minimum days in advance a booking must be made to earn the early bird discount. Set together with earlyBirdDiscount or not at all.

      Example:
      30
    • earlyBirdDiscountstringnullable

      Early bird discount percentage as a decimal string. Set together with earlyBirdAdvanceDays or not at all.

      Example:
      10.00
    • variantsobject[]

      Active variants of the option, subject to the restricted query 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 string

        Multilingual text field. By default resolves to a single string in the requested language (with fallback to the default language); when showTranslations=true is 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.

      • imagestringnullable

        URL of an illustrative image for the variant. Null when not set.

        Example:
        https://cdn.turneo.com/variants/boat-morning.jpg
      • maxParticipantsintegernullable

        Maximum participants a single booking of this variant may include. Null means no variant-level cap.

        Example:
        8
      • sortOrderinteger

        Ascending display position among the option's variants.

        Example:
        0
      • flatPricestringnullable

        Fixed price per booking, as a decimal string. Only set for FLAT_RATE options; null otherwise.

        Example:
        150.00
      • groupSizeUnitstringnullable

        How 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
        • minQuantityinteger

          Inclusive lower bound of the quantity band. The first tier always starts at 1.

          Example:
          1
        • maxQuantityintegernullable

          Inclusive upper bound of the quantity band. Null means open-ended ("7+"); only the last tier may be open-ended.

          Example:
          6
        • pricestring

          Price 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
        • pricestring

          Price per participant of this type, as a decimal string.

          Example:
          45.00
      • restrictedboolean

        Marks the variant as exclusive/member-only with special pricing. Filterable via the restricted query 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 string

        Multilingual text field. By default resolves to a single string in the requested language (with fallback to the default language); when showTranslations=true is 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.

      • sortOrderinteger

        Ascending display position among the option's add-ons.

        Example:
        0
      • addonTypestring

        UI behaviour — CHECKBOX is a yes/no extra, QUANTITY_SELECTOR lets the traveler pick a quantity.

        Allowed values:
        CHECKBOXQUANTITY_SELECTOR
        Example:
        QUANTITY_SELECTOR
      • perPersonboolean

        When true the add-on price is charged once per participant rather than per booking.

        Example:
        false
      • maxQuantityintegernullable

        Maximum quantity a booking may add. Null means unlimited.

        Example:
        5
      • pricestringnullable

        Price per unit of the add-on, as a decimal string. Null means free.

        Example:
        12.50
      • nonCommissionableboolean

        When 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 string

        Multilingual text field. By default resolves to a single string in the requested language (with fallback to the default language); when showTranslations=true is 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.

      • sortOrderinteger

        Ascending display position among the option's extra fields.

        Example:
        0
      • fieldTypestring

        Input type — QUESTION collects free text, CHECKBOX collects a yes/no answer.

        Allowed values:
        QUESTIONCHECKBOX
        Example:
        QUESTION
      • requiredboolean

        When 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
      • percentageAmountstring

        Discount percentage as a decimal string (e.g. "15.00" = 15% off).

        Example:
        15.00
      • startDatestring (date)nullable

        First date (inclusive) the discount applies. Null means no lower bound.

        Example:
        2026-06-01
      • endDatestring (date)nullable

        Last date (inclusive) the discount applies. Null means no upper bound.

        Example:
        2026-06-30
      • fromTimestringnullable

        Local time of day (HH:MM:SS) from which slots qualify. Null means from midnight.

        Example:
        14:00:00
      • untilTimestringnullable

        Local time of day (HH:MM:SS) until which slots qualify. Null means until midnight.

        Example:
        18:00:00
      • daysOfWeekinteger[]nullable

        Weekdays 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
      • namestringnullable

        Display 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 — resourceDetails carries 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
        • namestringnullable

          Resource name.

          Example:
          Double kayak #3
        • capacityintegernullable

          Maximum participants the resource can carry (the resource's maxParticipants). Null means uncapped.

          Example:
          2
Response 200json
{
  "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[].field and errors[].code.

401

Missing or invalid X-API-Key header.

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