- ✨ 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_read scope.
- 📚 Add the Understanding payouts guide — a walkthrough for going from "the amount I received is not what I expected" to the line that explains it: which of the two endpoints owns each hop, a worked example, an ordered checklist of the five things that shrink a payout (Smily fee, carry-over from an earlier booking, channel deduction, account-level movement, the channel's own arithmetic), carry-over lines and their paired halves, direct bookings and split payment — including OTA bookings that also carry a SmilyPay upsell — and, explicitly, what you can verify independently and what you cannot.
- ⚠️ 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_read OAuth scope, which grants read access to this data.
- ✨ Introduce the experimental MCP server — exposing API v3 over the Model Context Protocol so AI clients can query Smily resources directly. Covers authentication (header and URL tokens, single- and multi-account tokens with per-request account selection), the four tools, querying (filters, sparse fieldsets, pagination), the resource catalog, connecting clients (Claude Code, Claude Cowork, Codex), testing with MCP Inspector, and the JSON-RPC protocol.
- ✨ 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.
- ✨ Expose
start_at_global and end_at_global on the Booking resource. These are the booking's check-in and check-out as true UTC instants (rental's timezone applied), suitable for absolute time-window comparisons. The existing start_at and end_at remain wall-clock values in the rental's local timezone.
- ✨ Return
Retry-After header on 429 rate limit responses, and clarify rate limiting scope (per OAuth application, no per-endpoint sub-limits).
- ✨ Document the difference between
map and map_with_price_variation on the Mid Term Rate Map endpoint, and how the per-day price modifier is resolved from Applications Periods Rentals and the Application's default_price_increase.
- ✨ Document the application lock behavior when setting
nightly_rates_managed_externally to true on a Rental: rates management is locked to the calling application, and a different application attempting to update the Nightly Rate Map will receive an explicit error.
- ✨ Add
classified_kind attribute to Bookings Fees and Bookings Taxes endpoints.
