Experience Availability and Pricing

Overview

Experience availability and pricing depend on various factors including dates, group size, age composition, and selected periods. This guide covers how to check availability and get accurate pricing for experiences.

Understanding Experience Pricing

Experiences use different pricing models:

• FIT (Free Independent Traveler): Individual pricing per person
• SIC (Seat in Coach): Shared group pricing
• Series: Fixed departure group pricing

Pricing can be:

• Per Person: Price multiplied by number of participants
• Per Group: Fixed price regardless of group size
• Age-based: Different rates for adults and children

Check Experience Availability

Unlike hotels, experiences don't have a separate availability endpoint. There are two complementary sources:

• To get a bookable quote, run the experience search with startAt and experienceComposition — each result returns a price object whose priceId is the booking handshake. This is the path to follow to book.
• To understand the offer (seasons, operating days, group rules, price tiers), read the periods array on the experience details, described below. Periods explain why a date or party prices the way it does; the priced search remains the source of truth for the actual amount.

Get Experience Periods and Pricing

When retrieving experience details, the periods array contains availability and pricing information:

Endpoint: GET /api/v1/experiences/{experienceId}

Key Response Fields:

{
  "id": "exp-123",
  "name": "Louvre Museum Private Tour",
  "periods": [
    {
      "id": "period-1",
      "startAt": "2024-06-01",
      "endAt": "2024-08-31",
      "availableDays": [1, 2, 3, 4, 5, 6],
      "periodType": "free_sale",
      "state": "free_sale",
      "price": 150.00,
      "perPax": true,
      "minPax": 1,
      "maxPax": 8,
      "minPaxForDeparture": "2",
      "currentPaxForDeparture": "0",
      "allotments": "20",
      "allotmentsUsed": "5",
      "breakEven": 2,
      "adultPax": [
        {
          "id": "adult-1",
          "price": 150.00,
          "paxRange": [1, 8]
        }
      ],
      "childrenPax": [
        {
          "id": "child-1", 
          "price": 75.00,
          "ageRange": [6, 17]
        }
      ]
    }
  ]
}

Availability States

Experience availability is determined by the periodType and state fields:

Period Types and States

• free_sale: Available for immediate booking
• on_request: Requires confirmation from supplier
• pre_confirmed: Conditionally available pending final confirmation
• stop_sale: Not available for booking

Available Days

The availableDays array indicates which days of the week the experience operates. The shape differs between reading and writing:

• When reading experience details, it is the list of operating day numbers: 1 = Monday through 7 = Sunday. [1, 2, 3, 4, 5] means weekdays only.
• When creating or updating an experience (see Manage Experiences), it is a fixed 7-flag array, Monday first: [1, 1, 1, 1, 1, 0, 0] means weekdays only.

Pricing Calculation

Adult and Child Pricing

Experiences may have different pricing tiers based on group size and age:

{
  "adultPax": [
    {
      "price": 150.00,
      "paxRange": [1, 4]
    },
    {
      "price": 120.00,
      "paxRange": [5, 8]
    }
  ],
  "childrenPax": [
    {
      "price": 75.00,
      "ageRange": [6, 12]
    },
    {
      "price": 100.00,
      "ageRange": [13, 17]
    }
  ]
}

Group Size Requirements

• minPax: Minimum participants required
• maxPax: Maximum participants allowed
• minPaxForDeparture: Minimum bookings needed for departure
• currentPaxForDeparture: Current confirmed participants

Allotment Management

Allotment Fields

• allotments: Total available spots
• allotmentsUsed: Currently booked spots
• breakEven: Minimum participants needed for profitability

Calculating Availability

Available spots = allotments - allotmentsUsed

const availableSpots = parseInt(period.allotments) - parseInt(period.allotmentsUsed);
const canBook = availableSpots >= requestedPax && requestedPax >= period.minPax && requestedPax <= period.maxPax;

Experience Extras and Add-ons

Extra Pricing

Experiences may offer additional services or upgrades:

{
  "extras": [
    {
      "id": "extra-1",
      "name": "Private Transportation",
      "cancellationPolicies": "48-hour cancellation required",
      "recommendations": [
        {
          "id": "rec-1",
          "name": "Wine Tasting Addition"
        }
      ],
      "required": [],
      "suggested": [
        {
          "id": "sug-1", 
          "name": "Photo Package"
        }
      ]
    }
  ]
}

Booking with extras

Extras priced with the offer come back inside the search result's price.extras. To include one in a booking, add it to the extras array of the booking request: each entry declares who takes it (adultCount, childrenBirthdates) and its scope — global (once for the whole experience) or day (a specific day of a program, selected with dayIndex).

Pricing Factors

Date-based Pricing

Different periods may have different pricing:

{
  "periods": [
    {
      "id": "low-season",
      "startAt": "2024-01-01",
      "endAt": "2024-05-31", 
      "price": 120.00
    },
    {
      "id": "high-season",
      "startAt": "2024-06-01",
      "endAt": "2024-08-31",
      "price": 150.00
    }
  ]
}

Group Size Discounts

Larger groups may qualify for reduced per-person rates:

{
  "adultPax": [
    {
      "price": 150.00,
      "paxRange": [1, 2]
    },
    {
      "price": 130.00,
      "paxRange": [3, 5]
    },
    {
      "price": 110.00,
      "paxRange": [6, 8]
    }
  ]
}

Special Considerations

Room Supplements

Some experiences include accommodation or have room-related charges:

• roomSupplement: Additional cost per room
• hasRoomSupplement: Whether room charges apply

Guided Experience Languages

Check available guide languages:

{
  "guiding": true,
  "guidingLanguages": ["English", "French", "Spanish", "German"]
}

Difficulty and Requirements

Consider participant requirements:

{
  "difficulty": "Moderate",
  "includedServices": "Professional guide, entrance fees, equipment",
  "excludedServices": "Transportation, meals, personal expenses"
}