REST API

WP Hotelier provides a REST API that allows you to access rooms, reservations, availability, and hotel settings programmatically. This is useful for building custom frontends, mobile apps, or integrating with third-party services.

Introduction

The WP Hotelier REST API is built on top of the WordPress REST API infrastructure. All endpoints are prefixed with the hotelier/v1 namespace.

Base URL:

https://yoursite.com/wp-json/hotelier/v1/

Content Type: All requests and responses use JSON format (application/json).

Price Format

All prices in the API are returned as integers in the smallest currency unit (e.g., cents for USD/EUR). For example, a price of $150.00 is returned as 15000. This ensures precision and avoids floating-point issues.

To convert to a display format, divide by 100 (or the appropriate factor for your currency).

Authentication

The WP Hotelier REST API uses WordPress Application Passwords (introduced in WordPress 5.6) for authentication. Some endpoints are public and don't require authentication, while others require specific capabilities.

Creating an Application Password

  1. Go to Users > Profile in your WordPress admin
  2. Scroll down to the Application Passwords section
  3. Enter a name for the application (e.g., "My Booking App")
  4. Click Add New Application Password
  5. Copy the generated password (it will only be shown once)

Using Application Passwords

Use HTTP Basic Authentication with your WordPress username and the application password. The credentials should be base64 encoded in the format username:application_password.

curl https://yoursite.com/wp-json/hotelier/v1/reservations \
    -u your_username:xxxx xxxx xxxx xxxx xxxx xxxx

Or with the Authorization header:

curl https://yoursite.com/wp-json/hotelier/v1/reservations \
    -H "Authorization: Basic base64(username:application_password)"

Required Capabilities

Different endpoints require different WordPress capabilities:

  • Public endpoints: No authentication required
  • manage_hotelier: Required for reservations and hotel info endpoints (Administrator role)
  • edit_rooms: Required for updating room disabled dates

Pagination

List endpoints support pagination via query parameters and return pagination information in response headers:

  • page - Page number (default: 1)
  • per_page - Items per page (default: 10, max: 100)

Response Headers:

  • X-WP-Total - Total number of items
  • X-WP-TotalPages - Total number of pages

Response Format

All responses include HATEOAS-style _links for navigation:

{
    "id": 123,
    "name": "Deluxe Room",
    "_links": {
        "self": [{ "href": "https://yoursite.com/wp-json/hotelier/v1/rooms/123" }],
        "collection": [{ "href": "https://yoursite.com/wp-json/hotelier/v1/rooms" }]
    }
}

Error Responses

Errors are returned with appropriate HTTP status codes and a JSON body:

{
    "code": "hotelier_rest_invalid_dates",
    "message": "Check-out date must be after check-in date.",
    "data": { "status": 400 }
}

Public Endpoints

These endpoints are accessible without authentication.

Rooms

List Rooms

GET /rooms

Returns a paginated list of all published rooms.

Query Parameters:

Parameter Type Default Description
page integer 1 Page number
per_page integer 10 Items per page (max 100)
room_type integer - Filter by room category term ID
orderby string menu_order Sort by: date, title, menu_order, id
order string asc Sort order: asc, desc
checkin string - Check-in date (YYYY-MM-DD) for price calculation
checkout string - Check-out date (YYYY-MM-DD) for price calculation

Example Request:

curl https://yoursite.com/wp-json/hotelier/v1/rooms?per_page=5&orderby=title

Example Response:

[
    {
        "id": 123,
        "name": "Deluxe Room",
        "slug": "deluxe-room",
        "permalink": "https://yoursite.com/room/deluxe-room/",
        "is_variable": false,
        "max_guests": 2,
        "max_children": 1,
        "stock_rooms": 5,
        "bed_size": "King",
        "bathrooms": "1",
        "room_size": "35 sqm",
        "min_price": 15000,
        "requires_deposit": true,
        "deposit_percentage": 30,
        "is_cancellable": true,
        "categories": [{ "id": 5, "name": "Luxury", "slug": "luxury" }],
        "featured_image": {
            "id": 456,
            "url": "https://yoursite.com/wp-content/uploads/room.jpg",
            "thumbnail": "https://yoursite.com/wp-content/uploads/room-150x150.jpg"
        },
        "extras": [],
        "_links": {...}
    }
]

Get Single Room

GET /rooms/{id}

Returns details for a single room.

Query Parameters:

Parameter Type Description
checkin string Check-in date (YYYY-MM-DD) for price calculation
checkout string Check-out date (YYYY-MM-DD) for price calculation

Example Request:

curl https://yoursite.com/wp-json/hotelier/v1/rooms/123

Room Types

List Room Types

GET /room-types

Returns all room categories.

Query Parameters:

Parameter Type Default Description
hide_empty boolean false Hide categories with no rooms
orderby string name Sort by: id, name, slug, count, term_group
order string asc Sort order: asc, desc
parent integer - Filter by parent term ID

Example Request:

curl https://yoursite.com/wp-json/hotelier/v1/room-types?hide_empty=true

Example Response:

[
    {
        "id": 5,
        "name": "Luxury",
        "slug": "luxury",
        "description": "Our finest rooms",
        "count": 3,
        "parent": 0,
        "_links": {...}
    }
]

Get Single Room Type

GET /room-types/{id}

Returns details for a single room type.

Example Request:

curl https://yoursite.com/wp-json/hotelier/v1/room-types/5

Availability

Check Availability

GET /availability

Check room availability and calculate prices for a specific date range. This is the primary endpoint for building booking interfaces.

Query Parameters:

Parameter Type Required Description
checkin string Yes Check-in date (YYYY-MM-DD)
checkout string Yes Check-out date (YYYY-MM-DD)
room_id integer No Check availability for a specific room only
adults integer No Number of adults (defaults to room max_guests)
children integer No Number of children (defaults to room max_children)

Example Request (All Rooms):

curl "https://yoursite.com/wp-json/hotelier/v1/availability?checkin=2025-06-01&checkout=2025-06-05"

Example Response (All Rooms):

{
    "checkin": "2025-06-01",
    "checkout": "2025-06-05",
    "nights": 4,
    "available_count": 2,
    "rooms": [
        {
            "id": 123,
            "name": "Standard Room",
            "is_variable": false,
            "max_guests": 2,
            "max_children": 1,
            "available_rooms": 3,
            "is_available": true,
            "room": {
                "price_excl_tax": 40000,
                "tax": 4000,
                "price_incl_tax": 44000
            },
            "required_extras": [],
            "optional_extras": [
                {
                    "id": 789,
                    "name": "Breakfast",
                    "pricing": {
                        "type": "per_person",
                        "amount": 1500,
                        "per_night": true
                    }
                }
            ],
            "totals": {
                "price_excl_tax": 40000,
                "tax": 4000,
                "price_incl_tax": 44000
            }
        }
    ]
}

Example Request (Single Room):

curl "https://yoursite.com/wp-json/hotelier/v1/availability?checkin=2025-06-01&checkout=2025-06-05&room_id=123&adults=2&children=1"

Example Response (Single Room):

{
    "checkin": "2025-06-01",
    "checkout": "2025-06-05",
    "nights": 4,
    "room": {
        "id": 123,
        "name": "Standard Room",
        "is_available": true,
        "available_rooms": 3,
        "room": {
            "price_excl_tax": 40000,
            "tax": 4000,
            "price_incl_tax": 44000
        },
        "totals": {...}
    }
}

Variable Rooms: For rooms with rate variations, the response includes a variations array instead of a single room price:

{
    "variations": [
        {
            "index": 1,
            "rate_name": "Standard Rate",
            "room": {
                "price_excl_tax": 40000,
                "tax": 4000,
                "price_incl_tax": 44000
            },
            "totals": {...}
        },
        {
            "index": 2,
            "rate_name": "Non-Refundable Rate",
            "room": {
                "price_excl_tax": 35000,
                "tax": 3500,
                "price_incl_tax": 38500
            },
            "totals": {...}
        }
    ]
}

Authenticated Endpoints

These endpoints require authentication with appropriate capabilities.

Reservations

Requires manage_hotelier capability

List Reservations

GET /reservations

Returns a paginated list of reservations.

Query Parameters:

Parameter Type Default Description
page integer 1 Page number
per_page integer 10 Items per page (max 100)
status string - Filter by status: pending, on-hold, confirmed, completed, cancelled, refunded, failed
checkin_after string - Filter by check-in date on or after (YYYY-MM-DD)
checkin_before string - Filter by check-in date on or before (YYYY-MM-DD)

Example Request:

curl https://yoursite.com/wp-json/hotelier/v1/reservations?status=confirmed \
    -u your_username:xxxx xxxx xxxx xxxx xxxx xxxx

Example Response:

[
    {
        "id": 456,
        "reservation_number": "456",
        "status": "confirmed",
        "date_created": "2025-05-15 10:30:00",
        "checkin": "2025-06-01",
        "checkout": "2025-06-05",
        "nights": 4,
        "guest": {
            "first_name": "John",
            "last_name": "Doe",
            "email": "[email protected]",
            "telephone": "+1234567890",
            "address": {
                "address_1": "123 Main St",
                "city": "New York",
                "country": "US"
            }
        },
        "payment_method": "stripe",
        "payment_method_title": "Credit Card (Stripe)",
        "currency": "USD",
        "subtotal": 40000,
        "tax_total": 4000,
        "discount_total": 0,
        "total": 44000,
        "deposit": 13200,
        "paid_deposit": 13200,
        "balance_due": 30800,
        "special_requests": "Late check-in requested",
        "items": [
            {
                "id": 1,
                "name": "Deluxe Room",
                "room_id": 123,
                "quantity": 1,
                "rate_name": "Standard Rate",
                "rate_id": 1,
                "max_guests": 2,
                "price": 40000,
                "total": 40000,
                "deposit": 12000,
                "percent_deposit": 30,
                "cancellable": true,
                "adults": [2],
                "children": [0]
            }
        ],
        "can_be_cancelled": true,
        "_links": {...}
    }
]

Get Single Reservation

GET /reservations/{id}

Returns details for a single reservation.

Example Request:

curl https://yoursite.com/wp-json/hotelier/v1/reservations/456 \
    -u your_username:xxxx xxxx xxxx xxxx xxxx xxxx

Update Reservation Status

PUT /reservations/{id}

Update a reservation's status.

Request Body:

Parameter Type Description
status string New status: pending, on-hold, confirmed, completed, cancelled, refunded, failed

Example Request:

curl -X PUT https://yoursite.com/wp-json/hotelier/v1/reservations/456 \
    -u your_username:xxxx xxxx xxxx xxxx xxxx xxxx \
    -H "Content-Type: application/json" \
    -d '{"status": "confirmed"}'

Note: Refunded reservations cannot be modified. If a room is no longer available when restoring a cancelled reservation, the API will return a 409 Conflict error.

Hotel Info

Requires manage_hotelier capability

Get Hotel Settings

GET /info

Returns hotel settings and configuration.

Example Request:

curl https://yoursite.com/wp-json/hotelier/v1/info \
    -u your_username:xxxx xxxx xxxx xxxx xxxx xxxx

Example Response:

{
    "hotel": {
        "name": "Grand Hotel",
        "address": "123 Hotel Street",
        "postcode": "10001",
        "locality": "New York",
        "telephone": "+1-555-123-4567",
        "email": "[email protected]",
        "checkin_time": "15:00",
        "checkout_time": "11:00"
    },
    "currency": {
        "code": "USD",
        "symbol": "$",
        "position": "before",
        "thousand_separator": ",",
        "decimal_separator": ".",
        "num_decimals": 2
    },
    "booking": {
        "mode": "instant-booking",
        "minimum_nights": 1,
        "maximum_nights": 30,
        "hold_minutes": 60
    },
    "tax": {
        "enabled": true,
        "rate": 10
    },
    "seasonal_prices": [
        {
            "index": 0,
            "from": "2025-06-01",
            "to": "2025-08-31",
            "every_year": true,
            "description": "Summer Season"
        }
    ],
    "extensions": ["disable-dates", "stripe"]
}

Disabled Dates (Requires Disable Dates Extension)

These endpoints require the Disable Dates extension to be installed and activated.

Update Global Disabled Dates

PUT /info/disabled-dates

Requires manage_hotelier capability

Update the global disabled dates schema.

Request Body:

Parameter Type Description
schema array Array of disabled date rules

Rule Object Properties:

Property Type Required Description
from string Yes Start date (YYYY-MM-DD)
to string No End date (YYYY-MM-DD) - required if single_day is false
single_day boolean No If true, only the "from" date is disabled
every_year boolean No If true, the rule repeats every year

Example Request:

curl -X PUT https://yoursite.com/wp-json/hotelier/v1/info/disabled-dates \
    -u your_username:xxxx xxxx xxxx xxxx xxxx xxxx \
    -H "Content-Type: application/json" \
    -d '{
        "schema": [
            {
                "from": "2025-12-24",
                "to": "2025-12-26",
                "every_year": true
            },
            {
                "from": "2025-07-04",
                "single_day": true,
                "every_year": true
            }
        ]
    }'

Update Room Disabled Dates

PUT /rooms/{id}

Requires edit_rooms capability

Update disabled dates for a specific room.

Request Body:

Parameter Type Description
disabled_dates_type string "global" (use global settings) or "custom" (use custom dates)
disabled_dates_schema array Array of disabled date rules (required when type is "custom")

Example Request (Set to Global):

curl -X PUT https://yoursite.com/wp-json/hotelier/v1/rooms/123 \
    -u your_username:xxxx xxxx xxxx xxxx xxxx xxxx \
    -H "Content-Type: application/json" \
    -d '{"disabled_dates_type": "global"}'

Example Request (Set Custom Dates):

curl -X PUT https://yoursite.com/wp-json/hotelier/v1/rooms/123 \
    -u your_username:xxxx xxxx xxxx xxxx xxxx xxxx \
    -H "Content-Type: application/json" \
    -d '{
        "disabled_dates_type": "custom",
        "disabled_dates_schema": [
            {
                "from": "2025-09-01",
                "to": "2025-09-15"
            }
        ]
    }'

Extension Fields

When certain WP Hotelier extensions are active, additional fields are included in API responses:

Disable Dates Extension

Rooms include:

  • disabled_dates_type - "global" or "custom"
  • disabled_dates - Array of disabled date strings (YYYY-MM-DD)

Flat Deposit Extension

Rooms/variations include:

  • flat_deposit_amount - Fixed deposit amount (integer)

Min/Max Nights Extension

Variations include per-variation overrides:

  • min_nights - Minimum nights for this variation
  • max_nights - Maximum nights for this variation

Advanced Pricing System Extension

Rooms include:

  • advanced_pricing_enabled - true if APS is active

Availability responses may include:

  • extra_guest_fees - Additional fees for extra adults/children