Scan Guest Entitlements

Quick Check

Most scans take under 1 minute. The first refresh each business day builds a lightweight reservation list. Entitlement details load only after you select a reservation.

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.

Area	What it does	What you should expect
Scan	Reads a guest keycard against today's snapshot	The matched reservation opens on screen
Refresh	Rebuilds today's reservation snapshot	The banner shows progress, counts, and a ready state
Manual lookup	Finds a reservation by room or confirmation number	You can still work when a card does not read
Benefits	Manages benefit definitions and rate-plan assignments	Only shows actions your PMS supports
Activity	Shows today's consumptions and sync status	You 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. The property's Enable physical keycard reading setting must also be on.

Opera card scans

Opera card scans provide room and validity details, but they do not provide the guest name. Use the matched reservation details to confirm the guest before managing entitlements.

Refresh Reservation Data

The page keeps a local snapshot for the hotel's current business date. Normal refreshes are incremental. They reuse successful details when the PMS reservation revision is unchanged. The refresh reads the in-house reservation list only. It does not load entitlement details for every reservation. Guests departing today remain eligible while they are still in the room. Some PMSs label these stays DUE_OUT or Due Out instead of CHECKED_IN.

1. Click Refresh for a normal update.

2. Click Refresh + clear cache when details look 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.

Count	What it means	Why it matters
Fetched	Reservations read fresh from the PMS	Higher counts mean more new or changed rows
Reused	Reservations carried forward from the previous snapshot	Higher reuse usually means a faster refresh
Deferred	Reservation details waiting for a unique selection	These details do not need a PMS read yet
Hydrated	Reservations with loaded entitlement details	This count shows how much detail AVA has checked
Pages	PMS reservation list pages read during the refresh	Helps you spot slow or unusually deep list scans

Departure-day guests

AVA keeps a guest on the entitlement roster until the PMS marks the stay checked out. Refresh the snapshot before serving breakfast or another departure-day benefit.

The snapshot tracks hydrated reservations separately from deferred reservations. The entitlement total may be a lower bound while details remain deferred. It becomes complete after every reservation has loaded or returned no benefits.

Load Reservation Details

1. Scan a guest card or use manual lookup.

2. Select the room result when several room matches appear.

3. Wait while AVA loads that reservation's entitlement details.

   ✓ Successful results, including no-benefit results, remain cached for the business day.

Repeated scans and lookups reuse that cached result. A failed detail read affects only the selected reservation. AVA waits before retrying, and rate-limit responses can extend that wait.

Opera next-day benefits

Opera can store a next-day package against the previous stay night. AVA uses Opera's schedule flag to show the benefit on its actual redemption date. The hotel business date controls redemption, while the matched PMS date controls the allowance row. For example, a 28 August breakfast can use Opera's 27 August schedule row. Schedules without an explicit stay-night basis continue using the hotel business date.

Mews posting dates

Mews normally posts benefits against the occupied stay night. A 27 August posting can therefore appear as breakfast for 28 August. AVA keeps this default when the Mews product catalogue is unavailable. Explicit same-day schedules, including PostingTimeUnit, use their supplied redemption date.

When the PMS date differs from today's date

Some PMS benefits use the occupied stay night as their schedule date. This is common for next-day breakfast packages.

• AVA checks whether the guest can redeem on today's hotel business date.
• AVA reads and updates the matching PMS schedule date.
• Per-stay benefits also use the matched schedule when their valid dates come from that basis.

You do not need to change the hotel's business date manually.

Handle Family Reservations

AVA groups linked reservations for the same room into one room-level result. This includes block bookings, multi-room bookings, and reservations with sharers.

AVA uses the PMS reservation family supplied by the connection. You do not need to identify linked guests from vendor-specific shared-guest codes. Opera family reservations use normalized Primary, Sharer, or Member roles. Mews companion records use normalized Main or Accompany roles.

The result can show:

• Booked occupancy, with adults and children when the PMS provides them.
• A guest roster labeled Primary, Sharer, Accompany, or Guest.
• The allowance selected for the room's reservation group.

AVA does not add allowances from linked reservations together. It uses the highest allowance and chooses Primary when allowances tie. Consumption stays attached to the reservation that supplied the allowance.

Use the roster to confirm who you are serving before recording a benefit.

Unknown occupancy stays unknown

If the PMS does not provide booked occupancy, AVA leaves that value blank. It does not display a false zero.

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.

Starting a manual lookup stops an active card read before the search begins. The Start scanning, encoder, and candidate controls stay locked during the lookup. If several room results match, selecting one keeps the lookup card-less.

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 text	What it means	What you do
in-house reservations ready	The snapshot is ready for scans	Start scanning
Refreshing PMS reservations…	AVA is rebuilding the snapshot	Wait for the refresh to finish
using earlier same-day data	A same-day refresh failed, but usable data remains	Refresh again when you can
unavailable until the next refresh	That reservation is not usable yet	Refresh or use manual lookup
Reservation data must be refreshed before scanning	No ready snapshot exists yet	Click 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.

Undo updates the visible entitlement count directly. It does not need a follow-up refresh that could interrupt active card scanning.

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 Refresh + clear cache.
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 for the retry window to pass.
2. Select the reservation again.
3. Use the current snapshot for other guests.
4. Ask an admin to check PMS rate limits if it continues.

What you see: Entitlement details are still loading

Why this happens: AVA loads details only after a unique reservation selection. The reservation list can be ready while its entitlement details remain deferred.

Fix:

1. Confirm the reservation is selected uniquely.
2. Wait for its detail read to finish.
3. Click Refresh + clear cache if the PMS correction is newer.
4. Check the PMS connection if details remain unavailable.

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 Refresh + clear cache if the snapshot still looks stale.

What you see: Manual lookup reopens scanning or replaces a newer result

Why this happens: An older scan or lookup response may still be finishing.

Fix:

1. Wait for the current lookup to finish.

2. Do not change the encoder or select another candidate while it runs.

3. Start the lookup again with the correct room or confirmation number.

   ✓ AVA keeps the newest result and does not restart scanning from a manual lookup.

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

Fix:

1. Open the room-level result when several linked reservations match.
2. Check that the selected encoder is online.
3. Use Look up by room or Look up by confirmation number.
4. Use the roster labels to confirm the guest being served.
5. If the result still looks wrong, ask support to review the reservation mapping.

What you see: The room allowance looks too high

What you see: A grouped room result shows one allowance for several linked reservations.

Why this happens: AVA selects the highest reservation allowance. It never sums allowances from linked reservations.

Fix: Check the Primary, Sharer, and Accompany labels. Contact support if the selected allowance differs from the PMS.

What you see: A guest departing today is missing

What you see: The guest is still in the room, but room lookup says no active reservation matches.

Why this happens: The PMS may mark departure-day stays as DUE_OUT or Due Out.

Fix:

1. Confirm the guest has not checked out in the PMS.

2. Click Refresh in Entitlements.

3. Search again by room or confirmation number.

4. Use Refresh + clear cache if the guest still does not appear.

   ✓ AVA keeps checked-in and due-out stays eligible until checkout completes.

What you see: A family reservation shows the wrong allowance

What you see: A block, multi-room, or sharer reservation does not show the expected benefit.

Fix:

1. Refresh the reservation in your PMS.
2. Click Refresh + clear cache in Entitlements.
3. Search again by room or confirmation number.
4. Select the correct reservation when several candidates appear.
5. Contact support if the allowance still differs from the PMS.

What you see: Physical keycard reading is not enabled

Fix:

1. Use Look up by room or Look up by confirmation number.
2. Go to Settings → Room Access → Keycard Encoding.
3. Select PMS Integration.
4. Confirm the PMS vendor and encoder device are correct.
5. Turn on Enable physical keycard reading only after the PMS read API is validated.
6. Click Save, then reload Entitlements.
7. Contact support if the warning remains after saving.

Manual lookup stays available

AVA disables card scanning when the connection cannot read cards. Room and confirmation lookups remain available. The warning can mean reading is off, unsupported, or temporarily unavailable.

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

Related Guides

• Manage Access Codes
• Manual Keycard Encoding
• Smart Lock Problems