# Changelog

Changes to the RatesSpot API (/v1), newest first. Additions never break existing clients ([API versions and changes](https://www.ratesspot.com/docs/api-versioning.md)); deprecations are listed here with what to use instead.

## 2026-11-22: Apps can ask for a booking site's key

`POST /v1/api-keys` now accepts apps' tokens for `website` and `browser` keys (never `full`), behind an owner's approval: the answer is `202`, and once approved the key comes from `GET /v1/approval-requests/{id}` as `secret`, the first time the app asks, and never again. The key is named after the app.

## 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](https://www.ratesspot.com/docs/oauth-apps.md).

## 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](https://www.ratesspot.com/docs/api-versioning.md).

## 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.
