> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/other/cloudbeds/best-practices.md).

# Best Practices

## Recommended setup

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Join Reservations with Guests and Transactions</strong></td><td>Reservations alone only give you booking metadata. Join on Guest ID to add contact details, and on Reservation ID to add payment data — this gives you the complete picture for any guest stay analysis.</td></tr><tr><td><strong>Use one API key per property</strong></td><td>If you manage multiple properties, generate a dedicated API key for each one in Cloudbeds. Then use the Append transformation in Coupler.io to merge data across properties into a single destination table.</td></tr><tr><td><strong>Start with Reservations as your anchor entity</strong></td><td>Reservations link to almost every other entity (guests, rooms, transactions, packages). Build your data model around this entity and join others to it rather than treating each entity as standalone.</td></tr></tbody></table>

## Data refresh and scheduling

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Refresh Transactions and Reservations more frequently</strong></td><td>These change throughout the day as payments are processed and bookings are updated. Rooms and Hotels data changes rarely — you can refresh those less often to stay within Cloudbeds API rate limits.</td></tr><tr><td><strong>Avoid running multiple property data flows at the same time</strong></td><td>If you're pulling from several properties using separate API keys, stagger your scheduled runs by at least a few minutes to avoid hitting Cloudbeds' rate limits across simultaneous requests.</td></tr></tbody></table>

## Performance optimization

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><strong>Use Aggregate for revenue summaries</strong></td><td>Instead of sending raw transaction rows to a spreadsheet and summing there, use Coupler.io's Aggregate transformation to pre-summarize revenue by date, room type, or booking source before it reaches the destination.</td></tr><tr><td><strong>Pull static entities separately</strong></td><td>Hotels, Rooms, and Packages change infrequently. Set these up as separate data flows with low refresh rates so they don't count against your API quota when refreshing high-frequency data like Reservations.</td></tr></tbody></table>

## Common pitfalls

{% hint style="danger" %}
Don't mix properties in a single API key. Cloudbeds API keys are property-scoped — using one key for multiple properties won't return combined data; it will only return data for the property the key belongs to. Use Append to combine, not a shared key.
{% endhint %}

{% columns %}
{% column %}
**Do**

* Filter Transactions by type (charge, payment, refund) when calculating net revenue
* Account for the property's local time zone when working with date fields
* Use reservation status as a filter to exclude cancelled bookings from revenue reports
  {% endcolumn %}

{% column %}
**Don't**

* Assume raw Transaction totals match Cloudbeds built-in reports without checking filter logic
* Run all entities on the same high-frequency schedule — prioritize by how often data actually changes
* Forget to update the API key in Coupler.io if you regenerate it in Cloudbeds
  {% endcolumn %}
  {% endcolumns %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.coupler.io/sources/category/other/cloudbeds/best-practices.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.