Aries PMS Help Center

Welcome. This page is a practical, task‑oriented guide to running your hotel on Aries PMS. It maps directly to this application’s modules and screens: Reservations, Guests, Rooms, Housekeeping, Billing, Reports, Admin, Front Desk operations, Key Cards, and Messaging.

Tip: You must be assigned to a hotel to access most features. If you see limited data, ask an admin to assign a hotel to your user.

Getting Started

  1. Register an account from the top navigation or have an admin create one.
  2. Login with your email and password. Optionally use “Remember me” to extend the cookie session.
  3. Ask an admin to assign your user to a hotel. Without a hotel, lists and reports will be empty.

Technical: Authentication uses signed JWT stored in an httpOnly cookie named access_token.

  • Open Admin → Hotel Settings and enter property details (name, address, category).
  • Define Room Categories and create Rooms with numbers and capacities.
  • Optionally configure RMS integration later for combined reporting.

  • Dashboard: operational overview and quick links.
  • Reservations: search, create, edit, and perform check‑in/out.
  • Guests: create and maintain guest profiles and IDs.
  • Rooms: inventory and status; see availability and assign rooms.
  • Housekeeping: track cleaning status and assignments.
  • Billing: folios, charges, payments, and invoice printing.
  • Reports: Occupancy, Revenue, Forecast, Meal Plans (+ CSV export).
  • Admin: hotel configuration and user context.

Reservations

  1. Go to Reservations → New (URL: /reservations/new).
  2. Select hotel and room category; set check‑in/check‑out dates and occupants.
  3. Pick an available room (optional at creation; can assign later).
  4. Select an existing guest or create a new one.
  5. Save the reservation; a confirmation code will be generated.

Back‑end: pms_reservations.py creates records; room availability computed via pms_rooms.search_rooms_with_availability.

  • Assign Room: choose an available room in the reservation details.
  • Check‑In: uses pms_front_desk.check_in_guest; creates room assignment and sets status.
  • Check‑Out: uses pms_front_desk.check_out_guest; finalizes stay and frees the room.

Due check‑outs and currently checked‑in guests are available via pms_front_desk helpers and surfaces on the dashboard.

  • Edit dates, guests, or room category from the reservation edit view.
  • Cancel to release inventory while keeping audit trail (pms_reservations.cancel_reservation).
  • Mark as no‑show if applicable; configure fees via Billing if needed.

Guests

  • Create guests via Guests → New: name, email, phone, address, city, country, ZIP.
  • Attach identity documents using guest IDs if local regulations require.
  • View history to see past stays and preferences.

  • Earn 1 Loyalty Point for every 10 EUR paid on a reservation folio. Points are calculated using floor; amounts under 10 EUR add 0 points.
  • Status thresholds: Bronze ≥ 200, Silver ≥ 500, Gold ≥ 1000, Platinum ≥ 5000 points.
  • Editing a guest’s Loyalty Points in Guests → Edit will automatically recalculate and save the appropriate Loyalty Status.
  • Points accrue automatically when you record payments in Billing or when you use Check‑out to auto‑settle the balance.

Technical: points and status updates are handled server‑side; manual database edits are not required.

Rooms

  • Rooms are grouped by Room Categories. Define categories in Admin, then add physical rooms.
  • Monitor room status (vacant, occupied, dirty/clean) and filter by availability.
  • Use the availability grid on Reservations to visualize occupancy across dates.

Back‑end: pms_rooms.py for inventory and availability queries.

Housekeeping

  • Track room cleaning status and assignments per day.
  • Switch statuses to coordinate cleaning and inspection.

Back‑end: pms_housekeeping.py. A test utility exists at tools/test_hk_sync.py.

Billing

  1. Open Billing and select the hotel; open an active folio for a checked‑in reservation.
  2. Add folio items (room night, minibar, fees) with amounts and taxes.
  3. Record payments (cash, card, transfer) and verify remaining balance.
  4. Print or export the invoice using the print view.

UI: billing.html and billing_print.html. Back‑end: pms_billing.py; routes in src/routes/billing_routes.py.

  1. Go to Admin → Rate Management to configure VAT Settings for the selected hotel.
  2. Choose whether Rates include VAT (included) or exclude VAT (added on top).
  3. Enter VAT rates as decimal fractions (e.g., 0.19 for 19%). For convenience, values like 19 or 7 are also accepted and normalized.
  4. Map which VAT rate applies to each charge category: Room, Meal/F&B, and Other.
  5. On the Billing page, the folio shows a VAT Summary with correct percentages (e.g., 19.00%, 7.00%) and Net / VAT / Gross totals, honoring your include/exclude setting.

Stored per hotel in hotels.vat_config. The summary groups charges by mapped VAT rate and displays normalized percentages.

  1. When a guest is CHECKED_IN, open the reservation details and pick a Payment Method (Cash, Credit Card, Debit Card, Direct Bill, or Invoice).
  2. Click Check‑out. The system automatically creates a payment for the Due amount and marks the folio PAID when fully settled. If the balance is already zero and no payments exist, a payment record is created (amount can be 0) to keep the audit trail.
  3. Manual payments: In Billing, open the folio and use the Add Payment button. Leave amount empty to post the current Due; optionally enter a method.
  4. Loyalty: Each payment accrues 1 point per 10 EUR to the guest profile (rounded down). Check‑out auto‑payments also accrue points; editing points in Guests recalculates status.
  5. Filters: Use Status (Open/All/Paid/Closed), Reservation ID or Confirmation Code to locate folios. The Open view excludes fully paid folios; lists are sorted by folio number.

Payments are stored in the payments table with method and timestamp; folio status flips to PAID once total ≤ sum of payments.

  • Post room charges nightly or at check‑out depending on your policy.
  • Use separate folio items for taxes for transparency.
  • Do not close folios with non‑zero balance; post balance adjustments first.

Reports

  1. Open Reports. Select Hotel, Report Type (OCCUPANCY, REVENUE, FORECAST, MEAL_PLANS), and Date Range.
  2. Click Run to generate combined PMS/RMS insights where applicable.
  3. Export CSV via the Export button or use the API: 
    GET /api/reports?report_type=MEAL_PLANS&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD
GET /api/reports/export?report_type=MEAL_PLANS&start_date=YYYY-MM-DD&end_date=YYYY-MM-DD

Implemented in src/routes/rms_routes.py using pms_rms_integration.get_combined_report; hotel selection via get_all_hotels(). Aliases accepted for meal plans: MEALS, MEAL, MEAL_PLAN, MEALPLANS.

Meal Plans report

Shows per-day counts of guests on Breakfast or Half-board and configured per-person amounts/currency for each date. CSV columns: date, breakfast_count, breakfast_amount, breakfast_currency, half_board_count, half_board_amount, half_board_currency.

Meals Checklist: A printable list for the restaurant at /meals-list with hotel and date filters. Also accessible from the Meal Plans report via the “Meals Checklist” button.

Admin

  • Manage Hotels and select active hotel context if you have multiple.
  • Define Room Categories and Rooms; keep inventory accurate.
  • Configure VAT Settings in Admin → Rate Management (rates included/excluded, full/reduced/extra rates, category mapping).
  • Map users to hotels (performed by administrators).

Template: admin.html; Back‑end: pms_hotels.py for hotel and categories.

User & Role Management

Roles and Permissions
  • Admin: Full access to all modules, including the Admin section and user management.
  • Front Desk: Read and write across operational pages (Reservations, Guests, Rooms, Billing, Reports) but no access to the Admin section.
  • Housekeeping: Read and write in Housekeeping; read access to Reservations; Reports limited to Meal Plans only.

Note: Housekeeping report restriction is enforced in the UI (dropdown shows only Meal Plans) and in the API (/api/reports, /api/reports/export return 403 for other types).

Add a New User (Admins)
  1. Navigate to Admin → User Management.
  2. Fill in: First Name, Last Name, Email (username), Password, and select a Role (Admin, Front Desk, Housekeeping).
  3. Click Add User. The user appears in the list below.

Email is the login username. Passwords are stored securely (hashed). Consider using strong passphrases.

Role Names & Normalization
  • Inputs are normalized case‑insensitively and spaces become underscores. Examples: "Admin", "admin" → ADMIN; "Front Desk" → FRONT_DESK; "Housekeeping" → HOUSEKEEPING.
  • Legacy synonyms MANAGER and STAFF are mapped to FRONT_DESK.
Password & Access Tips
  • Use a strong password and change it periodically. If forgotten, use Forgot Password.
  • Assign each user the minimal role they need. Limit Admin accounts to trusted personnel.
  • For reports, Housekeeping can only run Meal Plans.
Go to Admin Open Reports Forgot Password

Front Desk, Key Cards, Messaging

  • Front Desk: Utilities in pms_front_desk.py power check‑in/out flows and lists of due check‑outs.
  • Key Cards: pms_key_cards.py and assignments help manage physical keys where supported.
  • Messaging: pms_messaging.py and message templates enable guest communications.

Troubleshooting & FAQs

  • Ensure you are logged in; check the access_token cookie exists.
  • Ask an admin to assign your user to a hotel.
  • If redirected to Login repeatedly, your token may be expired—log in again.

  • Verify database settings and run src/db_init.py or application bootstrap.
  • Check that the hotel exists and has rooms; many lists are empty otherwise.

  • Confirm the date range covers stays/payments in your database.
  • Select a different hotel if you manage multiple.

For deeper technical details, see docs/pms_documentation.md included in this project.

RMS Integration (Final Rates)

Configure a connection to rms.aries-software.net to pull Final Rates into PMS. Rates are stored in category_daily_rates and mapped to your hotel's Standard room category (we pick the first category whose name starts with "Standard"; otherwise the first category).

Configure credentials
  1. Go to Admin → RMS API Credentials.
  2. Enter RMS Base URL (defaults to https://rms.aries-software.net), RMS Hotel ID, and API Key (header X-API-Key).
  3. Click Save & Test. You will see a short validation result and a Request ID for support.
  4. Plans: Only STANDARD and ENTERPRISE can import final rates.
Import Final Rates
  1. On the same page, pick Start Date and End Date and click Import Final Rates.
  2. The importer calls the RMS endpoint /api/v1/hotels/{rms_hotel_id}/final-rates?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD.
  3. Successful imports report inserted, updated, and skipped counts.
  4. If the remote request fails (e.g., 403/5xx), PMS shows a clear error and no local data is inserted.
Import from Rate Management (per category)
  1. Open Admin → Rate Management and select the Hotel, Room Category, and Date Range.
  2. Click Import RMS Final Rates. This calls PMS endpoint POST /api/rms/final-rates/import with the selected room_category_id, which proxies to RMS /api/v1/hotels/{rms_hotel_id}/room-categories/final-rates?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&room_category_id=ID.
  3. The returned rates are upserted into category_daily_rates for the selected category. The table updates after import.
  4. Requirements: user role ADMIN and hotel plan STANDARD or ENTERPRISE; RMS integration must be enabled with valid API key and RMS Hotel ID.
Quick cURL test
curl -sS -D - \
  -H "X-API-Key: YOUR_RMS_API_KEY" \
  "https://rms.aries-software.net/api/v1/hotels/YOUR_RMS_HOTEL_ID/final-rates?start_date=2025-09-21&end_date=2025-09-30" | head -n 20

See also: docs/troubleshooting_rms.md for connectivity tips.

Channel Manager API

Aries PMS now exposes a Channel Manager API for connected partners to read availability and rates, and to create reservations. Access is gated: only hotels that purchased the CM_API module can use it, and API calls must include a valid API key with required scopes.

Authentication
  • Authorization header: Authorization: Bearer <key_id>:<secret>
  • Each key is bound to a specific hotel and has scopes (permissions).
  • Required scopes by endpoint:
    • cm:inventory:read – GET availability
    • cm:rates:read – GET rates
    • cm:reservations:write – POST reservations
Endpoints
  1. Availability
    GET /api/cm/v1/hotels/{hotel_id}/availability?start=YYYY-MM-DD&end=YYYY-MM-DD&mode=count|grid 
    curl -s \
  -H "Authorization: Bearer <key_id>:<secret>" \
  "http://localhost:8000/api/cm/v1/hotels/1/availability?start=2025-10-01&end=2025-10-03&mode=count"
  2. Rates
    GET /api/cm/v1/hotels/{hotel_id}/rates?start=YYYY-MM-DD&end=YYYY-MM-DD 
    curl -s \
  -H "Authorization: Bearer <key_id>:<secret>" \
  "http://localhost:8000/api/cm/v1/hotels/1/rates?start=2025-10-01&end=2025-10-03"

    This endpoint fetches Final Rates from the remote RMS for the given date range, upserts them into PMS under the hotel's Standard room category, and returns the stored rates. If the remote call fails, it returns HTTP 502.

  3. Create Reservation
    POST /api/cm/v1/hotels/{hotel_id}/reservations 
    curl -s -X POST \
  -H "Authorization: Bearer <key_id>:<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "guest": {"first_name": "API", "last_name": "Tester", "email": null, "phone": null},
    "stay": {"check_in_date": "2025-10-01", "check_out_date": "2025-10-03", "adults": 2, "children": 0},
    "special_requests": "Quiet room",
    "preferred_room_id": null,
    "client_reference": "ext-12345"
  }' \
  "http://localhost:8000/api/cm/v1/hotels/1/reservations"

    Idempotency (best-effort): posting the same guest + dates again may return the existing reservation.

Admin: API Keys
  • Navigate to Admin → “Channel Manager API” section.
  • Create a key for the selected hotel, choose scopes, and copy the Secret now – it is shown only once.
  • Use the displayed Authorization example directly in your API client.
Testing / Sandbox
  • Run basic auth/route checks: ARIES_SKIP_DB_INIT=1 python tools/test_cm_api_readonly.py
  • End-to-end reservation create and scope checks: ARIES_SKIP_DB_INIT=1 python tools/test_cm_api_write.py
  • Seed a key for a hotel from CLI: python tools/seed_cm_api_key.py --hotel-id <ID>
Note: CM API access requires an active entitlement (CM_API) for the property. Keys are hotel-bound and rate-limited.

Last updated: 2025-09-21 20:57

Support

If you have other problems or questions, create a support ticket here.