> For the complete documentation index, see [llms.txt](https://syticks.gitbook.io/merpi-by-syticks/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://syticks.gitbook.io/merpi-by-syticks/api-reference/hospitality-ticketing-hotels-resorts-apartments/get-hotel-and-rooms-in-one-endpoint.md).
# Get Hotel & Rooms in One Endpoint
#### 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](/merpi-by-syticks/api-reference/hospitality-ticketing-hotels-resorts-apartments/get-list-of-hotels-apartments-resorts.md) followed by [Get Hotel Rooms](/merpi-by-syticks/api-reference/hospitality-ticketing-hotels-resorts-apartments/get-hotel-apartment-resort-rooms.md).
## 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
```bash
GET {{url}}/v2/merpi/hotels/packages?city=Lagos&available_rooms_only=true&min_price=20000&max_price=50000
```
```javascript
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)
> 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.
```json
{"openapi":"3.0.3","info":{"title":"Syticks Hospitality API","version":"2.0.0"},"paths":{"/v2/merpi/hotels/packages":{"get":{"summary":"Get hotels with rooms (Packages)","description":"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.\n","operationId":"getHotelPackages","parameters":[{"name":"business_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Filter hotels by business ID"},{"name":"city","in":"query","required":false,"schema":{"type":"string"},"description":"Filter hotels by city"},{"name":"state","in":"query","required":false,"schema":{"type":"string"},"description":"Filter hotels by state"},{"name":"country","in":"query","required":false,"schema":{"type":"string"},"description":"Filter hotels by country"},{"name":"property_type","in":"query","required":false,"schema":{"type":"string","enum":["hotel","apartment","resort","motel"]},"description":"Filter by property type"},{"name":"available_rooms_only","in":"query","required":false,"schema":{"type":"boolean"},"description":"Return only hotels with available rooms"},{"name":"min_price","in":"query","required":false,"schema":{"type":"number"},"description":"Minimum room price"},{"name":"max_price","in":"query","required":false,"schema":{"type":"number"},"description":"Maximum room price"},{"name":"min_occupancy","in":"query","required":false,"schema":{"type":"integer"},"description":"Minimum room occupancy"},{"name":"max_occupancy","in":"query","required":false,"schema":{"type":"integer"},"description":"Maximum room occupancy"},{"name":"amenities","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of amenities (e.g. wifi,pool)"},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Search hotels by name"},{"name":"per_page","in":"query","required":false,"schema":{"type":"integer"},"description":"Number of hotels per page"},{"name":"page","in":"query","required":false,"schema":{"type":"integer"},"description":"Page number"}],"responses":{"200":{"description":"List of hotel packages","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"status":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","properties":{"hotels":{"type":"array","items":{"$ref":"#/components/schemas/HotelPackage"}},"next_page":{"type":"string","nullable":true},"count":{"type":"integer"},"per_page":{"type":"integer"}}}}}}}}}}}},"components":{"schemas":{"HotelPackage":{"type":"object","description":"Hotel with nested rooms and pricing metadata","properties":{"id":{"type":"integer","description":"Unique identifier for the hotel/property"},"name":{"type":"string","description":"Name of the hotel, apartment, or resort"},"location":{"type":"string","nullable":true,"description":"Physical location/address of the property"},"description":{"type":"string","nullable":true,"description":"Detailed description of the property"},"city":{"type":"string","description":"City where the property is located"},"state":{"type":"string","description":"State/region where the property is located"},"country":{"type":"string","description":"Country where the property is located"},"coordinates":{"type":"object","nullable":true,"description":"Geographical coordinates of the property","properties":{"latitude":{"type":"number","nullable":true,"description":"Latitude coordinate"},"longitude":{"type":"number","nullable":true,"description":"Longitude coordinate"}}},"contact":{"type":"object","nullable":true,"description":"Contact information for the property","properties":{"website":{"type":"string","nullable":true,"format":"uri","description":"Property website URL"}}},"check_in_time":{"type":"string","description":"Standard check-in time"},"check_out_time":{"type":"string","description":"Standard check-out time"},"amenities":{"type":"array","description":"List of amenities available at the property","items":{"type":"string"}},"images":{"type":"array","description":"Array of property images","items":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the image"},"image_url":{"type":"string","format":"uri","description":"Full URL to the property image"},"alt_text":{"type":"string","description":"Alternative text for the image"}}}},"property_type":{"type":"string","description":"Type of property","enum":["hotel","apartment","resort","motel"]},"status":{"type":"string","description":"Current status of the property"},"business":{"type":"object","nullable":true,"description":"Business that owns/manages the property","properties":{"id":{"type":"string","format":"uuid","description":"Unique identifier for the business"},"name":{"type":"string","description":"Business name"},"photo":{"type":"string","nullable":true,"format":"uri","description":"Business logo/photo URL"},"slug":{"type":"string","description":"URL-friendly business identifier"},"type":{"type":"string","description":"Type of business"}}},"rooms":{"type":"array","description":"Array of rooms available at this property","items":{"$ref":"#/components/schemas/Room"}},"room_count":{"type":"integer","description":"Total number of room types at this property"},"available_room_count":{"type":"integer","description":"Number of room types currently available for booking"},"price_range":{"type":"object","description":"Price range across all rooms at this property","properties":{"min":{"type":"number","nullable":true,"description":"Lowest room price per night"},"max":{"type":"number","nullable":true,"description":"Highest room price per night"}}},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the property was created"},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when the property was last updated"}}},"Room":{"type":"object","description":"Room nested under a hotel package","properties":{"id":{"type":"integer","description":"Unique identifier for the room"},"hotel_id":{"type":"integer","description":"ID of the hotel this room belongs to"},"number_of_rooms":{"type":"string","description":"Number of rooms of this type available in the property"},"room_name":{"type":"string","description":"Name or category of the room"},"type":{"type":"string","nullable":true,"description":"Room type classification"},"description":{"type":"string","nullable":true,"description":"Detailed description of the room"},"max_occupancy":{"type":"integer","description":"Maximum number of guests allowed in the room"},"price":{"type":"number","description":"Total price per night in local currency (NGN).\nThis is what the customer pays. Includes base price, convenience fee, and merchant commission.\n"},"price_breakdown":{"type":"object","description":"Detailed breakdown of the total price showing individual components","properties":{"ticket_price":{"type":"number","description":"Base room price per night set by the hotel/property"},"convenience_fee":{"type":"number","description":"Platform convenience fee"},"merchant_commission":{"type":"number","description":"Merchant earning on the transaction"}},"required":["ticket_price","convenience_fee","merchant_commission"]},"is_available":{"type":"boolean","description":"Indicates if the room is currently available for booking"},"images":{"type":"array","description":"Array of room images","items":{"type":"object","properties":{"id":{"type":"integer","description":"Unique identifier for the image"},"image_url":{"type":"string","format":"uri","description":"Full URL to the room image"},"alt_text":{"type":"string","description":"Alternative text for the image"}}}},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the room was created"},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when the room was last updated"}},"required":["id","hotel_id","number_of_rooms","room_name","max_occupancy","price","price_breakdown","is_available"]}}}}
```
## Response Fields
#### Hotel Package Object
All fields from [Get List of Hotels](https://app.gitbook.com/o/SdxmAr1Slmq0wQDYbHgZ/s/2r9YlOLh3xxMyGYKBpvG/~/edit/~/changes/24/api-reference/hospitality/get-list-of-hotels#hotel-object) 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.](https://app.gitbook.com/o/SdxmAr1Slmq0wQDYbHgZ/s/2r9YlOLh3xxMyGYKBpvG/~/edit/~/changes/24/api-reference/hospitality/get-hotel-rooms#room-object)
#### 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
```javascript
// 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):
```javascript
const packages = await getHotelPackages();
// You now have hotels + rooms
// Proceed directly to booking
```
#### Using Standard Flow (2 API calls):
```javascript
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](/merpi-by-syticks/api-reference/hospitality-ticketing-hotels-resorts-apartments/book-hotel-apartment-room-tickets.md) to complete the reservation
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://syticks.gitbook.io/merpi-by-syticks/api-reference/hospitality-ticketing-hotels-resorts-apartments/get-hotel-and-rooms-in-one-endpoint.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.