📚 Spell out the request paths in the Inbox Messaging guide. The guide referred to the "Inbox Conversations endpoints" and "Inbox Messages endpoints" by link only, so a reader who did not click through never saw a path and had to guess one — and /inbox_conversations guesses 404, because the resources are nested (/inbox/conversations, /inbox/messages, /inbox/participants). Each section now shows its path where the action is described. Also fixes the "Bookings endpoints" link under Fetching an Inbox Conversation, which pointed at the Applications reference page instead of Bookings.
🔑 An Idempotency-Key is now scoped to the request that created it. Presenting a key alongside a different method, path or body returns 409 Conflict with the idempotency_key_mismatch code instead of replaying the unrelated first response. Retries of the identical request keep replaying as before.
📚 Document the header, which has been supported all along but was never written down. The new Idempotency section explains how to retry a write safely: the first response is stored and replayed to any later attempt at the same request, so a request that was applied but whose response never reached you is not applied twice. It also covers what is not stored (4xx and 5xx, so those retries genuinely re-run) and the one sharp edge — concurrent requests sharing a key are both processed. API best practices now recommends retrying 5xx with a backoff and a stable key instead of aborting the whole synchronization.
📚 State the two things the Inbox Messaging guide left implicit. A new Prerequisites section lists the inbox_read / inbox_writescopes and the fact that Inbox Conversations for a Channel only exist once that Channel is connected to the Account — with no connection there is nothing to read and nothing to reply to. Flow now says up front that API messaging is reply-only: threads are opened on the Channel's side, and a Conversation you create yourself is not linked to a Channel's messaging system, so its Messages never reach the guest.
📚 Correct how Claude's custom connectors (Cowork, claude.ai, Claude Desktop, mobile) connect to the MCP server: register the bare https://www.bookingsync.com/mcp URL with no query parameters, leave the OAuth client ID/secret empty, and paste the mcp_… token on the Connect to bookingsync-mcp sign-in page Smily opens — documented in Connecting clients with a screenshot of that page, and in Authentication → Connector sign-in. The pasted token is the credential — there is no separate connector password — so it keeps its own account scoping and expiry, and revoking it stops the connector too, which is why an expired token sends you back through the same page. The ?token=URL parameter is now marked legacy: still accepted, so existing setups keep working, but no longer the way to connect Claude. Troubleshooting covers the sign-in page appearing, a connector asking to reconnect, a rejected token, and Unregistered redirect_uri. (400).
✨ Document the read-only Payouts and Channel Payouts resources, both in beta. /payouts exposes SmilyPay payouts — what Smily paid out and the Smily fees deducted on top of each collected payment, per booking, with each line's contribution to the payout total. /channel_payouts covers the step before it: what an OTA such as Airbnb or Booking.com actually wired, decomposed across each booking's commission, city tax, cleaning fees and deductions, plus account-level movements. Pivot between the two with related_channel_payout_references. Both require the new payouts_readscope.
⚠️ Note the beta caveats while these endpoints stabilise: /payouts returns one payout per page (per_page is capped at 1, since rows are computed on the fly), payment_gateway_id is required on every /payouts request and omitting it returns 400, and both resources are read-only — payouts are produced internally as OTA wires arrive.
✨ Document the read-only Booking Cancelation Protection Summaries resource — the per-booking summary of cancelation-protection amounts (commissionable amount, eligible protection amount, rent revenue, policy, and churned_at) used for accounting reconciliation. Listing and fetching require the new bookings_cancelation_protection_readOAuth scope, which grants read access to this data.
📚 Document the per-application connected-accounts cap on private applications. Private apps are limited to 5 connected accounts by default; new installations (both OAuth and private access code) are blocked once the cap is reached. Partners can contact partners@smily.com to formalize the partnership and lift the cap.
✨ Expose payment_charge_commission on the Bookings endpoint — the Payment Charge commission amount — the commission charged by an OTA for processing payments (e.g. Payments by Booking.com). Available on the bookings_write_owned, bookings_read, and bookings_write scopes.
📚 Document the accuracy caveat: when the payout has not yet been reconciled from Booking.com via Smily Pay, the value may be off by approximately one cent — the real amount is only known once the payout is reconciled.
📚 Document how the channel attribute on an Inbox Message controls relay to the originating platform (Airbnb, Booking.com, etc.) and how to derive the right value from the Conversation's default_channel. See the Inbox Messaging guide.
