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

```sh
npm install @ratesspot/sdk
```

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

## 1. Show what's for sale

```ts
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

```ts
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

```ts
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

```ts
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](https://www.ratesspot.com/docs/payments.md#where-customers-return-after-paying)). The provider sends the guest back to `callbackUrl?reference=…` (Stripe adds `provider=stripe`). Confirm it:

```ts
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](https://api.ratesspot.com/docs).
