Retrieve an option

GET/v2/options/{optionId}

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

Retrieves a single option by UUID, with its full tree of variants (including pricing tiers and per-participant prices), add-ons, extra fields, discounts and resource groups.

Unlike the list endpoint, no status filter applies here: DRAFT and INACTIVE options resolve normally. Soft-deleted options return 404.

The restricted, language and showTranslations query parameters behave exactly as on the list endpoint (see listOptions).

Requestbash
curl "https://api.turneo.co/v2/options/0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d" \
  -H "X-API-Key: <your-api-key>"

Path parameters

  • optionIdstring (uuid)required

    UUID of the option.

    Example:
    0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d

Query parameters

  • restrictedstring

    Variant visibility filter — same semantics as on listOptions.

    Allowed values:
    truefalse
    Example:
    true
  • languagestring

    Language code used to resolve multilingual fields.

    Example:
    en
  • showTranslationsstring

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

    Allowed values:
    truefalse
    Example:
    false

Responses

200object

The option with its full nested configuration tree.

  • 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
{
  "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

401

Missing or invalid X-API-Key header.

404

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

Error body
  • typestring

    Error class.

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

      Machine-readable error code.

      Example:
      required
    • fieldstringnullable

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

      Example:
      startTime
    • messagestring

      Human-readable message.

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