Admin Booking Management Guide

Last Updated: 2026-04-07 Version: 1.2

Overview

This guide covers all admin-specific booking management operations including searching, creating, modifying, and managing bookings through the admin interface.

Table of Contents

1. Booking Search & Filtering
2. Creating Admin Bookings
3. Admin Booking Wizard (UI)
4. Viewing Customer Booking History
5. Managing Booking Notes
6. Booking Status Management
7. Editing Customer Information
8. Best Practices

---

Booking Search & Filtering

Overview

The admin booking search provides advanced filtering and search capabilities to quickly locate bookings across your entire tenant database.

API Endpoint

GET /api/v1/admin/bookings

Required Permission

• admin:bookings:read

Search Parameters

Parameter	Type	Description	Example
customerEmail	string	Filter by customer email (partial match)	john@example.com
customerPhone	string	Filter by customer phone number	+1234567890
customerName	string	Filter by customer name (partial match)	John Smith
bookingStatus	string[]	Filter by booking status	['confirmed', 'paid']
siteId	string	Filter by specific site	site_hq
productId	string	Filter by specific product	prod_laser_tag
dateFrom	ISO date	Start of date range	2025-11-01T00:00:00Z
dateTo	ISO date	End of date range	2025-11-30T23:59:59Z
minAmount	number	Minimum booking amount	50.00
maxAmount	number	Maximum booking amount	500.00
page	number	Page number (default: 1)	1
limit	number	Results per page (default: 50, max: 100)	50
sortBy	string	Sort field	startTime
sortOrder	string	Sort order (asc or desc)	desc

Response Structure

{
  "bookings": [
    {
      "bookingId": "booking_123",
      "bookingReference": "REF-2025-001",
      "customer": {
        "name": "John Smith",
        "email": "john@example.com",
        "phone": "+1234567890"
      },
      "slot": {
        "startTime": "2025-11-20T14:00:00Z",
        "endTime": "2025-11-20T15:00:00Z",
        "siteName": "HQ Facility",
        "productName": "Laser Tag"
      },
      "status": "confirmed",
      "grandTotal": 150.0,
      "paidAmount": 150.0,
      "createdAt": "2025-11-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 125,
    "totalPages": 3
  },
  "summary": {
    "totalBookings": 125,
    "totalRevenue": 18750.0,
    "statusBreakdown": {
      "confirmed": 45,
      "paid": 60,
      "completed": 15,
      "cancelled": 5
    }
  }
}

Example Usage

Search by customer email:

curl -H "Authorization: Bearer $TOKEN" \
     -H "x-tenant-id: t_demo" \
     "https://api.example.com/api/v1/admin/bookings?customerEmail=john@example.com"

Search by date range and status:

curl -H "Authorization: Bearer $TOKEN" \
     -H "x-tenant-id: t_demo" \
     "https://api.example.com/api/v1/admin/bookings?dateFrom=2025-11-01T00:00:00Z&dateTo=2025-11-30T23:59:59Z&bookingStatus=confirmed&bookingStatus=paid"

Search with pagination:

curl -H "Authorization: Bearer $TOKEN" \
     -H "x-tenant-id: t_demo" \
     "https://api.example.com/api/v1/admin/bookings?page=2&limit=25"

Best Practices for Search

1. Use Date Ranges: Always specify date ranges to improve query performance
2. Limit Results: Use pagination with reasonable page sizes (25-50 records)
3. Combine Filters: Use multiple filters to narrow results effectively
4. Cache Results: Consider caching frequently accessed searches

---

Creating Admin Bookings

Overview

Admins can create bookings directly without going through the standard customer booking flow. This is useful for phone orders, group bookings, or special arrangements.

API Endpoint

POST /api/v1/admin/bookings

Required Permission

• admin:bookings:create

Request Body

{
  "siteId": "site_hq",
  "productId": "prod_laser_tag",
  "variantId": "var_standard",
  "startTime": "2025-11-25T14:00:00Z",
  "partySize": 8,
  "customerInfo": {
    "name": "John Smith",
    "email": "john@example.com",
    "phone": "+1234567890"
  },
  "addons": [
    {
      "addonId": "addon_pizza",
      "quantity": 2
    }
  ],
  "adminNotes": "VIP customer - special request for birthday party",
  "skipAvailabilityCheck": false,
  "bypassCapacity": false,
  "autoConfirm": true,
  "sendConfirmationEmail": true
}

Field Descriptions

Field	Type	Required	Description
siteId	string	Yes	Site where booking will occur
productId	string	Yes	Product/activity being booked
variantId	string	No	Product variant (if applicable)
startTime	ISO date	Yes	Booking start time
partySize	number	Yes	Number of participants
customerInfo	object	Yes	Customer contact information
addons	array	No	Additional products/services
adminNotes	string	No	Internal notes (not visible to customer)
skipAvailabilityCheck	boolean	No	Bypass availability validation (use cautiously)
bypassCapacity	boolean	No	Override capacity limits (requires special permission)
autoConfirm	boolean	No	Automatically confirm booking (default: false)
sendConfirmationEmail	boolean	No	Send confirmation to customer (default: true)

Response Structure

{
  "bookingId": "booking_admin_123",
  "bookingReference": "REF-2025-045",
  "status": "confirmed",
  "grandTotal": 175.0,
  "breakdown": {
    "basePrice": 120.0,
    "addons": 40.0,
    "tax": 15.0,
    "total": 175.0
  },
  "slot": {
    "startTime": "2025-11-25T14:00:00Z",
    "endTime": "2025-11-25T15:00:00Z"
  },
  "warnings": []
}

Workflow Steps

1. Verify Availability: Check slot availability before creating
2. Collect Customer Info: Gather all required customer details
3. Add Internal Notes: Document special requests or requirements
4. Choose Options: Select appropriate bypass/auto-confirm options
5. Create Booking: Submit the booking request
6. Confirm Creation: Verify booking was created successfully
7. Follow Up: Send confirmation or follow up as needed

Special Admin Flags

skipAvailabilityCheck

• Use Case: Overbooking for groups or special events
• Risk: May create scheduling conflicts
• Recommendation: Only use when intentional overbooking is required

bypassCapacity

• Use Case: VIP bookings or special arrangements
• Risk: May exceed safety or operational limits
• Recommendation: Requires admin:capacity:override permission

autoConfirm

• Use Case: Direct bookings for known customers
• Risk: Skips payment collection
• Recommendation: Use for comp bookings or invoice-based arrangements

Example Usage

Standard admin booking:

curl -X POST \
     -H "Authorization: Bearer $TOKEN" \
     -H "x-tenant-id: t_demo" \
     -H "Content-Type: application/json" \
     -d '{
       "siteId": "site_hq",
       "productId": "prod_laser_tag",
       "startTime": "2025-11-25T14:00:00Z",
       "partySize": 8,
       "customerInfo": {
         "name": "John Smith",
         "email": "john@example.com",
         "phone": "+1234567890"
       },
       "adminNotes": "Birthday party - requested Team Red arena"
     }' \
     "https://api.example.com/api/v1/admin/bookings"

---

Admin Booking Wizard (UI)

Overview

The Admin Booking Wizard provides a comprehensive 10-step interface for creating bookings on behalf of customers. This UI-based approach offers full feature parity with the customer booking flow, including participant details, promotions, waivers, and multiple payment options.

Location: /admin/operations/bookings/new

Wizard Steps

Step	Name	Description
1	Site	Select the location/site for the booking
2	Product	Choose the activity/product
3	Date & Time	Pick an available slot and participant types
4	Variant	Choose product tier/variant
5	Add-ons	Select optional extras
6	Customer	Enter customer contact details
7	Participants	Collect details for each participant
8	Promotions	Apply promotion codes and vouchers
9	Waivers	Handle waiver requirements (if applicable)
10	Review & Pay	Confirm booking and select payment method

Step Details

Step 1-5: Booking Configuration

The first five steps mirror the customer booking flow:

• Site Selection: Choose from all active sites for the tenant
• Product Selection: Browse available products at the selected site
• Date & Time: Calendar view with available slots, supports participant type pricing
• Variant Selection: Choose pricing tier (Standard, Premium, etc.)
• Add-ons Selection: Add optional extras with quantities

Step 6: Customer Information

Collect customer contact details:

• Name (required)
• Email (required)
• Phone (optional)
• Special Requests (optional notes from customer)

Step 7: Participant Details

Collect information for each person in the party:

• First Name / Last Name (required)
• Email (optional)
• Phone (optional)
• Date of Birth (optional, for age-restricted activities)
• Dietary Restrictions (optional)
• Medical Conditions (optional)
• Emergency Contact (optional)
• Special Requests (optional)

The first participant is auto-populated from customer information. This step can be skipped if participant details are not required.

Step 8: Promotions & Vouchers

Apply discount codes to the booking:

• Promotion Codes: Enter and apply promotion codes
• Voucher Codes: Redeem prepaid vouchers
• Discount Preview: See applied discounts and updated totals
• Remove Codes: Remove previously applied codes

A booking hold is created at this step to enable code validation.

Step 9: Waivers (Conditional)

This step appears only if the product requires waivers:

• View Requirements: See required waivers for the product
• Offline Collection: Mark waivers as "collected offline" (paper forms)
• Skip with Reason: Skip waiver requirement with documented reason
• Send Email: Send waiver signing links to participants

Step 10: Review & Payment

Final review and payment selection:

Booking Summary:

• All selected options
• Participant list
• Add-ons and quantities
• Applied discounts

Pricing Breakdown:

• Subtotal
• Discounts (promotions, vouchers)
• Tax
• Final total

Payment Methods:

Method	Description	Use Case
poa	Pay on Arrival	Customer pays at check-in
stripe	Card Payment (Stripe)	Process card payment now
paytrail	Bank Payment (Paytrail)	Finnish bank payment redirect
comp	Complimentary	Free booking (no payment)
invoice	Invoice	Send invoice for later payment

Admin Options:

• Created Reason: Why booking was created (phone_booking, walk_in, comp, correction, other)
• Internal Notes: Staff-only notes about the booking
• Terms Acceptance: Acknowledge terms on customer's behalf

Required Permissions

• admin:bookings:create - Required for all admin booking creation
• admin:bookings:create:custom_pricing - Required for custom pricing
• admin:bookings:create:override_capacity - Required to bypass capacity limits
• admin:bookings:create:comp - Required for complimentary bookings

Workflow Example: Phone Booking

1. Customer calls to make a booking
2. Navigate to Operations → Bookings → New Booking
3. Select site and product
4. Choose date/time and participant types
5. Select variant and any add-ons
6. Enter customer contact information
7. Collect participant details (names, dietary needs)
8. Apply any promo codes customer mentions
9. Skip waivers (can be signed on arrival)
10. Select "Pay on Arrival" and complete booking

Workflow Example: Walk-in Booking

1. Customer arrives without reservation
2. Navigate to Operations → Bookings → New Booking
3. Complete steps 1-6 quickly
4. Skip participant details step
5. Skip promotions step
6. Skip waivers (sign in person)
7. Select appropriate payment method
8. Set "Created Reason" to walk_in
9. Complete booking

Workflow Example: Complimentary Booking

1. Navigate to Operations → Bookings → New Booking
2. Complete steps 1-7 as normal
3. Skip promotions (comp doesn't need discounts)
4. Handle waivers if required
5. Select "Complimentary" payment method
6. Set "Created Reason" to comp
7. Add internal note explaining comp reason
8. Complete booking

---

Viewing Customer Booking History

Overview

View complete booking history for a specific customer, useful for customer service and relationship management.

API Endpoint

GET /api/v1/admin/customers/:identifier/bookings

Required Permission

• admin:customers:read

Path Parameters

• :identifier - Can be customer email, phone number, or customer ID

Query Parameters

Parameter	Type	Description
includeCompleted	boolean	Include completed bookings (default: true)
includeCancelled	boolean	Include cancelled bookings (default: false)
limit	number	Maximum results (default: 50)

Response Structure

{
  "customer": {
    "identifier": "john@example.com",
    "name": "John Smith",
    "totalBookings": 12,
    "lifetimeValue": 1850.0,
    "firstBookingDate": "2024-06-15T10:00:00Z",
    "lastBookingDate": "2025-11-10T15:30:00Z"
  },
  "bookings": [
    {
      "bookingId": "booking_123",
      "bookingReference": "REF-2025-045",
      "status": "completed",
      "startTime": "2025-11-10T15:30:00Z",
      "product": "Laser Tag",
      "site": "HQ Facility",
      "partySize": 6,
      "total": 120.0,
      "notes": []
    }
  ],
  "statistics": {
    "completedBookings": 10,
    "cancelledBookings": 1,
    "noShows": 1,
    "averagePartySize": 6.5,
    "averageBookingValue": 154.17,
    "favoriteProduct": "Laser Tag",
    "favoriteSite": "HQ Facility"
  }
}

Use Cases

1. Customer Service: Quick access to customer's booking history
2. Loyalty Programs: Identify high-value customers
3. Issue Resolution: Review past bookings when handling complaints
4. Marketing: Understand customer preferences and patterns

---

Managing Booking Notes

Overview

Internal notes system for tracking communications, special requests, and important booking details.

API Endpoints

Add Note:

POST /api/v1/admin/bookings/:bookingId/notes

Get Notes:

GET /api/v1/admin/bookings/:bookingId/notes

Update Note:

PATCH /api/v1/admin/bookings/:bookingId/notes/:noteId

Delete Note:

DELETE /api/v1/admin/bookings/:bookingId/notes/:noteId

Required Permission

• admin:bookings:write (for add/update/delete)
• admin:bookings:read (for viewing)

Adding a Note

Request:

{
  "content": "Customer requested Team Red arena if available",
  "category": "special_request",
  "priority": "normal",
  "isInternal": true
}

Response:

{
  "noteId": "note_123",
  "bookingId": "booking_456",
  "content": "Customer requested Team Red arena if available",
  "category": "special_request",
  "priority": "normal",
  "isInternal": true,
  "createdBy": "admin_user_1",
  "createdByName": "Sarah Johnson",
  "createdAt": "2025-11-18T10:30:00Z"
}

Note Categories

Category	Purpose	Example
general	General information	"Customer is a regular"
special_request	Customer requests	"Requested birthday cake setup"
issue	Problems or complaints	"Customer reported late arrival"
follow_up	Action items	"Call customer to confirm dietary needs"
resolution	Issue resolutions	"Provided 10% discount for inconvenience"

Note Priority Levels

• low - Informational only
• normal - Standard notes
• high - Important information requiring attention
• urgent - Immediate action required

Best Practices

1. Be Specific: Include relevant details and context
2. Use Categories: Properly categorize for easy filtering
3. Set Priority: Mark urgent items appropriately
4. Follow Up: Close the loop on action items
5. Keep Professional: Notes may be reviewed by other staff

---

Booking Status Management

Overview

Admin users can transition bookings through various status states. There are 10 statuses in total.

Status Descriptions

Status	Value	Description	Admin Actions
Hold	hold	Temporary reservation awaiting confirmation (15-min TTL default)	Confirm, cancel, or let expire
Tentative	tentative	Payment-on-Arrival (PoA) booking — customer will pay at the venue	Mark paid, cancel, mark no-show
Confirmed	confirmed	Booking confirmed after online payment is initiated	Record payment, mark arrived, cancel
Part Paid	part_paid	Partial payment received (e.g., voucher applied, balance pending)	Record remaining payment, cancel
Paid	paid	Fully paid	Mark arrived, cancel, mark no-show
Arrived	arrived	Customer has checked in at the venue	Mark completed, mark no-show
Completed	completed	Activity has finished successfully	No further transitions (terminal)
Cancelled	canceled	Booking was cancelled by customer, admin, or system	No further transitions (terminal)
No Show	no_show	Customer did not arrive for their booking	Re-mark as arrived (admin correction)
Expired	expired	Hold expired before confirmation (capacity auto-released)	Re-hold or cancel

Valid Status Transitions

Main flow:      hold → confirmed → paid → arrived → completed
PoA flow:       hold → tentative → paid → arrived → completed
Partial pay:    confirmed → part_paid → paid → arrived → completed

Cancellation:   hold/tentative/confirmed/part_paid/paid → canceled
No-show:        tentative/confirmed/part_paid/paid → no_show
                arrived → no_show (late correction)
Expiration:     hold → expired
Recovery:       no_show → arrived (admin correction)
                expired → hold (manual re-hold) or canceled

Note: completed and canceled are terminal states — no further transitions are possible.

Manual Status Updates

Endpoint:

PATCH /api/v1/admin/bookings/:bookingId/status

Request:

{
  "status": "confirmed",
  "reason": "Phone payment received",
  "adminNotes": "Customer paid via phone using card ending in 1234"
}

Required Permission:

• admin:bookings:write

No-Show Management

When marking a booking as no-show:

1. Verify Non-Arrival: Confirm customer did not arrive
2. Check Policy: Review your no-show policy
3. Update Status: Mark as no-show in system
4. Apply Penalties: Apply any no-show fees or restrictions
5. Document: Add note explaining circumstances
6. Follow Up: Contact customer if appropriate

Endpoint:

POST /api/v1/admin/bookings/:bookingId/no-show

---

Editing Customer Information

Overview

Admins can update customer contact details on existing bookings directly from the booking detail page. This is useful when a customer provides corrected information, changes their email address, or when fixing data entry errors from phone bookings.

API Endpoint

PATCH /api/v1/admin/bookings/:bookingId/customer

Required Permission

• admin:bookings:write

Editable Fields

Field	Type	Description	Example
customerName	string	Full name of the booking customer	"Jane Doe"
customerEmail	string	Customer email address	"jane@example.com"
customerPhone	string	Customer phone number	"+358401234567"

All fields are optional in the request body. Only the fields included in the request will be updated; omitted fields remain unchanged.

Request Body

{
  "customerName": "Jane Doe",
  "customerEmail": "jane.doe@example.com",
  "customerPhone": "+358401234567"
}

Response Structure

{
  "bookingId": "booking_123",
  "customer": {
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "phone": "+358401234567"
  },
  "updatedAt": "2026-04-07T12:00:00Z",
  "updatedBy": "admin_user_1"
}

Audit Trail

All changes to customer information are tracked in the audit log. Each update records:

• Who made the change (admin user ID and name)
• When the change was made (timestamp)
• What changed (previous and new values for each modified field)

Audit entries can be viewed from the booking detail page under the "Activity" or "Audit Log" tab.

Admin UI

Customer information can be edited from the booking detail page in the admin interface:

1. Navigate to Operations --> Bookings and locate the booking
2. Open the booking detail page
3. Click the Edit button in the Customer Information section
4. Update the desired fields
5. Click Save to apply changes

Example Usage

Update customer email and phone:

curl -X PATCH \
     -H "Authorization: Bearer $TOKEN" \
     -H "x-tenant-id: t_demo" \
     -H "Content-Type: application/json" \
     -d '{
       "customerEmail": "jane.doe@example.com",
       "customerPhone": "+358401234567"
     }' \
     "https://api.example.com/api/v1/admin/bookings/booking_123/customer"

Update customer name only:

curl -X PATCH \
     -H "Authorization: Bearer $TOKEN" \
     -H "x-tenant-id: t_demo" \
     -H "Content-Type: application/json" \
     -d '{
       "customerName": "Jane Doe"
     }' \
     "https://api.example.com/api/v1/admin/bookings/booking_123/customer"

---

Best Practices

Search Efficiency

1. Use Indexes: Search fields are indexed - use them for fast queries
2. Limit Scope: Narrow date ranges improve performance
3. Pagination: Don't request all results at once
4. Cache Common: Cache frequently accessed search results

Booking Creation

1. Verify First: Always check availability before creating
2. Complete Info: Collect all customer information upfront
3. Document Special Requests: Use admin notes for special requirements
4. Confirm Contact: Verify customer contact information
5. Send Confirmation: Always send confirmation unless explicitly requested not to

Customer History

1. Regular Review: Review history for returning customers
2. Note Patterns: Document preferences and patterns
3. Proactive Service: Use history to anticipate needs
4. Resolve Issues: Address recurring problems

Note Management

1. Timely Updates: Add notes immediately while details are fresh
2. Clear Communication: Write notes others can understand
3. Complete Follow-up: Mark follow-up items as resolved
4. Privacy: Keep internal notes truly internal

Status Management

1. Follow Workflow: Respect status transition rules
2. Document Changes: Always add notes when changing status
3. Communicate: Inform customers of status changes
4. Audit Trail: Maintain complete status change history

---

Common Workflows

Workflow 1: Phone Booking

1. Customer calls to make a booking
2. Search for customer by phone/email to check history
3. Check availability for requested date/time
4. Create admin booking with customer info
5. Add note documenting special requests
6. Choose payment method (pay now, invoice, etc.)
7. Send confirmation email
8. Add follow-up note if needed

Workflow 2: Handling Customer Issues

1. Search for booking by customer email or reference
2. Review booking details and history
3. Check customer's previous bookings for context
4. Add note documenting the issue
5. Take corrective action (refund, reschedule, etc.)
6. Update booking status if needed
7. Add resolution note
8. Follow up with customer

Workflow 3: VIP Booking

1. Search for customer to check VIP status/history
2. Check availability for preferred date/time
3. Create admin booking with bypass flags if needed
4. Add addons and special services
5. Add priority note about VIP status
6. Auto-confirm if payment arranged separately
7. Send personalized confirmation
8. Schedule follow-up check

---

Troubleshooting

Search Returns No Results

Check:

• Date range is not too narrow
• Filters are not too restrictive
• Customer information is spelled correctly
• Tenant context is correct

Cannot Create Booking

Common Causes:

• Slot not available (check availability first)
• Capacity exceeded (use bypass if authorized)
• Invalid customer information
• Missing required fields

Notes Not Showing

Check:

• Proper permissions (admin:bookings:read)
• Note visibility settings (internal vs customer-facing)
• Tenant context is correct

Status Transition Failed

Common Causes:

• Invalid status transition (see allowed transitions)
• Booking in incompatible state
• Missing payment for paid status
• Insufficient permissions

---

API Reference Summary

Endpoint	Method	Purpose	Permission
/api/v1/admin/bookings	GET	Search bookings	admin:bookings:read
/api/v1/admin/bookings	POST	Create booking	admin:bookings:create
/api/v1/admin/bookings/:id	GET	Get booking details	admin:bookings:read
/api/v1/admin/bookings/:id/notes	GET	Get notes	admin:bookings:read
/api/v1/admin/bookings/:id/notes	POST	Add note	admin:bookings:write
/api/v1/admin/bookings/:id/status	PATCH	Update status	admin:bookings:write
/api/v1/admin/bookings/:id/customer	PATCH	Edit customer info	admin:bookings:write
/api/v1/admin/customers/:id/bookings	GET	Customer history	admin:customers:read

---

Related Documentation

• Payment on Arrival Guide - Full PoA workflow for arrival confirmation, on-site payment, and no-show handling
• Customer Service Procedures
• Financial Operations
• API Reference
• Admin Operations Guide