Get Hotel & Rooms in One Endpoint

Get complete hotel and room information in a single API call. This endpoint is specifically designed for POS terminal integrations and scenarios where you need all booking information at once.

GET /v2/merpi/hotels/packages

Designed for POS Terminal Integrations

Retrieve complete hotel and room information in a single API call. This endpoint is specifically designed for PTSP license providers and POS terminal integrations where you need all relevant booking data at once to minimize API calls and create a streamlined booking flow.

Instead of making separate calls to get hotels and then rooms, this endpoint returns everything together.

When to Use This Endpoint

✅ Use this if you're:

• Building a POS terminal integration

• Working in a constrained environment with limited API calls

• Need hotel + room data in one response

• Want a simplified integration flow

❌ Don't use this if you're:

• Building a web/mobile app with multiple screens

• Want to show hotels first, then rooms on a separate page

• Need progressive loading for better UX

For standard web/mobile integrations, use Get List of Hotels followed by Get Hotel Rooms.

Query Parameters

Parameter	Type	Required	Description
business_id	string	No	Filter hotels by specific hospitality business
city	string	No	Filter by city name
state	string	No	Filter by state
country	string	No	Filter by country (default: "Nigeria")
property_type	string	No	Filter by property type: hotel, apartment, resort, inn
available_rooms_only	boolean	No	If true, only return hotels with available rooms
min_price	number	No	Minimum room price per night (in Naira)
max_price	number	No	Maximum room price per night (in Naira)
min_occupancy	number	No	Minimum guest capacity per room
max_occupancy	number	No	Maximum guest capacity per room
amenities	string	No	Comma-separated amenities
search	string	No	Search term for hotel name or description
per_page	number	No	Number of results per page (default: 20)
page	number	No	Page number for pagination (default: 1)

Example Request

GET {{url}}/v2/merpi/hotels/packages?city=Lagos&available_rooms_only=true&min_price=20000&max_price=50000

const response = await fetch('{{url}}/v2/merpi/hotels/packages?city=Lagos&available_rooms_only=true', {
  method: 'GET',
  headers: {
    'X-API-KEY': 'your_api_key_here',
    'TransactionMedium': 'POS'  // Typically used for POS integrations
  }
});
const data = await response.json();

Get hotels with rooms (Packages)

get

Retrieve a list of hotels with their available rooms nested in the same response. This endpoint returns multiple hotels, each including its rooms with complete pricing breakdown, price range, and availability metadata. It is optimized for POS terminal integrations and constrained environments where minimizing API calls is required.

Query parameters

business_idstring · uuidOptional

Filter hotels by business ID

citystringOptional

Filter hotels by city

statestringOptional

Filter hotels by state

countrystringOptional

Filter hotels by country

property_typestring · enumOptional

Filter by property type

Possible values:

available_rooms_onlybooleanOptional

Return only hotels with available rooms

min_pricenumberOptional

Minimum room price

max_pricenumberOptional

Maximum room price

min_occupancyintegerOptional

Minimum room occupancy

max_occupancyintegerOptional

Maximum room occupancy

amenitiesstringOptional

Comma-separated list of amenities (e.g. wifi,pool)

searchstringOptional

Search hotels by name

per_pageintegerOptional

Number of hotels per page

Example: 20

pageintegerOptional

Page number

Example: 1

Responses

200

List of hotel packages

application/json

successbooleanOptionalExample: true

statusintegerOptionalExample: 200

messagestringOptionalExample: List of hotel packages

get

/v2/merpi/hotels/packages

HTTPcURLJavaScriptPython

GET /v2/merpi/hotels/packages HTTP/1.1
Accept: */*

200

List of hotel packages

{
  "success": true,
  "status": 200,
  "message": "List of hotel packages",
  "data": {
    "hotels": [
      {
        "id": 16,
        "name": "Grand Paradise Hotel",
        "location": "Downtown City",
        "description": "A luxurious hotel with modern amenities.",
        "city": "Lagos",
        "state": "Lagos",
        "country": "Nigeria",
        "coordinates": {
          "latitude": 6.5244,
          "longitude": 3.3792
        },
        "contact": {
          "website": "https://grandparadise.com"
        },
        "check_in_time": "2PM",
        "check_out_time": "11AM",
        "amenities": [
          "Pool",
          "Spa",
          "Restaurant"
        ],
        "images": [],
        "property_type": "hotel",
        "status": "active",
        "business": {
          "id": "abd5b9d4-f98f-483c-b0a4-eaadcdc776fa",
          "name": "Stay-IN",
          "photo": null,
          "slug": "stay-in",
          "type": "hospitality"
        },
        "rooms": [
          {
            "id": 9,
            "hotel_id": 16,
            "number_of_rooms": "23",
            "room_name": "Deluze",
            "type": null,
            "description": null,
            "max_occupancy": 2,
            "price": 38000,
            "price_breakdown": {
              "ticket_price": 37500,
              "convenience_fee": 100,
              "merchant_commission": 400
            },
            "is_available": true,
            "images": [],
            "created_at": "2025-09-10T00:56:46.000000Z",
            "updated_at": "2025-09-10T00:56:46.000000Z"
          }
        ],
        "room_count": 2,
        "available_room_count": 2,
        "price_range": {
          "min": 26134.75,
          "max": 38000
        },
        "created_at": "2025-09-07T23:26:12.000000Z",
        "updated_at": "2025-09-09T22:07:11.000000Z"
      }
    ],
    "next_page": "2",
    "count": 22,
    "per_page": 20
  }
}

Response Fields

Hotel Package Object

All fields from Get List of Hotels plus:

Field	Type	Description
business	object	Hospitality business information
rooms	array	Complete list of available rooms (see Room Object below)
room_count	number	Total number of room types at this property
available_room_count	number	Number of currently available room types
price_range	object	Min and max room prices at this hotel

Room Object (nested in rooms array)

Same structure as Get Hotel Rooms response.

Price Range Object

Field	Type	Description
min	number|null	Lowest room price per night in Naira
max	number|null	Highest room price per night in Naira

POS Terminal Integration Example

// Single API call gets everything needed for booking
const packages = await fetch('/v2/merpi/hotels/packages?city=Lagos&available_rooms_only=true');
const data = await packages.json();

// Display on POS screen
data.data.hotels.forEach((hotel, hotelIndex) => {
  console.log(`\n${hotelIndex + 1}. ${hotel.name}`);
  console.log(`   Location: ${hotel.location}`);
  console.log(`   Price Range: ₦${hotel.price_range.min} - ₦${hotel.price_range.max}`);
  
  // Show available rooms
  hotel.rooms.forEach((room, roomIndex) => {
    console.log(`   ${hotelIndex + 1}.${roomIndex + 1} ${room.room_name}: ₦${room.price}/night`);
  });
});

// Customer selects: Hotel 1, Room 2 (Basic)
const selectedHotel = data.data.hotels[0];
const selectedRoom = selectedHotel.rooms[1];

// Proceed directly to booking with room_id
const booking = {
  room_id: selectedRoom.id,
  // ... rest of booking details
};

Comparison: Packages vs Standard Flow

Using Hotels & Rooms in One Endpoint (1 API call):

const packages = await getHotelPackages();
// You now have hotels + rooms
// Proceed directly to booking

Using Standard Flow (2 API calls):

const hotels = await getHotels();
// User selects hotel
const rooms = await getHotelRooms(selectedHotelId);
// User selects room
// Proceed to booking

Next Steps

After retrieving hotel packages:

1. Display hotels and their available rooms to the user

2. Allow user to select hotel and room type

3. Proceed directly to Book Hotel Room to complete the reservation