Upselling API Endpoints

This page provides the complete API reference for the Upselling API.

OpenAPI Specification

The complete OpenAPI specification for the Upselling API is available at openapi.yaml.

Room Upgrade Management Workflows

Check Available Upgrades

// Check all available room upgrades for a guest
const availableUpgrades = await fetch('/api/v1/upselling/room-upgrades/available', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${staffToken}`
  },
  params: new URLSearchParams({
    guest_id: 'guest_123',
    current_room_type: 'standard_king',
    check_in_date: '2024-01-15',
    check_out_date: '2024-01-18',
    party_size: 2,
    include_pricing: true,
    include_amenities: true
  })
});

const {
  available_upgrades,
  pricing_options,
  inventory_status,
  recommendation_score
} = await availableUpgrades.json();

Create Personalized Upgrade Offer

// Create a targeted room upgrade offer with dynamic pricing
const upgradeOffer = await fetch('/api/v1/upselling/room-upgrades/create-offer', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${staffToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    guest_id: 'guest_123',
    current_booking_id: 'booking_789',
    upgrade_details: {
      from_room_type: 'standard_king',
      to_room_type: 'deluxe_suite',
      upgrade_amenities: ['balcony', 'city_view', 'premium_bath']
    },
    pricing_strategy: {
      base_price: 120,
      discount_percentage: 20,
      dynamic_pricing_enabled: true,
      loyalty_discount_applied: true
    },
    offer_parameters: {
      valid_until: '2024-01-14T18:00:00Z',
      communication_channel: 'whatsapp',
      personalization_level: 'high',
      urgency_factor: 'limited_availability'
    },
    guest_context: {
      loyalty_tier: 'gold',
      previous_upgrades: 3,
      spending_history: 'above_average',
      special_occasion: 'anniversary',
      arrival_time: '2024-01-15T15:00:00Z'
    }
  })
});

const {
  offer_id,
  final_upgrade_price,
  savings_amount,
  personalized_message,
  expires_at,
  acceptance_probability
} = await upgradeOffer.json();

Process Upgrade Acceptance

// Handle guest acceptance of upgrade offer
const processUpgrade = await fetch(`/api/v1/upselling/room-upgrades/${offerId}/accept`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${staffToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    guest_confirmation: true,
    payment_details: {
      payment_method: 'room_charge',
      authorization_amount: 96.00,
      currency: 'USD'
    },
    preferences: {
      floor_preference: 'high_floor',
      room_features: ['city_view', 'balcony'],
      arrival_instructions: 'early_checkin_if_possible'
    },
    confirmation_preferences: {
      send_confirmation_email: true,
      send_whatsapp_confirmation: true,
      include_amenity_details: true
    }
  })
});

const {
  upgrade_confirmed,
  new_room_assignment,
  confirmation_code,
  additional_charges,
  amenity_details,
  check_in_instructions
} = await processUpgrade.json();

Personalized Service Recommendations

Generate AI-Powered Recommendations

// Generate personalized service recommendations using AI
const serviceRecommendations = await fetch('/api/v1/upselling/recommendations/generate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${staffToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    guest_id: 'guest_123',
    recommendation_context: {
      stay_purpose: 'leisure',
      stay_duration: 4,
      party_composition: {
        adults: 2,
        children: 0,
        special_needs: []
      },
      arrival_date: '2024-01-15',
      budget_indication: 'premium',
      weather_context: 'sunny_warm'
    },
    guest_preferences: {
      interests: ['spa_wellness', 'fine_dining', 'outdoor_activities'],
      dietary_restrictions: ['vegetarian'],
      mobility_requirements: [],
      previous_bookings: ['spa_massage', 'wine_tasting', 'local_tour'],
      communication_style: 'detailed_informative'
    },
    business_factors: {
      inventory_priorities: ['spa_services', 'dining_experiences'],
      promotional_campaigns: ['couples_spa_package', 'anniversary_dining'],
      revenue_targets: 'above_average_upsell',
      staff_availability: 'full_service_available'
    },
    recommendation_parameters: {
      max_recommendations: 6,
      include_alternatives: true,
      price_sensitivity: 'medium',
      timing_flexibility: 'high'
    }
  })
});

const {
  recommendations,
  total_potential_revenue,
  personalization_score,
  confidence_levels,
  optimal_presentation_order
} = await serviceRecommendations.json();

Contextual Upselling During Stay

// Generate context-aware upselling opportunities based on guest activity
const contextualRecommendations = await fetch('/api/v1/upselling/recommendations/contextual', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${staffToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    guest_id: 'guest_123',
    current_context: {
      location: 'spa_reception',
      time_of_day: 'afternoon',
      current_activity: 'spa_treatment_inquiry',
      companion_presence: true,
      previous_services_today: ['breakfast_room_service']
    },
    conversation_history: [
      {
        topic: 'massage_availability',
        sentiment: 'positive',
        interest_level: 'high'
      }
    ],
    real_time_factors: {
      weather: 'rainy',
      hotel_events: ['wine_tasting_evening'],
      availability_status: {
        spa: 'moderate_availability',
        restaurants: 'high_availability',
        activities: 'limited_availability'
      }
    }
  })
});

Dynamic Pricing and Optimization

Calculate Dynamic Pricing

// Calculate optimized pricing for services and upgrades
const dynamicPricing = await fetch('/api/v1/upselling/pricing/calculate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${staffToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    pricing_request: {
      service_type: 'room_upgrade',
      from_category: 'standard_king',
      to_category: 'luxury_suite',
      service_dates: ['2024-01-15', '2024-01-16', '2024-01-17']
    },
    guest_profile: {
      guest_id: 'guest_123',
      loyalty_tier: 'platinum',
      booking_channel: 'direct_website',
      advance_booking_days: 14,
      historical_spending: 'high_value',
      price_sensitivity: 'low'
    },
    market_context: {
      occupancy_forecast: 0.85,
      competitor_pricing: {
        similar_upgrades_avg: 150,
        market_position: 'premium'
      },
      demand_indicators: 'high',
      seasonal_factors: 'peak_season'
    },
    business_objectives: {
      revenue_priority: 'maximize_profit',
      inventory_optimization: true,
      guest_satisfaction_weight: 0.8
    }
  })
});

const {
  recommended_price,
  price_breakdown,
  pricing_factors,
  confidence_score,
  alternative_pricing_scenarios,
  expected_acceptance_rate
} = await dynamicPricing.json();

Real-time Price Optimization

// Get real-time price optimization for multiple services
const priceOptimization = await fetch('/api/v1/upselling/pricing/optimize', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${staffToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    optimization_scope: {
      services: [
        { type: 'spa_treatment', service_id: 'couples_massage' },
        { type: 'dining_experience', service_id: 'chef_tasting_menu' },
        { type: 'room_upgrade', from: 'deluxe', to: 'suite' }
      ],
      guest_segment: 'high_value_leisure',
      time_horizon: '24_hours'
    },
    optimization_criteria: {
      primary_objective: 'revenue_maximization',
      constraints: {
        min_margin_percentage: 0.3,
        max_discount_percentage: 0.25,
        guest_satisfaction_threshold: 4.2
      },
      market_responsiveness: 'high'
    }
  })
});

Campaign Management and Performance

Create Targeted Upselling Campaign

// Create comprehensive upselling campaign with targeting and messaging
const campaign = await fetch('/api/v1/upselling/campaigns/create', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${staffToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    campaign_details: {
      name: 'Premium Spa Weekend Experience',
      type: 'service_package_promotion',
      objective: 'revenue_growth',
      category: 'wellness_upselling'
    },
    target_audience: {
      guest_segments: ['leisure_travelers', 'couples', 'wellness_enthusiasts'],
      loyalty_tiers: ['gold', 'platinum'],
      demographic_filters: {
        age_range: [25, 65],
        spending_history: 'above_average'
      },
      behavioral_criteria: {
        previous_spa_bookings: true,
        stay_duration_min: 2,
        advance_booking_days: 7
      }
    },
    offer_structure: {
      service_package: {
        included_services: ['couples_massage', 'facial_treatment', 'spa_lunch'],
        package_value: 400,
        promotional_price: 320,
        savings_amount: 80
      },
      incentives: {
        early_booking_bonus: 'champagne_welcome',
        loyalty_points_multiplier: 2.0,
        complimentary_amenities: ['spa_robes', 'premium_toiletries']
      }
    },
    campaign_schedule: {
      start_date: '2024-02-01T00:00:00Z',
      end_date: '2024-02-29T23:59:59Z',
      booking_window: '2024-01-15T00:00:00Z',
      blackout_dates: ['2024-02-14', '2024-02-15'],
      optimal_delivery_times: ['10:00-12:00', '15:00-17:00']
    },
    messaging_strategy: {
      communication_channels: ['email', 'whatsapp', 'mobile_app'],
      message_personalization: 'high',
      follow_up_sequence: {
        initial_contact: 'immediate',
        reminder_1: '3_days_later',
        final_offer: '1_day_before_expiry'
      },
      creative_elements: {
        imagery_theme: 'luxury_wellness',
        tone_of_voice: 'elegant_inviting',
        call_to_action: 'Book Your Spa Escape'
      }
    }
  })
});

const {
  campaign_id,
  estimated_reach,
  projected_revenue,
  launch_schedule,
  tracking_metrics,
  optimization_recommendations
} = await campaign.json();

Campaign Performance Analytics

// Get detailed campaign performance metrics
const campaignAnalytics = await fetch(`/api/v1/upselling/campaigns/${campaignId}/analytics`, {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${staffToken}`
  },
  params: new URLSearchParams({
    metrics: 'conversion_rates,revenue_attribution,segment_performance,channel_effectiveness',
    breakdown: 'daily',
    include_comparisons: true
  })
});

const {
  performance_summary,
  conversion_metrics,
  revenue_analytics,
  segment_analysis,
  channel_performance,
  guest_feedback_correlation,
  optimization_opportunities
} = await campaignAnalytics.json();

Service Booking and Integration

Book Recommended Services

// Process booking for recommended services with full integration
const serviceBooking = await fetch('/api/v1/upselling/services/book', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${staffToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    guest_id: 'guest_123',
    booking_details: {
      service_id: 'premium_spa_package',
      recommendation_id: 'rec_spa_001',
      selected_date: '2024-01-16',
      selected_time: '14:00:00',
      duration: 180,
      participant_count: 2
    },
    service_customization: {
      massage_type: 'swedish_relaxation',
      pressure_preference: 'medium',
      aromatherapy_selection: 'lavender_eucalyptus',
      music_preference: 'nature_sounds',
      special_requests: ['couples_suite', 'champagne_service']
    },
    payment_integration: {
      payment_method: 'room_charge',
      billing_authorization: true,
      promotional_code: 'ANNIVERSARY20',
      loyalty_points_redemption: 500
    },
    confirmation_preferences: {
      confirmation_channels: ['email', 'whatsapp'],
      include_preparation_instructions: true,
      send_reminder_notifications: true,
      calendar_integration: true
    }
  })
});

const {
  booking_confirmation,
  service_details,
  total_investment,
  savings_applied,
  confirmation_codes,
  next_steps,
  cancellation_policy
} = await serviceBooking.json();

Advanced Analytics and Reporting

Comprehensive Upselling Analytics

// Get comprehensive upselling performance analytics
const upsellAnalytics = await fetch('/api/v1/upselling/analytics/comprehensive', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${staffToken}`
  },
  params: new URLSearchParams({
    analysis_period: 'last_90_days',
    metrics: 'revenue_impact,conversion_rates,guest_satisfaction,roi_analysis',
    segmentation: 'guest_tier,service_category,communication_channel',
    include_predictions: true
  })
});

const {
  revenue_performance,
  conversion_analytics,
  guest_impact_analysis,
  roi_metrics,
  trend_analysis,
  predictive_insights,
  benchmarking_data,
  optimization_recommendations
} = await upsellAnalytics.json();

Revenue Attribution Analysis

// Detailed revenue attribution for upselling activities
const revenueAttribution = await fetch('/api/v1/upselling/analytics/revenue-attribution', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${staffToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    attribution_scope: {
      time_period: {
        start_date: '2024-01-01',
        end_date: '2024-01-31'
      },
      service_categories: ['room_upgrades', 'spa_services', 'dining_experiences'],
      guest_segments: ['all']
    },
    attribution_model: 'multi_touch_with_decay',
    analysis_dimensions: [
      'campaign_performance',
      'channel_effectiveness',
      'staff_contribution',
      'guest_lifetime_value_impact'
    ]
  })
});

Error Handling and Best Practices

Error Response Examples

{
  "error": {
    "code": "INSUFFICIENT_INVENTORY",
    "message": "Requested room upgrade not available for selected dates",
    "details": {
      "requested_room_type": "luxury_suite",
      "available_alternatives": [
        {
          "room_type": "premium_king",
          "availability": "full",
          "price_difference": -50
        }
      ],
      "next_available_date": "2024-01-20",
      "waitlist_available": true
    },
    "recovery_options": [
      "Select alternative room type",
      "Modify stay dates",
      "Join waitlist for preferred room type",
      "Book alternative premium services"
    ]
  }
}

Common Error Codes

• INSUFFICIENT_INVENTORY (409) - Requested service or upgrade not available
• PRICING_SERVICE_UNAVAILABLE (503) - Dynamic pricing service temporarily unavailable
• GUEST_NOT_ELIGIBLE (403) - Guest doesn't meet criteria for specific offer
• CAMPAIGN_EXPIRED (410) - Promotional campaign no longer active
• PAYMENT_PROCESSING_ERROR (402) - Payment authorization or processing failed
• INVALID_BOOKING_WINDOW (422) - Booking request outside allowed time window
• MAXIMUM_UPSELLS_REACHED (429) - Guest has reached maximum upsell limit
• SERVICE_TEMPORARILY_UNAVAILABLE (503) - Requested service temporarily unavailable

Best Practices for Implementation

1. Guest-Centric Approach - Always prioritize guest satisfaction over pure revenue optimization
2. Personalization Balance - Use data intelligently without being intrusive
3. Timing Optimization - Respect guest preferences and communication frequency limits
4. Value Communication - Clearly articulate benefits and value proposition
5. Flexible Options - Provide alternatives and customization opportunities
6. Feedback Integration - Use guest responses to improve future recommendations