KOOB API Documentation

Appearance

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. Availability and pricing are determined through the experience details and periods.

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:

json
{
  "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:

  • 1 = Monday
  • 2 = Tuesday
  • 3 = Wednesday
  • 4 = Thursday
  • 5 = Friday
  • 6 = Saturday
  • 7 = Sunday

Pricing Calculation ​

Adult and Child Pricing ​

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

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

javascript
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:

json
{
  "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"
        }
      ]
    }
  ]
}

Extra Pricing Calculation ​

When booking with extras, use the experience booking endpoint to get accurate pricing:

Request Body Example:

json
{
  "experienceId": "exp-123",
  "adults": 2,
  "childrenBirthdates": ["2010-05-15"],
  "startAt": "2024-06-15",
  "extras": [
    {
      "id": "extra-1",
      "adultCount": 2,
      "dayIndex": 1,
      "childrenBirthdates": ["2010-05-15"],
      "scope": "day"
    }
  ]
}

Pricing Factors ​

Date-based Pricing ​

Different periods may have different pricing:

json
{
  "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:

json
{
  "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:

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

Difficulty and Requirements ​

Consider participant requirements:

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