Set Up Cloudbeds PMS Integration

Quick Setup

Connecting Cloudbeds usually takes about 10 minutes. Cloudbeds uses OAuth v3. AVA supplies v3 when the callback omits a version. Cloudbeds v1 and v2 are retired. Explicit v1 or v2 requests return an unsupported-version error. Remove the version pin and start a new connection. Cloudbeds now requests item access, read-only add-on access, and read access for hotel, rate, and taxes/fees. It also requests adjustment write access for supported rate-preservation updates. AVA saves other unsaved Essentials changes before the OAuth redirect. Cloudbeds becomes the active PMS after authorization finishes. The provider selection refreshes automatically when finalization completes.

This guide helps you connect Cloudbeds. It keeps reservation, guest, housekeeping, payment, room, currency, hotel, rate, and tax data in sync. If Cloudbeds rejects the connection, AVA now shows the exact reason on the error banner.

Cloudbeds calendar reads and rate-plan catalog actions appear separately in AVA. Write actions remain capability-gated during the initial rollout.

Where to Find It

Settings → Essentials → Property Management System (PMS) Integration

Before You Start

You'll need:

• A Cloudbeds account with admin access
• Your Cloudbeds login credentials
• Permission to authorize third-party apps

warning

Only one Cloudbeds account can be connected at a time per property.

Connecting to Cloudbeds

Step 1: Select Cloudbeds as Your PMS

1. Go to Settings → Essentials
2. Scroll to Property Management System (PMS) Integration
3. Click the Cloudbeds card
4. A checkmark (✓) appears to confirm selection

Selecting the card prepares the connection. AVA activates Cloudbeds after OAuth authorization completes. You should not need to select Cloudbeds and save again.

Step 2: Start the Connection

1. Click the Connect to Cloudbeds button
2. AVA saves other unsaved Essentials changes first
3. Your browser opens the Cloudbeds authorization page

Step 3: Authorize Access

1. Log in to your Cloudbeds account
2. Review the permissions AVA is requesting
3. Click Authorize or Allow
4. Return to AVA after authorization finishes

AVA receives the Cloudbeds Property ID and API key through OAuth. You do not need to enter these values manually.

AVA now requests these permissions:

Permission	What AVA uses it for
read:hotel	View hotel metadata
read:guest	View guest details
write:guest	Update guest details
read:housekeeping	View housekeeping data
write:housekeeping	Update housekeeping data
read:rate	View rate plan data
read:payment	View payment data
write:payment	Update payment data
read:reservation	View reservation data
write:reservation	Update reservation data
read:room	View room data
write:room	Update room data
read:currency	Read property currency settings
read:taxesAndFees	View taxes and fee data
read:item	View item catalog data
write:item	Update item catalog data
read:addon	View add-on catalog data
write:adjustment	Preserve rates during supported reservation updates

Existing Cloudbeds Connections

If you connected Cloudbeds before this fix, your token keeps its existing permissions. Reconnect from Settings → Essentials to receive the full current permission set.

Step 4: Verify Connection

1. Return to AVA settings
2. Wait for "Finalizing connection..." (5-10 seconds)
3. Status shows a green checkmark
4. Message displays: "Cloudbeds Account Linked"
5. Confirm the Cloudbeds provider card remains selected

Connection complete! 🎉

AVA refreshes the provider selection after finalization. The selected card should show Cloudbeds without a manual page refresh.

Cloudbeds OAuth Errors

When Cloudbeds blocks the connection, AVA shows a readable message. You no longer need to guess from a generic failure.

What you see	What it means	What to do
Cloudbeds did not return the OAuth state parameter.	Cloudbeds callback is missing state data.	Start the connection again.
Cloudbeds did not return an authorization code.	Cloudbeds did not finish authorization.	Reconnect from Settings → Essentials.
Cloudbeds OAuth state verification failed.	The callback state was invalid or expired.	Reconnect Cloudbeds.
Could not identify the merchant for this Cloudbeds link.	AVA could not match the callback to your hotel.	Check you are logged into the right property.
Version is required.	The OAuth callback did not complete.	Start a new Cloudbeds connection. AVA uses OAuth v3 automatically.
Unsupported Cloudbeds version.	The request selected retired Cloudbeds v1 or v2.	Remove the version pin, then start a new connection.
Cloudbeds rejected the authorization code exchange.	Cloudbeds rejected the single-use authorization code.	Start a new Cloudbeds connection so Cloudbeds generates a fresh code.
Failed to link Cloudbeds account.	AVA could not map the backend error.	Copy the full message and contact support.

What Syncs Automatically

Cloudbeds uses webhooks for real-time updates. When changes happen in Cloudbeds, AVA is notified immediately:

Event	What Happens
Reservation created	AVA receives notification and can schedule pre-arrival messages
Reservation dates changed	AVA updates any scheduled messages
Check-in/out status	Status syncs in real-time
Guest profile updated	AVA refreshes the latest guest details, including email changes used for automatic resend catch-up

When you view reservations in AVA, the system fetches the latest data directly from Cloudbeds. This ensures you always see current information.

info

Data flows primarily from Cloudbeds → AVA. Guest updates made in AVA (like check-in completion) are sent back to Cloudbeds.

Guest email updates

When Cloudbeds sends a guest update, AVA can re-send elapsed pre-arrival emails to the guest's latest PMS address. That automatic catch-up runs after the next sync.

Cloudbeds read protection

If several staff members request the same Cloudbeds data at once, AVA shares one read request. If Cloudbeds returns the same access or success:false error again, AVA pauses repeated retries briefly.

Cloudbeds arrival time updates

When the primary guest syncs, AVA can send the reservation's estimated arrival time to Cloudbeds v3. Companion guests do not update that time. Invalid, missing, or empty times are ignored, so AVA does not clear existing PMS data. If that optional update fails or Cloudbeds does not support it, the guest sync still succeeds.

Rates and Availability

AVA reads Cloudbeds' detailed daily rates for the Operations → Rates & Availability calendar. The calendar can show prices, room counts, CTA, CTD, and minimum or maximum stay restrictions. Missing room or rate rows remain visible, so you can identify incomplete Cloudbeds data.

Cloudbeds rate-plan catalog management is separate from the daily calendar. You may see list, edit, activation, deactivation, or delete actions when enabled for your property. AVA does not create public Cloudbeds rate plans because metadata-only plans may not be sellable.

Cloudbeds writes are asynchronous

Supported ARI changes return an accepted status while Cloudbeds processes the job. AVA checks the published calendar value before showing success. Do not repeat the same change while the first change is still pending.

Cloudbeds capabilities control each action separately. Your property may edit restrictions while price changes, price clearing, or stop sell remain unavailable. Derived prices can remain read-only even when their restrictions are editable.

AVA shows Queued, Failed, Verified, or Verification timeout outcomes for supported writes. Verification can take up to seven minutes while AVA checks the PMS job and calendar read-back. Refresh manually when verification times out.

Payment Posting Behavior

Cloudbeds shared bills post one consolidated payment against the shared parent reservation. AVA keeps room-level trace metadata so staff can audit the allocation later. If a booking does not use a shared bill, AVA posts reservation by reservation as usual.

When AVA posts a payment, Cloudbeds stores these details in the payment description:

• Gateway Transaction ID: The payment gateway transaction identifier.
• Payment Reference: The AVA payment reference.

Use either value to match the Cloudbeds folio line with the payment in Stripe. Cloudbeds keeps the two description lines when you read the folio later.

If AVA must recover a missing Cloudbeds payment method, it uses the required method code. AVA reuses a matching method when possible, so repeated payments do not create duplicates.

Reconcile a Cloudbeds payment

1. Open the reservation in AVA and note its Transaction ID or payment reference.

2. Open the same reservation's folio in Cloudbeds.

3. Find the payment posted by AVA.

4. Compare Gateway Transaction ID or Payment Reference with the AVA payment.

   ✓ The amount, payment method, and reference should identify the same payment.

For shared bills, check the shared parent reservation's folio. Cloudbeds shows one consolidated payment for that shared bill.

Guest & Staff Impact

• Guest forms adapt to Cloudbeds rules. Required fields and hidden fields change based on Cloudbeds configuration, so guests only see what is needed.
• Reservation lookup uses Cloudbeds. If Cloudbeds is not connected, the guest lookup step will fail. AVA waits up to 20 seconds for the lookup before showing a service-unavailable error.
• Cloudbeds fallback lookup uses the exact OTA confirmation reference. This keeps large-property searches responsive and finds matching reservations beyond the first results page.
• ACI document scans do not change Cloudbeds occupancy. AVA checks capacity when pending companions are created or synced during Registration, then before final check-in.
• Occupancy updates preserve pre-assigned physical rooms. When AVA changes Cloudbeds Adults or Children, existing room assignments remain in place.
• Occupancy edits preserve booked rates at the source. AVA sends the no-reprice setting per room when changing Cloudbeds Adults or Children.
• A correction guard remains available. If Cloudbeds unexpectedly reprices the stay, AVA verifies the dated rates and can post a fallback correction.
• Supported source rules use source-aware math. One exclusive percentage charge uses a cent-safe pre-tax correction. Fully inclusive percentage charges, including multiple charges, use the exact gross correction.
• Dated rates are checked after Cloudbeds finishes updating. Cloudbeds applies rate changes asynchronously. AVA waits for the rate job, then checks the dated nightly rate instead of relying on a lagging plan summary.
• Unsupported source rules stop safely. Mixed, fixed, missing, unreadable, or multiple exclusive charges return PMS_RATE_PRESERVATION_SOURCE_TAX_UNSUPPORTED before occupancy changes.
• Property-level fallback remains available. AVA uses it only when the exact source has no applicable charge.
• Small Cloudbeds rounding differences do not block verification. If only subtotal and tax differ by equal, opposite amounts within 10 cents, AVA accepts the unchanged guest-facing totals.
• Small total residuals can also be accepted. After final verification retries, source-aware updates can accept a coherent total difference up to 5 cents. AVA adds a note with the settled and booked totals. Do not post a manual correction.
• Shared bills show one PMS payment. You may see that payment on the shared parent folio instead of every room.
• Guest email changes can trigger resend catch-up. When Cloudbeds sends a guest update, AVA can re-send elapsed pre-arrival emails to the latest address.
• Booking source labels can use Cloudbeds source metadata. If a reservation is missing sourceName, AVA falls back to the linked Cloudbeds source name.
• Source collect comes from the linked source record when available. That keeps hotel and channel source behavior consistent with Cloudbeds settings.
• Channel-collect invoices stay waived. When Cloudbeds v3 marks a channel-collect invoice as waived, AVA zeroes the payable totals and shows the waiver in Streamliner.
• Room condition setting affects housekeeping sync only. This setting controls whether AVA sends Clean or Inspected status to Cloudbeds when a room is marked clean in AVA. It does not change the guest UI.
• Estimated arrival time sync uses the primary guest only. Companion guests and invalid times are ignored, so AVA keeps the PMS value unchanged.
• AVA requests item access and read-only add-on access. write:addon stays excluded on purpose.
• Fallback rate corrections use adjustment access. AVA requests write:adjustment for the safety-net correction if Cloudbeds reprices unexpectedly.
• Cloudbeds OAuth scopes refresh on reconnect. Reconnect connections created before this fix to receive the full current permission set.

Missing adjustment permission

Cloudbeds must grant write:adjustment so AVA can correct an unexpected reprice during occupancy edits. If AVA reports PMS_RATE_PRESERVATION_ADJUSTMENT_SCOPE_MISSING, stop retrying the edit. Reconnect Cloudbeds with an administrator and approve the adjustment permission. AVA blocks the edit before the occupancy write, so folio reconciliation is not normally needed.

Disconnecting Cloudbeds

Only disconnect if you're:

• Switching to a different PMS
• Changing Cloudbeds accounts
• Troubleshooting sync issues

To disconnect:

1. Go to Settings → Essentials
2. Click Disconnect from Cloudbeds
3. Confirm when prompted

caution

Disconnecting stops all synchronization immediately. Existing data remains but won't update.

Troubleshooting

Connection stuck on "Connecting..."

1. Wait 30 seconds
2. Refresh the page
3. Check your internet connection
4. Try a different browser

Save error before Cloudbeds connects

What you see: "Failed to save settings before connecting: ..."

Why this happens: AVA saves other unsaved Essentials changes before leaving for Cloudbeds. The message identifies the setting that needs attention.

Fix:

1. Read the full message shown in the error banner.

2. Fix the setting named in the message.

3. Select Save if the page shows unsaved changes.

4. Select Connect to Cloudbeds again.

   ✓ AVA redirects you to Cloudbeds after the save succeeds.

Cloudbeds OAuth error message

What you see: A Cloudbeds OAuth message appears in the banner.

Fix:

1. Read the message first.
2. Match it to the table above.
3. Start a new Cloudbeds connection if the message mentions state, code, version, or token exchange.
4. Confirm you are using a Cloudbeds admin account.
5. Do not reuse a failed authorization callback. Cloudbeds authorization codes are single-use.
6. Contact support if a new connection still fails.

info

The banner now shows Cloudbeds' own error details when available. That gives you a clearer starting point for support. AVA defaults an omitted Cloudbeds OAuth version to v3. Cloudbeds v1 and v2 are no longer supported. Use versionless routing so AVA selects v3.

Reservations not syncing

1. Wait 15 minutes for the initial sync
2. Check connection status (should show green)
3. Try disconnecting and reconnecting
4. Verify reservations exist in Cloudbeds

Cloudbeds access or property error

What you see: A message like You don't have access to property ID, or the same Cloudbeds error returns right away.

Why this happens: The connected Cloudbeds account cannot read that property. AVA also pauses repeated retries for a short time.

Fix:

1. Confirm you are logged into the correct Cloudbeds property.

2. Ask a Cloudbeds admin to verify the property access and permissions.

3. Wait a minute before clicking Refresh again.

4. Contact support if the message keeps returning.

   ✓ The next refresh should work after the Cloudbeds access issue is fixed.

Cloudbeds adjustment permission is missing

What you see: An occupancy edit returns PMS_RATE_PRESERVATION_ADJUSTMENT_SCOPE_MISSING.

Why this happens: Your Cloudbeds property did not grant AVA write:adjustment access.

Fix:

1. Stop retrying the occupancy edit.

2. Go to Settings → Essentials.

3. Reconnect Cloudbeds with an administrator account.

4. Approve the write:adjustment permission.

5. Wait for the connection to finish, then retry the edit once.

   ✓ AVA should accept new occupancy edits after the permission is active.

Cached permission check

AVA may keep the property blocked for up to six hours after the first refusal. Contact support if the same code remains after reconnecting and waiting.

Cloudbeds source tax setup requires review

What you see: An occupancy edit returns PMS_RATE_PRESERVATION_SOURCE_TAX_UNSUPPORTED. The message says Cloudbeds occupancy was not changed.

Why this happens: The reservation's source tax or fee rules are unsupported. AVA stops before the occupancy write to prevent an unrecoverable reprice.

Fix:

1. Open the reservation in Cloudbeds.

2. Confirm the reservation's booking source and target room type.

3. Review the source's tax and fee charges.

4. Ask your Cloudbeds administrator to correct the unsupported source rule. This may involve mixed, non-percentage, unreadable, or multiple exclusive charges.

5. Refresh AVA and retry the occupancy edit once.

   ✓ The edit should continue after Cloudbeds exposes a supported source policy.

Do not bypass the source review

Do not change occupancy manually until you confirm the booked total in Cloudbeds. Contact support if the source rules look supported but AVA still returns this code.

Cloudbeds linked but not active

What you see: Cloudbeds links successfully, but another PMS remains selected. You may see: "Cloudbeds is linked, but it could not be set as the active PMS. Select Cloudbeds above and save to finish."

Fix:

1. Go to Settings → Essentials.

2. Select the Cloudbeds provider card.

3. Click Save.

4. Confirm the Cloudbeds card remains selected after the save.

   ✓ Cloudbeds is now the active PMS.

If the warning appears again, run the Cloudbeds connection flow again. The repeated flow retries activation for an already linked account.

Catalog tabs do not appear

What you see: The Items or Add-ons tab is missing.

Fix:

1. Reopen the Rooms page.
2. Check the Cloudbeds permission prompt.
3. Confirm the prompt includes read:item, write:item, and read:addon.
4. Contact support if catalog tabs still do not appear.

Cloudbeds authorization page doesn't open

What you see: Nothing happens after selecting Connect to Cloudbeds.

Fix:

1. Refresh Settings → Essentials.
2. Select Connect to Cloudbeds again.
3. Check your internet connection.
4. Try a different browser or private window.

Security

• Connection uses secure OAuth 2.0
• Your password is never stored in AVA
• Revoke access anytime from Cloudbeds
• Connection expires after 90 days of inactivity

Frequently Asked Questions

Can I connect multiple Cloudbeds properties? No, one property per AVA account.

Will disconnecting delete my data? No, existing data remains but won't update.

Can staff members connect Cloudbeds? No, only administrators can manage PMS connections.

Still Stuck?

Contact success@vouch-technologies.com if:

• ❌ The same OAuth error appears after reconnecting.
• ❌ Cloudbeds keeps rejecting the authorization code exchange.
• ❌ You cannot confirm the correct Cloudbeds account or property.

Helpful to include:

• Screenshot of the error banner
• Time the issue started
• The exact message shown in AVA

Related Guides

• PMS Connection
• PMS Options
• PMS Connection Errors