Changelog
Changes to the RatesSpot API (/v1), newest first. Additions never break existing clients (API versions and changes); deprecations are listed here with what to use instead.
2026-11-22: Approvals for high-risk actions by apps
When an app (an OAuth token) asks for a cancellation that refunds something, a refund given back, a change to payment keys or bank details, a webhook, revoking an API key, uninstalling an app, or deleting a unit or cancellation terms, the API answers 202 with { "approval": { … } } instead of doing it, and a person approves or declines it in the dashboard. Check GET /v1/approval-requests/{id} or listen for approval.decided (a new event type). Businesses choose which areas need approval (GET/PUT /v1/business/approval-policy). API keys are unaffected. See Building an app.
2026-11-22: Two-factor sign-in
Staff sign-in can ask for a code from an authenticator app. login answers 401 two_factor_required with details.challenge; finish with POST /v1/auth/login/two-factor (code or recovery code, optionally trustDevice for a 30-day deviceToken to send with login). Your own settings: GET /v1/auth/two-factor, POST …/setup, …/confirm, …/recovery-codes, …/disable. Owners: PUT /v1/business/two-factor-requirement and POST /v1/staff/{userId}/two-factor/reset. A business that requires it answers 403 two_factor_setup_required to staff who haven't set it up. StaffUser gains twoFactorEnabled and merchants[].requireTwoFactor; StaffMember gains twoFactorEnabled. API keys and app tokens are unaffected.
2026-11-21: Staff notifications
The dashboard's bell (booking-model.md 9.1): GET /v1/staff-notifications and POST /v1/staff-notifications/read, for signed-in staff. Installed apps can post to it with POST /v1/staff-notifications (their own token, no scope, 50 a day per business). kind is an extensible list.
2026-11-21: Deprecation headers
Deprecated operations now answer with a Deprecation header and a Link (rel="deprecation") to their entry here. See API versions and changes.
2026-11-21: App directory
Developers list apps in the directory at ratesspot.com/apps and in the dashboard, after review: GET/PATCH /v1/developer/apps/{id}/listing, POST …/listing/images, POST …/listing/submission, DELETE …/listing/publication. Anyone can browse with GET /v1/marketplace/apps and GET /v1/marketplace/apps/{slug}, with no key. Once an app is listed, the consent screen refuses requests for more scopes than its listing says. The consent description gains client.listed and client.byRatesSpot.
2026-11-21: Charges during a stay
POST /v1/bookings/{id}/charges and POST /v1/bookings/{id}/charges/{chargeId}/void, on checked-in or completed bookings. Bookings gain charges, and charges add to total. booking.changed has data.change charge_added or charge_voided.
2026-11-20: Booking emails move to the Emails app
RatesSpot no longer sends booking emails itself; the Emails app does, installed like any app. Deprecated: GET/PUT /v1/notification-settings (getEmailSettings, setEmailSettings), POST /v1/notification-settings/test (sendTestEmail), GET /v1/notifications (listEmails) and POST /v1/notifications/{id}/retry (retryEmail). They keep working: enabled can only be false, and testing or retrying answers 409. Use the Emails app instead; GET /v1/business/setup gives its install link.
2026-11-20: Apps: lifecycle, places and webhooks
app.installed and app.uninstalled events. Apps declare places in the dashboard (a sidebar page, booking panels), opened with a signed context (POST /v1/apps/{clientId}/context, checked with verifyAppContext in the SDK). Apps can have one webhook for every business that installs it (webhook on POST/PATCH /v1/developer/apps).
2026-11-20: Approvals, amendments and refunds given back
Rates can require approval: requests are PENDING_APPROVAL until approved or declined (booking.approved, booking.declined). Bookings can be changed with POST /v1/bookings/{id}/amendment-preview and then POST /v1/bookings/{id}/amend. Refunds staff hand back are settled with POST /v1/payments/{id}/give-back. GET /v1/occupancy for a day's units in use, closed and free.
2026-11-20: Event types can grow
Lists that grow, starting with webhook event types, are marked x-extensible-enum, and clients must ignore values they don't know. Switching event types over was a one-time change made before launch. Adding an event type has not been a breaking change since.