Skip to main content

Use Cases

This guide covers common use cases and integration patterns for the Bundleport Connect Hotels API.

Travel Agency Integration​

Scenario​

A travel agency needs to integrate hotel booking into their existing booking system to offer hotel reservations alongside flights and other travel services.

Implementation Flow​

  1. Search for hotels when customer selects destination and dates
  2. Display results with pricing, amenities, and cancellation policies
  3. Quote selected option before showing final price to customer
  4. Create booking when customer confirms
  5. Store booking references in agency's CRM system
  6. Handle cancellations when needed

Code Example​

// Search for hotels
const searchResponse = await fetch('https://api.bundleport.com/hotels/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    stay: {
      checkIn: '2025-12-15',
      checkOut: '2025-12-17',
    },
    destination: { code: 'BCN' },
    occupancies: [{ adults: 2 }],
    filters: { currency: 'EUR' },
  }),
});

const { options } = await searchResponse.json();

// Display options to customer, then quote before booking
const selectedOption = options[0];
const quoteResponse = await fetch('https://api.bundleport.com/hotels/v1/recheck', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    optionRefId: selectedOption.optionRefId,
  }),
});

const quote = await quoteResponse.json();

// Create booking when customer confirms
const bookingResponse = await fetch('https://api.bundleport.com/hotels/v1/bookings', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    optionRefId: selectedOption.optionRefId,
    holder: {
      name: 'John',
      surname: 'Doe',
      email: 'john@example.com',
      phone: '+34600123456',
    },
    rooms: [{
      occupancyRefId: 1,
      paxes: [
        { name: 'John', surname: 'Doe', age: 35 },
        { name: 'Jane', surname: 'Doe', age: 33 },
      ],
    }],
  }),
});

const booking = await bookingResponse.json();

// Store in your CRM
await saveToCRM({
  bookingId: booking.booking.bookingId,
  clientReference: `AGENCY-${Date.now()}`,
  providerReference: booking.booking.providerReference,
});

Key Considerations​

  • Quote before booking: Always quote immediately before booking to avoid price changes
  • Store all references: Keep Bundleport booking ID, provider reference, and your own client reference
  • Handle cancellations: Implement cancellation flow for customer-initiated cancellations
  • Monitor webhooks: Set up webhooks for booking status changes

B2C Hotel Portal​

Scenario​

A consumer-facing hotel booking website needs to display hotel options, allow customers to book directly, and manage their reservations.

Implementation Flow​

  1. Pre-load content: Use Content API to cache hotel, destination, and room data
  2. Search on user input: Trigger search as user selects dates/destination
  3. Real-time pricing: Quote options when user views details
  4. Guest checkout: Collect minimal information for booking
  5. Confirmation page: Display booking details and send confirmation email
  6. My Bookings: Allow customers to view and cancel their bookings

Code Example​

// Pre-load hotel content (cache for better performance)
const hotelsResponse = await fetch('https://api.bundleport.com/content/hotels/v1/hotels', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: {
      destinationCodes: ['BCN', 'MAD', 'PMI'],
      maxSize: 100,
    },
  }),
});

const hotels = await hotelsResponse.json();
// Cache this data for quick display

// When user searches, use Booking API for live availability
const searchResponse = await fetch('https://api.bundleport.com/hotels/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    stay: {
      checkIn: userSelectedCheckIn,
      checkOut: userSelectedCheckOut,
    },
    destination: { code: userSelectedDestination },
    occupancies: [{ adults: userSelectedAdults }],
    filters: {
      currency: userSelectedCurrency,
      minPrice: userSelectedMinPrice,
      maxPrice: userSelectedMaxPrice,
    },
  }),
});

// Display results, allow filtering/sorting
// When user clicks "Book Now", quote then create booking

Key Considerations​

  • Content caching: Use Content API to pre-load hotel data for faster page loads
  • Progressive enhancement: Show cached content first, then update with live pricing
  • User experience: Implement loading states, error handling, and retry logic
  • Mobile optimization: Ensure search and booking flows work well on mobile devices

Corporate Travel Management​

Scenario​

A corporate travel management system needs to book hotels for business travelers with company policies, approval workflows, and expense integration.

Implementation Flow​

  1. Policy enforcement: Filter search results based on company travel policies
  2. Approval workflow: Require approval before booking
  3. Corporate rates: Prefer negotiated rates when available
  4. Expense integration: Link bookings to expense reports
  5. Traveler profiles: Use saved traveler information
  6. Reporting: Track bookings, costs, and compliance

Code Example​

// Search with corporate policy filters
const searchResponse = await fetch('https://api.bundleport.com/hotels/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    stay: {
      checkIn: tripRequest.checkIn,
      checkOut: tripRequest.checkOut,
    },
    destination: { code: tripRequest.destination },
    occupancies: [{ adults: 1 }],
    filters: {
      currency: 'EUR',
      // Apply corporate policy limits
      minPrice: 0,
      maxPrice: tripRequest.maxBudget, // From company policy
      // Prefer specific hotel chains if negotiated
      hotelCodes: companyPreferredHotels,
    },
  }),
});

// Filter results by additional policies
const compliantOptions = options.filter(option => {
  return option.price.net <= tripRequest.maxBudget &&
         option.hotel.categoryCode >= companyPolicy.minCategory;
});

// After approval, create booking
// Store with expense report reference

Key Considerations​

  • Policy enforcement: Implement business rules on top of API responses
  • Approval workflows: Integrate with your approval system before booking
  • Audit trails: Log all booking attempts and policy decisions
  • Reporting: Use booking list endpoint with filters for compliance reporting

Hotel Aggregator Platform​

Scenario​

A platform that aggregates hotel inventory from multiple sources and provides a unified API to downstream partners.

Implementation Flow​

  1. Multi-supplier search: Bundleport handles supplier aggregation automatically
  2. Normalized results: All suppliers return data in the same format
  3. Smart routing: Bundleport selects best supplier based on availability and pricing
  4. Fallback handling: If one supplier fails, others are automatically tried
  5. Unified booking: Single booking flow regardless of supplier
  6. Supplier reporting: Track performance by supplier

Key Considerations​

  • Leverage aggregation: Bundleport already handles multi-supplier logic
  • Monitor warnings: Use warnings field to detect supplier issues
  • Tracing data: Use tracing field to understand supplier performance
  • Supplier health: Track availability rates and response times by supplier

Best Practices Across All Use Cases​

1. Always Quote Before Booking​

// ✅ Good: Quote then book
const quote = await quoteOption(optionRefId);
if (quote.priceChanged) {
  // Show updated price to user
}
const booking = await bookOption(optionRefId, travelerData);

// ❌ Bad: Book without quoting
const booking = await bookOption(optionRefId, travelerData);
// May fail or have unexpected price changes

2. Implement Proper Error Handling​

try {
  const booking = await createBooking(bookingData);
} catch (error) {
  if (error.code === 'PRICE_CHANGED') {
    // Re-quote and show updated price
  } else if (error.code === 'NO_AVAILABILITY') {
    // Search again with different criteria
  } else {
    // Log error and show user-friendly message
  }
}

3. Use Webhooks for Real-Time Updates​

// Set up webhook endpoint
app.post('/webhooks/bookings', async (req, res) => {
  const { event, data } = req.body;
  
  if (event === 'booking.confirmed') {
    await sendConfirmationEmail(data);
    await updateCRM(data);
  } else if (event === 'booking.cancelled') {
    await processRefund(data);
  }
  
  res.status(200).send('OK');
});

4. Cache Content Data​

// Cache hotel content (changes infrequently)
const cacheKey = `hotels-${destinationCode}`;
let hotels = cache.get(cacheKey);

if (!hotels || cache.isExpired(cacheKey)) {
  hotels = await getHotelsFromContentAPI(destinationCode);
  cache.set(cacheKey, hotels, { ttl: 3600 }); // 1 hour cache
}

5. Monitor Rate Limits​

// Check rate limit headers
const response = await makeAPIRequest();
const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));

if (remaining < 10) {
  console.warn('Rate limit approaching');
  // Implement queuing or backoff
}

Next Steps​