RRatesSpot
← Docs

Building a plugin

RatesSpot does rates, availability and bookings, the same way for every business. Everything else, from housekeeping and guest registration to invoices, reports, loyalty and channel managers, is a plugin: your own service that works through the public API and webhooks. Our own plugins follow the same rules.

The rules

  1. Only the public API, webhooks and metadata. There is no database access and no private hook, so whatever you build works on any RatesSpot business, hosted or self-hosted.
  2. Keep your own data. Store your records (a guest's ID details, an invoice, a cleaning log) in your own database. On the RatesSpot object, keep only a reference in metadata.
  3. React to events instead of polling. Subscribe to webhooks, and use GET /v1/events to catch up after downtime.
  4. Ask for the fewest scopes. A report needs payments:read, not bookings:list.
  5. Removing your plugin never breaks bookings. RatesSpot never waits on a plugin.

Building blocks

You need Use
To hear when things happen Your app's own webhook (webhook when you register it): one address for every business that installs you, filtered by each install's scopes. booking.confirmed, booking.checked_in, booking.completed, payment.succeeded, refund.created, catalog.changed, customer.updated…
To set up and clean up app.installed when a business installs you; app.uninstalled (with reason) when its last connection to you ends, as your last delivery: stop, and delete that business's data within 30 days
To forget a person customer.erased: delete everything you hold about that customer
To link your record to ours metadata on bookings, customers, listings, units, rates, courses and the business: 50 string keys, set with PATCH, and an empty string removes a key
To find "your" objects again GET /v1/bookings?metadata=key:value, GET /v1/customers?metadata=key:value
Guests GET /v1/customers (search, with booking counts), GET /v1/customers/{id}, GET /v1/bookings?customerId= for their history
Units (rooms, desks…) GET /v1/catalog: every listing's units with their metadata; PATCH /v1/catalog/units/{id} to set yours
Money GET /v1/payments?from=&to=: every charge and refund with its method (card provider, cash, POS, transfer)
Credentials An API key the business creates for you, or an OAuth app businesses install and can uninstall

Prefix your metadata keys with your plugin's name (acme_cleaning), so two plugins never collide. The core never reads metadata, so availability and prices are unaffected by anything you store there.

Pages in the dashboard

Staff shouldn't have to leave the dashboard to use your plugin. Declare places when you register your app (or later, PATCH /v1/developer/apps/{id}):

"places": [
  { "kind": "page", "label": "Reports", "url": "https://reports.example.com/app", "roles": ["OWNER", "MANAGER"] },
  { "kind": "booking_panel", "label": "Notes", "url": "https://reports.example.com/panel" }
]
  • At most one page (an item in the dashboard's Apps group; put your other screens in tabs inside it) and two booking panels. roles limits who sees each; omit it for everyone. Don't name a business in a label: the same app serves many.
  • The dashboard shows your URL in a sandboxed frame with ?ratesspot_context=…: which business, which staff member and role, which place, and the booking for a panel. Check it before showing anything:
import { verifyAppContext } from "@ratesspot/sdk";

const context = await verifyAppContext(url.searchParams.get("ratesspot_context"), { clientId: process.env.RATESSPOT_CLIENT_ID!, seen: (jti) => usedOnce(jti) });
if (!context) return new Response("Open this from the RatesSpot dashboard.", { status: 401 });
// Then call the API with your own install token for context.merchantId.
  • A context is signed by RatesSpot for your app only and lasts 5 minutes; accept each jti once. Set your own session cookie after the first check, and send Referrer-Policy: no-referrer so the token doesn't leak in links.
  • Fit the frame. The frame starts 480 pixels tall. Tell the dashboard your page's height, and again whenever it changes and whenever the dashboard asks (it sends { type: "ratesspot:measure" } once it's listening, because a report sent before then is lost):
const report = () => parent.postMessage({ type: "ratesspot:resize", height: document.documentElement.scrollHeight }, "https://app.ratesspot.com");
new ResizeObserver(report).observe(document.body);
addEventListener("message", (e) => { if (e.origin === "https://app.ratesspot.com" && e.data?.type === "ratesspot:measure") report(); });

Telling staff something

An installed app can put a notification under the dashboard's bell: POST /v1/staff-notifications with your app token and { "title": "Studio 2 is ready", "body": "…", "bookingId": "…", "roles": ["FRONT_DESK"] }. It links to the booking if you give one, otherwise to your app's page. Keep it to what needs a person: there's a limit of 50 a day per business. Our Housekeeping app does this when a unit someone arrives in today becomes ready.

Listing your app

Once it works, list it in the app directory so any business can find it: open Apps → Apps you've built → Directory listing in the dashboard (or PATCH /v1/developer/apps/{id}/listing), add an icon, screenshots, a description, the permissions it asks for and an install address (yours, which starts your OAuth flow), then submit it. RatesSpot reviews every listing, and every change to one, before it's shown at ratesspot.com/apps and in the dashboard. Once listed, the consent screen refuses requests for more permissions than the listing says, so ask for exactly what you need. Listing is free; if you charge, link to your own pricing page (RatesSpot doesn't bill for apps).

Three patterns

Guest registration (ID documents, nationality, emergency contact). On booking.confirmed, send the guest your own form. Store what they submit in your own database, then PATCH /v1/customers/{id} with { "metadata": { "acme_registration": "reg_123" } }. When staff check the guest in (booking.checked_in), check that the registration exists. Personal details stay with you. If the business erases a customer you get customer.erased (just the customerId): you must delete your copy of their details then.

Housekeeping. On booking.completed (checkout), mark the booking's units dirty: PATCH /v1/catalog/units/{unitId} with { "metadata": { "acme_cleaning": "dirty" } }. Your cleaners' app sets the unit back to clean. A unit out of service for repairs is a closure (POST /v1/closures), which RatesSpot itself respects.

Reports and accounting. Backfill with GET /v1/payments and GET /v1/bookings?from=&to=, then keep your ledger current from payment.succeeded, refund.created and refund.sent. Occupancy comes from GET /v1/calendar. Exports (PDF, spreadsheets) are yours to render. With only payments:read you see amounts and booking references, never guests' details, but you don't get payment events (they carry the booking, which needs bookings:read): read GET /v1/payments when you need it.

Rules for your code

  • Verify every webhook signature (verifyWebhook in @ratesspot/sdk), and skip an event id you've already handled.
  • Amounts are integers in minor units next to a currency. Dates without a time are local to the business.
  • If something can't be done with the API, that's a gap in RatesSpot, not something to work around. Open an issue describing what you're building.