RRatesSpot
← Docs

Build a booking page

Everything a guest-facing booking page needs works with a publishable key (rs_live_pk_…), which is safe in browser code: browse, check availability, quote, hold, and start a card checkout. Keep secret keys (rs_live_sk_…) on a server.

npm install @ratesspot/sdk
import { createRatesSpot } from "@ratesspot/sdk";
const rs = createRatesSpot({ apiKey: "rs_live_pk_…" });

1. Show what's for sale

const { data: listings } = await rs.GET("/v1/resources"); // rooms, desks, offices… with rates and photos
const { data: courses } = await rs.GET("/v1/sessions");   // courses and events with seats left
const { data: methods } = await rs.GET("/v1/payment-methods"); // card (and which provider), bank transfer

Photos are images[].url, served by RatesSpot and safe to cache forever.

2. Check availability and price

await rs.GET("/v1/availability", { params: { query: { resourceId, from: "2026-12-01", to: "2026-12-31" } } });

const { data: quote, error } = await rs.POST("/v1/quotes", {
  body: { resourceId, range: { kind: "nights", checkIn: "2026-12-10", checkOut: "2026-12-12" }, adults: 2 },
});

range matches how the listing is sold: nights, hours (start may be local time, 2026-12-08T10:00), block (e.g. Morning), days, months, years, or session for a course. The quote has every line, taxes, the cancellation terms with their deadlines, and the ways to pay (paymentOptions: in full, deposit, on arrival, instalments). It reserves nothing.

3. Hold it

const { data: booking } = await rs.POST("/v1/holds", {
  params: { header: { "idempotency-key": crypto.randomUUID() } }, // the SDK adds one if you don't
  body: { resourceId, range, adults: 2, paymentOption: "FULL", paymentMethod: "card", customer: { name, email } },
});

A hold keeps the units for the business's hold time (15 minutes by default) while the guest pays. Retrying with the same idempotency key returns the same hold, never a second one. paymentMethod: "bank_transfer" holds for the transfer window instead and returns bank details through /v1/payment-methods; a rate with ON_ARRIVAL confirms straight away.

4. Take payment

const { data: checkout } = await rs.POST("/v1/bookings/{id}/checkout", {
  params: { path: { id: booking.id } },
  body: { provider: methods.cardProvider, callbackUrl: "https://your-site.com/booking/complete" },
});
// send the guest to checkout.authorizationUrl

callbackUrl must be on one of the business's return websites (see payments). The provider sends the guest back to callbackUrl?reference=… (Stripe adds provider=stripe). Confirm it:

const { data: status } = await rs.POST("/v1/checkouts/verify", { body: { provider, reference } });
// status.bookingStatus === "CONFIRMED"

The provider's webhook confirms the booking too, whichever comes first, so a guest who closes the page is still booked.

Errors

Every error is { "error": { "code", "message", "details" } }. message is written for people; show it. Codes you'll meet: insufficient_inventory (taken: details include nearestAvailable), outside_schedule, lead_time, invalid_request (details list each problem), provider_not_configured.

See the full reference at api.ratesspot.com/docs.