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.

Guest Online Check‑In (Admin)

Aries PMS includes a privacy‑first, one‑click Guest Online Check‑In flow. Guests receive a secure, one‑time link and can confirm their check‑in before arrival. Links are valid until the end of the arrival day and become unusable after completion. Tokens are stored as bcrypt hashes in the database.

1) Enable the add‑on for a hotel
  1. Open Admin and select the hotel (top section).
  2. Under Subscription Add‑ons, choose Online Check‑In and click Subscribe.
  3. Once enabled, the Online Check‑In Email (SMTP) Settings panel appears for that hotel.
2) Configure SMTP for invitations
  • In Admin → Online Check‑In Email (SMTP) Settings, enter SMTP Server, Port, Username/Password, From Email/Name, and TLS option.
  • If per‑hotel SMTP is empty, PMS falls back to global settings from .env: SMTP_SERVER, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, SMTP_USE_TLS, SMTP_FROM, SMTP_FROM_NAME.
  • Emails are sent as multipart (plain text + HTML) for best deliverability.
3) Send invitations

From the Admin UI:

  1. Use Send Online Check‑In emails now and select Days before arrival (default 2) and optional limit.
  2. PMS schedules a background task to email eligible reservations for the selected hotel.

From the CLI (automation/cron):

python tools/send_online_checkin_emails.py \
  --days-before 2 \
  --hotel-id YOUR_HOTEL_ID \
  --base-url https://pms.your-domain.com [--limit 100] [--dry-run]

Script applies the same eligibility rules as the Admin action.

Eligibility (per reservation):
  • Status = CONFIRMED
  • Online check‑in not yet completed
  • No prior online check‑in email sent
  • Guest has a valid email
  • Hotel has active ONLINE_CHECKIN entitlement
4) Guest experience
  • Guest receives an email with a one‑time link: /online-checkin?token=....
  • The page shows hotel name, guest name, arrival date, and a confirmation checkbox.
  • On submit, PMS validates the token again and marks the reservation as online check‑in completed.
  • Tokens expire automatically at the end of the arrival day and are invalidated immediately after use.
5) How it works (technical)
  • Token creation: pms_reservations.create_or_refresh_online_checkin_token() stores a token id, a bcrypt hash of the secret, and an expires_at set to end of arrival day.
  • Validation: pms_reservations.validate_online_checkin_token() checks status, completion flag, expiry, and verifies the hash.
  • Completion: pms_reservations.mark_online_checkin_completed() sets online_checkin_completed_at = NOW() and clears token fields.
  • Email sending uses per‑hotel SMTP (get_hotel_smtp_settings) with global .env fallback.
  • Base URL for links: PUBLIC_BASE_URL (or APP_BASE_URL/PMS_BASE_URL) when present; otherwise request base URL.
6) Verification & Operations
  • After completion, front desk can proceed with a quicker on‑site check‑in from the reservation page.
  • For auditing, database fields include reservations.online_checkin_email_sent_at and reservations.online_checkin_completed_at.
Open Admin Preview Online Check‑In CLI Script: tools/send_online_checkin_emails.py

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 the hotel has Online Check‑In enabled in Admin.
  • Check SMTP settings for the hotel; if blank, ensure global .env SMTP variables are set.
  • Confirm guests have non‑empty emails and reservations are CONFIRMED for the selected arrival date.
  • Use the Send Online Check‑In emails now button in Admin, or run the CLI script with --dry-run to see candidates.

  • Completed check‑ins are recorded in reservations.online_checkin_completed_at (database field).
  • Front desk can proceed with on‑site check‑in normally; the guest has already confirmed online.

  • 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 and POST quote
    • 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[&room_category_id=ID] 
    # Default (maps to Standard category)
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"

# Per-category (imports from RMS and returns that category's rates)
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&room_category_id=2"

    If room_category_id is provided, PMS calls RMS /room-categories/final-rates for that category, upserts results into category_daily_rates, and returns them. Missing or invalid RMS responses return HTTP 502.

  3. Quote
    POST /api/cm/v1/hotels/{hotel_id}/quote 
    curl -s -X POST \
  -H "Authorization: Bearer <key_id>:<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "stay": {"check_in_date": "2025-10-01", "check_out_date": "2025-10-03", "adults": 2, "children": 1},
    "room_category_id": 2,
    "meal_plan": "BREAKFAST"
  }' \
  "http://localhost:8000/api/cm/v1/hotels/1/quote"

    Returns nightly breakdown (base, extra‑guest surcharges, meal plan), VAT per item (based on hotel VAT config), currency, and totals. If any rate dates are missing, responds with HTTP 409 and a list of missing_rate_dates.

  4. 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",
    "agreed_total_amount": 218.00,
    "currency": "EUR",
    "meal_plan": "BREAKFAST",
    "nightly_breakdown": [
      {"date": "2025-10-01", "base": 100.00, "extra_guest": 18.00, "meal": 0.00},
      {"date": "2025-10-02", "base": 100.00, "extra_guest": 0.00, "meal": 0.00}
    ],
    "create_folio": true
  }' \
  "http://localhost:8000/api/cm/v1/hotels/1/reservations"

    Idempotency (best‑effort): posting the same guest + dates again may return the existing reservation. If create_folio is true, PMS will create an OPEN folio and add nightly ROOM/MEAL items from your breakdown (or use agreed_total_amount if no breakdown is provided).

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.

See also: IBE Integration Guide.

Last updated: 2025-12-14

Support

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