Skip to main content

Scan Guest Entitlements

Quick Check

Most scans take under 1 minute. Refreshes now stop early when the PMS starts throttling requests.

Use this guide when you need to scan a guest card, refresh reservation data, or use manual lookup. Normal refreshes reuse unchanged reservations. That keeps most updates faster and reduces PMS reads.

AreaWhat it doesWhat you should expect
ScanReads a guest keycard against today's snapshotThe matched reservation opens on screen
RefreshRebuilds today's reservation snapshotThe banner shows progress, counts, and a ready state
Manual lookupFinds a reservation by room or confirmation numberYou can still work when a card does not read
BenefitsManages benefit definitions and rate-plan assignmentsOnly shows actions your PMS supports
ActivityShows today's consumptions and sync statusYou can undo or retry failed syncs

Open the Page​

  1. Open Entitlements.

  2. Start on the Scan tab.

  3. Select a connected encoder if you need card scans.

    ✓ The Start scanning button becomes available when a snapshot is ready.

PMS-backed keycard readers

AVA can scan through a PMS-backed reader when that connection advertises keycard reading. The reader appears with your other eligible encoders.

Refresh Reservation Data​

The page keeps a local snapshot for the hotel's current business date. Normal refreshes are incremental. They reuse fresh entries whose PMS revision has not changed. When your PMS supports it, AVA uses one bulk entitlement check first. It then reads only reservations that actually need entitlement data.

  1. Click Refresh for a normal update.

  2. Click Force full when the snapshot looks stale or you need a full rebuild.

  3. Wait for the status banner to change to a ready state.

    ✓ The page can now scan cards again.

Automatic refresh

If no active snapshot exists, AVA starts the first refresh automatically. If refresh returns partial same-day data, AVA keeps usable rows on screen. Existing snapshot-only scans stay available while refresh runs. If the PMS starts throttling the refresh, AVA stops that run. It keeps the last usable snapshot visible.

Read Refresh Counts​

The status banner now shows refresh progress counts.

CountWhat it meansWhy it matters
FetchedReservations read fresh from the PMSHigher counts mean more new or changed rows
ReusedReservations carried forward from the previous snapshotHigher reuse usually means a faster refresh
PagesChecked-in PMS list pages read during the refreshHelps you spot slow or unusually deep list scans

Use these counts to confirm whether a refresh was mostly reused or fully rebuilt.

Handle A Throttled Refresh​

Use this when a refresh stops before you expect it to finish. You may also see fewer fetched reservations than usual.

  1. Wait a minute before trying again.

  2. Click Refresh again.

  3. Keep using the current snapshot if it still covers today's guests.

  4. Ask an admin to check PMS rate limits if this keeps happening.

    ✓ AVA does not pretend the refresh finished when the PMS throttles it.

Scan a Card​

  1. Open Entitlements.
  2. Stay on Scan.
  3. Select an online encoder.
  4. Click Start scanning.
  5. Tap the guest keycard.
  6. Review the matched reservation.
  7. Click Consume 1 when the guest uses the entitlement.
  8. Click Manager override only when a manager approves an exception.
  9. Click Done when you finish with that guest.

✓ The banner briefly shows Card scanned — ready for the next card in a moment. ✓ Scanning then returns to Ready — tap the next card at any time.

Use Manual Lookup​

Use manual lookup when the card does not read, or when you need a room-based search. AVA checks the stay dates before it triggers a paid entitlement read. If the dates are missing or invalid, fix the reservation first.

  1. Use Look up by room when you know the room number.
  2. Use Look up by confirmation number when you know the booking reference.
  3. Wait for the reservation card to appear.
  4. Use the entitlement cards the same way as a scan result.
Live fallback

When a manual lookup misses the cache, AVA may check the PMS live. That result appears with a note until the next refresh includes it.

Read Snapshot Status​

Banner textWhat it meansWhat you do
in-house reservations readyThe snapshot is ready for scansStart scanning
Refreshing PMS reservations…AVA is rebuilding the snapshotWait for the refresh to finish
using earlier same-day dataA same-day refresh failed, but usable data remainsRefresh again when you can
unavailable until the next refreshThat reservation is not usable yetRefresh or use manual lookup
Reservation data must be refreshed before scanningNo ready snapshot exists yetClick Refresh
When the page shows a warning

The page also warns when PMS access is missing, unsupported, throttled, or unavailable. Existing snapshots can stay visible in those cases.

Benefits and Activity​

The other tabs still work the same way.

  • Benefits shows the benefit catalog when your PMS exposes it.
  • Activity shows today's consumptions, undo actions, and retry actions.
  • Rate plan assignments stay in Benefits when your PMS allows them.

Troubleshooting​

What you see: Reservation data must be refreshed before scanning​

Fix:

  1. Click Refresh.
  2. Wait for the ready state.
  3. If needed, click Force full.
  4. Open Entitlements again if the banner does not update.

What you see: The page shows a PMS warning​

Fix:

  1. Keep using the current snapshot if it is still available.
  2. Ask an admin to reconnect the PMS or restore capability access.
  3. Refresh again after the PMS issue is fixed.

What you see: A refresh stops early or shows a throttle warning​

Fix:

  1. Wait a minute before retrying.
  2. Click Refresh again.
  3. Keep using the current snapshot if it still covers today's guests.
  4. Ask an admin to check PMS rate limits if it happens again.

What you see: A manual lookup does not return a usable result​

Fix:

  1. Check that the reservation has valid stay dates.
  2. Confirm the room number or confirmation number is correct.
  3. Refresh the reservation in PMS, then try again.
  4. Use Force full if the snapshot still looks stale.

What you see: A scan shows multiple reservations or no match​

Fix:

  1. Pick the correct guest when several reservations match.
  2. Check that the selected encoder is online.
  3. Use Look up by room or Look up by confirmation number.
  4. If the card still does not match, ask support to review the reservation mapping.

What you see: Physical keycard reading is not enabled​

Fix:

  1. Use Look up by room or Look up by confirmation number.
  2. Ask an admin to check the property's room-access capability.
  3. Confirm the reader is configured in Settings → Room Access.
  4. Reload Entitlements after the connection is updated.
Manual lookup stays available

AVA disables card scanning when the connection cannot read cards. Room and confirmation lookups remain available.

What you see: A result says it was checked live in the PMS​

Fix:

  1. Use the result for the current guest.
  2. Click Refresh so later scans use the updated snapshot.
  3. Recheck the reservation if the live result still looks wrong.

Still Stuck?​

Contact success@vouch-technologies.com if:

  • ❌ The snapshot never becomes ready.
  • ❌ Card scans keep missing valid reservations.
  • ❌ Live fallback keeps appearing after refreshes.

Helpful to include:

  • Reservation ID or confirmation number
  • Room number
  • Screenshot of the status banner
  • Time the issue started