PMS Integration (Hotels)

Paid pluginsize Lplanned, not built

Indicative price, not an offer: €59/mo; credential: we maintain your PMS API integration, daily reconciliation

Generated from docs/plan/paid/pms-integration/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Hotel and resort merchants sync their Property Management System (Opera, Fosse, Cloudbeds) with AstroBaaS in real time, preventing overbooking and keeping inventory synchronized. The paid pack maintains PMS vendor integrations and daily reconciliation; core owns the reservation interface and booking state machine.

The problem

Hotels manage bookings in Opera or Fosse but sell through AstroBaaS website. Manual sync loses bookings when a room is reserved in PMS but still shows available online, or vice versa. Real-time two-way sync is essential.

What it does

• Real-time room inventory sync: PMS availability updates AstroBaaS cart within 5 minutes
• Booking sync: new AstroBaaS orders create reservations in PMS automatically
• Cancellation sync: PMS cancellations cascade to AstroBaaS orders with webhook notification
• Guest info sync: customer name, email, check-in date flow to PMS at booking
• Reconciliation report: daily check that AstroBaaS bookings match PMS reservations
• Conflict resolution UI: admin sees and resolves double-bookings (same room, overlapping dates)
• Test mode with mock PMS responses for development
• Audit log: every sync event, sync errors, resolution actions

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Rate parity enforcement: PMS and AstroBaaS may show different prices; we sync inventory only, not rates (merchant responsibility to keep prices aligned).
• Guest upselling: AstroBaaS does not negotiate room upgrades or add-ons within PMS (out of scope for inventory sync).
• Housekeeping integration: cleaning schedules are PMS responsibility; AstroBaaS only tracks occupancy.
• Multi-property reconciliation: each property has its own PMS instance; AstroBaaS does not merge data across properties (each is a separate storefront).

Data model

New document type: pms_reservation { reservationId (PMS-issued), bookingId (AstroBaaS), checkIn, checkOut, guestName, guestEmail, room, status, lastSyncAt }. New collection: pms_conflicts { conflictId, room, dates, pmsStatus, astroBaaSStatus, resolution }.

API

• POST /api/pms/sync { action, reservationId, bookingId, room, dates, guestInfo } (webhook from PMS or scheduled job)
• GET /api/pms/availability?roomId=123&from=2026-09-01&to=2026-09-10 -> { available, booked, pending }
• GET /api/pms/conflicts (admin only) -> list of unresolved conflicts
• POST /api/pms/conflicts/{conflictId}/resolve { decision } (admin only)
• GET /api/pms/reconciliation?date=2026-09-03 (admin only)

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Admin sees: real-time sync status (last check, next check, error count), room availability heatmap, active conflicts with side-by-side PMS vs. AstroBaaS details, manual sync button, reconciliation report viewer, PMS credential management (URL, API key).

The seam — why this is paid

Core owns the reservation interface and booking state machine. Paid pack owns: Opera/Fosse/Cloudbeds API adapters, real-time sync scheduler, conflict resolution strategy, production support and PMS vendor relationship.

Credential: PMS vendor integration (Opera, Fosse, Cloudbeds), real-time sync support

Dependencies

• booking subsystem (existing; orders have check-in/check-out dates)
• scheduler subsystem (existing; runs sync jobs)
• webhook-management (existing; receives PMS sync events)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• A room marked ‘booked’ in PMS shows as unavailable in AstroBaaS within 5 minutes
• An AstroBaaS order for room 101 on 2026-09-05 creates a reservation in Opera automatically
• A PMS cancellation sends a webhook that cancels the AstroBaaS order
• A double-booking (same room, overlapping dates, one in each system) is listed in conflicts UI
• Admin resolves a conflict by choosing ‘trust PMS’; the AstroBaaS order is cancelled
• Daily reconciliation report shows bookings synced, failures, and conflicts for the previous day
• In test mode, sync endpoints return predictable test data; no real PMS calls are made
• A sync error (PMS API timeout) is logged with timestamp, action, error details; sync retries after 5 minutes

Risks

If sync direction is one-way only, overbooking happens when PMS receives bookings outside AstroBaaS. If sync frequency is too low (e.g., hourly), customers book the same room twice in the gap. If guest info is sent to PMS without consent, GDPR is violated. If conflict resolution auto-chooses wrong side, bookings are lost. If reconciliation runs before sync completes, it reports false conflicts.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.