# WP BnB Management
A comprehensive Bed & Breakfast management system for WordPress. Manage buildings, rooms, bookings, and guests all within your WordPress admin.
## Description
WP BnB Management enables WordPress to act as a full management system for B&B hosts. It handles multiple buildings with multiple rooms each, bookings, and guest data required for room rentals.
### Key Features
- **Multi-Property Support**: Manage multiple buildings, each with multiple rooms
- **Flexible Pricing**: Configure short-term (nights), mid-term (weeks), and long-term (months) pricing
- **Seasonal Pricing**: Set price modifiers for high/low seasons
- **Booking Management**: Track reservations from inquiry to checkout
- **Guest Management**: Store guest information securely with GDPR compliance
- **Data Encryption**: Sensitive guest data (ID/passport) encrypted at rest
- **Additional Services**: Offer extras like breakfast, parking, or tours
- **Frontend Integration**: Gutenberg blocks, widgets, and shortcodes
- **Auto-Updates**: Automatic update checks and installation from license server
- **Development Mode**: License bypass for local development environments
- **Contact Form 7 Integration**: Accept booking requests and inquiries through CF7 forms
- **WooCommerce Integration**: Accept payments, auto-sync rooms as products, generate invoices
- **Dashboard**: Comprehensive admin dashboard with statistics and charts
- **Reports**: Detailed reports with CSV and PDF export
- **Prometheus Metrics**: Expose operational metrics for monitoring with Grafana
- **REST API**: Comprehensive API for external integrations
### Requirements
- WordPress 6.0 or higher
- PHP 8.3 or higher
- Valid license key
- Contact Form 7 (optional, for booking forms)
- WooCommerce 8.0+ (optional, for payments and invoicing)
## Installation
1. Download the latest release from the [releases page](https://src.bundespruefstelle.ch/magdev/wp-bnb/releases)
2. Upload the plugin to your `/wp-content/plugins/` directory
3. Activate the plugin through the 'Plugins' menu in WordPress
4. Go to **WP BnB → Settings → License** to enter your license key
5. Configure your business settings under **WP BnB → Settings**
## Configuration
### License Activation
1. Navigate to **WP BnB → Settings → License**
2. Enter your License Server URL
3. Enter your License Key (from purchase confirmation)
4. Enter the Server Secret (from purchase confirmation)
5. Click **Activate License**
### General Settings
- **Business Name**: Your B&B business name
- **Currency**: Select your preferred currency (CHF, EUR, USD, GBP)
- **Business Address**: Street, city, postal code, country
- **Contact Information**: Email, phone, website
- **Social Media**: Facebook, Instagram, X (Twitter), LinkedIn, TripAdvisor
### Update Settings
- **Update Notifications**: Enable/disable update notifications in WordPress
- **Automatic Updates**: Enable/disable automatic plugin updates
- **Check Frequency**: How often to check for updates (1-168 hours)
### Development Mode
The plugin automatically detects local development environments and bypasses license validation. Supported environments:
- localhost, 127.0.0.1, ::1
- Domains ending in .local, .test, .localhost, .dev, .ddev.site
- Private IP ranges (10.x.x.x, 172.16-31.x.x, 192.168.x.x)
## Usage
### Managing Buildings
1. Go to **WP BnB → Buildings**
2. Click **Add New**
3. Enter building details (name, address, description)
4. Add featured image
5. Publish
### Managing Rooms
1. Go to **WP BnB → Rooms**
2. Click **Add New**
3. Select the parent building
4. Configure room details and pricing
5. Add amenities and room type
6. Publish
### Managing Bookings
1. Go to **WP BnB → Bookings**
2. View and manage all reservations
3. Update booking status as guests progress
### Managing Guests
1. Go to **WP BnB → Guests**
2. View guest records and booking history
3. Manage guest information
### Dashboard
The dashboard (**WP BnB → Dashboard**) provides an at-a-glance overview of your B&B operations:
**Statistics Cards:**
- **Occupancy Rate** - Current percentage of rooms occupied with trend indicator
- **Monthly Revenue** - This month's revenue with comparison to previous month
- **Total Bookings** - Active bookings count with status breakdown
- **Total Guests** - Guest count with new guests this month
**Today's Activity:**
- Check-ins scheduled for today with guest names and room assignments
- Check-outs scheduled for today
- Quick links to manage each booking
**Upcoming Bookings:**
- Next 7 days of arrivals
- Guest name, room, dates, and booking status
- Direct links to booking details
**Quick Actions:**
- New Booking - Create a booking directly
- New Guest - Add a guest record
- View Calendar - Open the availability calendar
- View Reports - Access detailed reports
**Trend Charts:**
- 30-day occupancy trend line chart
- 6-month revenue bar chart
### Reports
Access detailed reports at **WP BnB → Reports**. All reports support date range filtering and export.
**Occupancy Report:**
- Overall occupancy percentage for the selected period
- Breakdown by room showing nights booked, available, and occupancy rate
- Visual progress bars for easy comparison
- Total nights booked vs. available across all rooms
**Revenue Report:**
- Total revenue for the selected period
- Revenue breakdown by room
- Revenue breakdown by pricing tier (short-term, mid-term, long-term)
- Revenue from additional services
- Average booking value
**Guest Statistics:**
- Total guests and new guests in period
- Repeat guest rate (guests with 2+ bookings)
- Top guests by total spending
- Guest nationality distribution
- Average spending per guest
**Export Options:**
- **CSV Export** - Download report data as spreadsheet-compatible CSV
- **PDF Export** - Generate formatted PDF reports for printing or archiving
**Date Filters:**
- This Month (default)
- Last Month
- This Year
- Custom date range
## Shortcodes
Display buildings and rooms on your site using shortcodes:
```txt
[bnb_buildings] - List all buildings (grid/list layout)
[bnb_rooms building="123"] - List rooms, optionally filtered by building
[bnb_room_search] - Interactive room search form
[bnb_building id="123"] - Display a single building
[bnb_room id="456"] - Display a single room with availability
```
### Shortcode Attributes
**`[bnb_buildings]`** and **`[bnb_rooms]`**:
- `layout` - "grid" or "list" (default: grid)
- `columns` - 1-4 columns (default: 3)
- `limit` - Number of items (default: 12)
- `orderby` - title, date, price, capacity (default: title)
- `order` - ASC or DESC (default: ASC)
**`[bnb_rooms]`** additional attributes:
- `building` - Building ID to filter by
- `room_type` - Room type slug to filter by
- `amenities` - Comma-separated amenity slugs
## Gutenberg Blocks
The following blocks are available in the block editor:
- **Building** - Display a single building with details
- **Room** - Display a single room with availability form
- **Room Search** - Interactive search form with filters
- **Buildings List** - Display buildings grid/list
- **Rooms List** - Display rooms grid/list with filters
## Widgets
Available sidebar widgets:
- **Similar Rooms** - Show rooms from same building or room type
- **Building Rooms** - List all rooms in a building
- **Availability Calendar** - Mini calendar showing booking status
## Contact Form 7 Integration
The plugin integrates with Contact Form 7 to accept booking requests and inquiries. Custom form tags are provided for room selection, date pickers, and guest counts.
### Custom Form Tags
Use these tags in your CF7 forms:
- `[bnb_building_select name]` - Building dropdown (optional filter for rooms)
- `[bnb_room_select* name]` - Room dropdown with capacity data
- `[bnb_date_checkin* name]` - Check-in date picker
- `[bnb_date_checkout* name]` - Check-out date picker
- `[bnb_guests* name]` - Guest count input
### Tag Options
**`[bnb_building_select]`**:
- `first_as_label:"text"` - Placeholder text (default: "All Locations")
**`[bnb_room_select]`**:
- `building_field:"name"` - Link to building field for filtering
- `first_as_label:"text"` - Placeholder text (default: "Select Room")
**`[bnb_guests]`**:
- `min:N` - Minimum guests (default: 1)
- `max:N` - Maximum guests (default: 10)
- `default:N` - Default value (default: 1)
### Example Booking Form
```txt
```
### Example Inquiry Form
For room-specific inquiries, add the `wp-bnb-inquiry-form` class:
```txt
```
### Form Features
- **Availability Checking**: Real-time AJAX validation shows room availability
- **Price Display**: Estimated total calculated and displayed automatically
- **Room Filtering**: Rooms filter by building selection
- **Date Validation**: Check-out must be after check-in, no past dates
- **Capacity Validation**: Guest count validated against room capacity
- **Automatic Booking**: Booking record created with "pending" status on submission
- **Guest Linking**: Guest records created or linked by email address
### Custom Mail Tags
Use these in your CF7 mail templates:
- `[_bnb_room_name]` - Room title
- `[_bnb_building_name]` - Building name
- `[_bnb_calculated_price]` - Formatted price
- `[_bnb_nights]` - Number of nights
- `[_bnb_booking_reference]` - Booking reference (after creation)
## Hooks and Filters
Developers can customize behavior using these hooks:
```php
// Modify price calculation
add_filter( 'wp_bnb_calculate_price', function( $price, $room_id, $dates ) {
// Custom pricing logic
return $price;
}, 10, 3 );
// Before booking creation
add_action( 'wp_bnb_before_booking_create', function( $booking_data ) {
// Custom validation or logging
} );
```
## Prometheus Metrics
The plugin integrates with [WP Prometheus](https://src.bundespruefstelle.ch/magdev/wp-prometheus) to expose operational metrics for monitoring with Prometheus and Grafana.
### Enabling Metrics
1. Install and activate the WP Prometheus plugin
2. Navigate to **WP BnB → Settings → Metrics**
3. Enable "Expose BnB metrics via Prometheus"
4. Metrics will be available at your site's `/metrics/` endpoint
### Available Metrics
**Inventory Metrics:**
- `wp_bnb_buildings_total` - Total number of buildings
- `wp_bnb_rooms_total{status}` - Rooms by status (available, occupied, maintenance, inactive)
- `wp_bnb_services_total{status}` - Services by status (active, inactive)
- `wp_bnb_total_capacity_beds` - Total bed capacity across all rooms
**Booking Metrics:**
- `wp_bnb_bookings_total{status}` - Bookings by status (pending, confirmed, checked_in, checked_out, cancelled)
- `wp_bnb_checkins_today` - Check-ins scheduled for today
- `wp_bnb_checkouts_today` - Check-outs scheduled for today
- `wp_bnb_bookings_upcoming_7days` - Bookings starting in next 7 days
- `wp_bnb_booking_avg_duration_nights` - Average booking duration
**Occupancy Metrics:**
- `wp_bnb_occupancy_rate_current` - Current room occupancy rate (percentage)
- `wp_bnb_occupancy_rate_this_month` - Monthly occupancy rate (percentage)
- `wp_bnb_rooms_currently_occupied` - Rooms currently occupied
**Revenue Metrics:**
- `wp_bnb_revenue_this_month{currency}` - Revenue for current month
- `wp_bnb_revenue_ytd{currency}` - Revenue year to date
- `wp_bnb_booking_avg_value{currency}` - Average booking value
- `wp_bnb_services_revenue_this_month{currency}` - Services revenue this month
**Guest Metrics:**
- `wp_bnb_guests_total` - Total registered guests
- `wp_bnb_guests_by_status{status}` - Guests by status (active, blocked, vip)
- `wp_bnb_guests_repeat` - Guests with more than one booking
- `wp_bnb_guests_new_this_month` - New guests this month
### Grafana Dashboard
A pre-configured Grafana dashboard is included at `assets/grafana/wp-bnb-dashboard.json`. If WP Prometheus is installed, the dashboard is automatically registered and available for export.
The dashboard includes:
- Occupancy gauges with color-coded thresholds
- Bookings, rooms, and guests pie charts by status
- Revenue and guest statistics panels
- Today's check-ins/check-outs
- Trend indicators
## WooCommerce Integration
The plugin integrates with WooCommerce to enable payment processing, automatic invoicing, and seamless order management.
### Enabling WooCommerce Integration
1. Install and activate WooCommerce 8.0 or higher
2. Navigate to **WP BnB → Settings → WooCommerce**
3. Enable "Enable WooCommerce Integration"
4. Configure product sync and invoice settings
### Features
**Product Synchronization:**
- Rooms are automatically synced as virtual WooCommerce products
- Products use SKU format `bnb-room-{id}` for tracking
- Price, description, and images are kept in sync
- Products created/updated on room save, deleted on room deletion
- Manual "Sync All Rooms" button in settings
**Cart & Checkout:**
- Add room bookings to WooCommerce cart with dates and guest count
- Real-time availability validation prevents double-booking
- Dynamic pricing calculated from room rates and services
- Special checkout fields for arrival time and special requests
- Guest information pre-filled from user profile
**Booking Creation:**
- Bookings automatically created on successful payment
- Guest records created from billing information
- Booking linked to WooCommerce order for reference
- Booking reference displayed on order confirmation
**Order-Booking Synchronization:**
- Order status changes sync to booking status:
- Order completed → Booking confirmed
- Order cancelled → Booking cancelled
- Order refunded → Booking cancelled (full refund)
- Partial refunds recorded without cancellation
- Bidirectional linking between orders and bookings
**PDF Invoices:**
- Automatic PDF invoice generation
- Configurable invoice number prefix (default: `INV-`)
- Sequential invoice numbering with configurable start number
- Auto-attach to WooCommerce order emails
- Secure storage in `wp-content/uploads/wp-bnb-invoices/`
- Manual generation from order admin
### WooCommerce Settings
**General Subtab:**
- Enable/disable WooCommerce integration
- Enable automatic product sync
- Enable auto-attach invoices to emails
**Products Subtab:**
- View sync status and product count
- Manual "Sync All Rooms Now" button
- Product category assignment
**Orders Subtab:**
- Order-booking status mapping
- View linked orders and bookings
**Invoices Subtab:**
- Invoice number prefix
- Starting invoice number
- Company details for invoice header
- PDF styling options
### HPOS Compatibility
The integration is fully compatible with WooCommerce High-Performance Order Storage (HPOS). Order meta is accessed using the modern `$order->get_meta()` and `$order->update_meta_data()` methods.
### Admin Columns
- **Bookings list**: "WC Order" column with link to order
- **WooCommerce Orders list**: "Booking" column with link to booking
## REST API
The plugin provides a comprehensive REST API for integration with external applications, mobile apps, and third-party services.
### Enabling the API
1. Navigate to **WP BnB → Settings → API**
2. In the **General** subtab, enable "Enable REST API"
3. Optionally enable rate limiting for protection against abuse
4. Configure rate limits in the **Rate Limits** subtab
5. View all available endpoints in the **Endpoints** subtab
### Base URL
All API endpoints are prefixed with:
```txt
https://your-site.com/wp-json/wp-bnb/v1/
```
### Authentication
**Public endpoints** (room listings, availability checks) require no authentication.
**Admin endpoints** (booking management, guest data) require authentication via:
- **Cookie + Nonce**: For same-domain JavaScript requests
- **Application Passwords**: For external applications (WordPress 5.6+, recommended)
To create an Application Password:
1. Go to **Users → Profile**
2. Scroll to "Application Passwords"
3. Enter a name and click "Add New Application Password"
4. Use the generated password with HTTP Basic Auth
```bash
curl -u "username:app-password" https://site.com/wp-json/wp-bnb/v1/bookings
```
### Public Endpoints
| Method | Endpoint | Description |
| ------ | -------- | ----------- |
| GET | `/buildings` | List all buildings |
| GET | `/buildings/{id}` | Get building details |
| GET | `/buildings/{id}/rooms` | Get rooms in a building |
| GET | `/rooms` | List/search rooms |
| GET | `/rooms/{id}` | Get room details |
| GET | `/rooms/{id}/availability` | Check room availability |
| GET | `/rooms/{id}/calendar` | Get monthly calendar data |
| POST | `/availability/search` | Search available rooms |
| GET | `/services` | List all services |
| GET | `/services/{id}` | Get service details |
| POST | `/pricing/calculate` | Calculate booking price |
| POST | `/bookings` | Create a new booking (pending status) |
### Admin Endpoints
| Method | Endpoint | Description |
| ------ | -------- | ----------- |
| GET | `/bookings` | List all bookings |
| GET | `/bookings/{id}` | Get booking details |
| PATCH | `/bookings/{id}` | Update a booking |
| DELETE | `/bookings/{id}` | Cancel a booking |
| POST | `/bookings/{id}/confirm` | Confirm a pending booking |
| POST | `/bookings/{id}/check-in` | Check in a guest |
| POST | `/bookings/{id}/check-out` | Check out a guest |
| GET | `/guests` | List all guests |
| GET | `/guests/{id}` | Get guest details |
| GET | `/guests/search` | Search guests |
| GET | `/guests/{id}/bookings` | Get guest's booking history |
### Rate Limiting
When enabled, rate limits are applied per client (by user ID or IP address). Configure limits in **Settings → API → Rate Limits**.
**Default Limits:**
| Type | Default | Applies To |
| ---- | ------- | ---------- |
| Public | 60/min | Room/building listings |
| Availability | 30/min | Availability and calendar endpoints |
| Booking | 10/min | Booking creation |
| Admin | 120/min | All admin endpoints |
**Configuration Options:**
- **Time Window**: 10-300 seconds (default: 60 seconds)
- **Per-endpoint limits**: Customize for each endpoint type
- **Rate limiting toggle**: Enable/disable without losing settings
Rate limit headers are included in responses:
- `X-RateLimit-Limit`: Maximum requests allowed
- `X-RateLimit-Remaining`: Requests remaining in window
- `X-RateLimit-Reset`: Unix timestamp when limit resets
### Example: Check Room Availability
```bash
curl "https://site.com/wp-json/wp-bnb/v1/rooms/42/availability?check_in=2026-03-15&check_out=2026-03-20"
```
Response:
```json
{
"available": true,
"room_id": 42,
"check_in": "2026-03-15",
"check_out": "2026-03-20",
"nights": 5,
"pricing": {
"base_price": 500.00,
"seasonal_modifier": 1.0,
"weekend_surcharge": 40.00,
"total": 540.00,
"currency": "CHF"
}
}
```
### Example: Create a Booking
```bash
curl -X POST https://site.com/wp-json/wp-bnb/v1/bookings \
-H "Content-Type: application/json" \
-d '{
"room_id": 42,
"check_in": "2026-03-15",
"check_out": "2026-03-20",
"guests": 2,
"guest_info": {
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com",
"phone": "+41 79 123 4567"
},
"services": [
{"service_id": 5, "quantity": 1}
],
"notes": "Late arrival expected"
}'
```
Response:
```json
{
"id": 123,
"reference": "BNB-2026-00042",
"status": "pending",
"room": {
"id": 42,
"title": "Deluxe Suite"
},
"check_in": "2026-03-15",
"check_out": "2026-03-20",
"nights": 5,
"guests": 2,
"pricing": {
"room_total": 540.00,
"services_total": 50.00,
"grand_total": 590.00,
"currency": "CHF"
},
"_links": {
"self": [{"href": "https://site.com/wp-json/wp-bnb/v1/bookings/123"}]
}
}
```
### Example: Search Available Rooms
```bash
curl -X POST https://site.com/wp-json/wp-bnb/v1/availability/search \
-H "Content-Type: application/json" \
-d '{
"check_in": "2026-03-15",
"check_out": "2026-03-20",
"guests": 2,
"amenities": ["wifi", "parking"]
}'
```
### Error Responses
Errors follow WordPress REST API conventions:
```json
{
"code": "rest_not_found",
"message": "Room not found.",
"data": {
"status": 404
}
}
```
Common error codes:
- `rest_invalid_param` (400): Invalid request parameters
- `rest_forbidden` (403): Insufficient permissions
- `rest_not_found` (404): Resource not found
- `rest_conflict` (409): Booking conflict
- `rest_rate_limit_exceeded` (429): Rate limit exceeded
## Frequently Asked Questions
### Do I need a license to use this plugin?
Yes, a valid license is required to use the frontend features in production. The admin functionality works without a license for evaluation purposes. Local development environments (localhost, .local, .test, .dev domains) automatically bypass license validation.
### Can I manage multiple properties?
Yes, you can create unlimited buildings and rooms.
### Is the plugin GDPR compliant?
Yes, guest data can be exported and deleted on request, and consent is tracked appropriately.
### Does it integrate with WooCommerce?
Yes! WooCommerce integration is available for payment processing and invoicing. Rooms are synced as virtual products, bookings are created on successful payment, and PDF invoices are auto-generated and attached to order emails. Navigate to **WP BnB → Settings → WooCommerce** to enable and configure the integration.
### How is guest data secured?
Sensitive guest data like passport/ID numbers are encrypted using AES-256-CBC encryption before storage. The encryption key is derived from your WordPress AUTH_KEY, ensuring data is secure at rest.
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for a detailed list of changes.
## Support
For support, please create an issue at:
## Author
**Marco Graetsch**
- Website:
- Email:
## License
GPL-2.0-or-later
This plugin is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or any later version.