Calendar and iCal feeds

Two related surfaces: a JSON calendar for building your own day-by-day view, and an iCal feed for exporting availability into an OTA. If you don’t want to build your own calendar UI, a pre-built, copy-paste version of the JSON calendar is also available — see Embed the calendar.

Only the JSON calendar works today

The JSON calendar is live. The iCal feed and iCal import are not available yet. The channel manager is switched off on the current deployment. Every iCal route answers 503 with the code channel_unavailable, and nothing syncs. The two iCal sections below show how it was built to work. Do not give a feed URL to an OTA yet.

JSON calendar

GET /v1/resources/{id}/calendar returns one entry per night in the window: availability status, a price hint, and any active restrictions — built on the same data as Availability. It is a per-night view for hotel stays. To show the bookable times of an hourly space, use GET /v1/resources/{id}/slots. See Hourly spaces and services.

curl

curl "https://api.<domain>/v1/resources/<RESOURCE_ID>/calendar?from=2026-08-01T00:00:00Z&to=2026-08-04T00:00:00Z" \
  -H "Authorization: Bearer sk_test_..."

TypeScript

const { data: calendar, error } = await client.GET("/v1/resources/{id}/calendar", {
  params: {
    path: { id: "<RESOURCE_ID>" },
    query: { from: "2026-08-01T00:00:00Z", to: "2026-08-04T00:00:00Z" },
  },
});
if (error) throw error;

{
  "resourceId": "<RESOURCE_ID>",
  "from": "2026-08-01T00:00:00.000Z",
  "to": "2026-08-04T00:00:00.000Z",
  "currency": "IDR",
  "days": [
    {
      "date": "2026-08-01",
      "status": "available",
      "reasons": [],
      "priceHintMinorUnits": "1500000",
      "restrictions": {
        "minStayNights": 2,
        "maxStayNights": null,
        "closedToArrival": false,
        "closedToDeparture": false,
        "stopSell": false
      }
    }
  ]
}

Both sk_ and pk_ keys can call this endpoint. priceHintMinorUnits is a hint only — always price the actual stay with POST /v1/quotes (see Quotes) before you hold it.

No PII on a publishable key

An sk_ key that holds bookings:read, or an operator session, gets one extra field per night: occupants, an array with each reservation’s id, a guest label, and its state. Every other caller — a pk_ key, or an sk_ key with only availability:read — never receives occupants at all: not an empty array, the key is absent from the JSON entirely. This is the same “no PII on a publishable key” rule as everywhere else in this API; it’s what makes it safe to build a public, embeddable calendar (see Embed the calendar) straight off this endpoint.

The window is limited to 92 nights per call (400 range_too_large beyond that). Every response is computed fresh: there is no ETag and no 304 on this endpoint, so request only the window you need.

iCal feed (export)

Not available yet

GET /v1/feeds/{token}.ics and the feed-token calls answer 503 channel_unavailable, whatever the token is. A 503 here does not mean the token is wrong.

GET /v1/feeds/{token}.ics is built to export confirmed direct bookings and any already-synced external OTA blocks as an iCal feed — busy/free VEVENTs only, no guest names or contact details.

Operators: get this URL from the dashboard

You don’t need to call the API to obtain a feed URL. On the Channels screen, under Your calendar feeds (outgoing), pick a room, name the feed and create it. The full URL is shown once — copy it then, because only a hash is stored. Revoking a feed is how you rotate a leaked URL.

curl https://api.<domain>/v1/feeds/<TOKEN>.ics

BEGIN:VCALENDAR
VERSION:2.0
BEGIN:VEVENT
UID:...
DTSTART:20260801
DTEND:20260804
SUMMARY:Booked
END:VEVENT
END:VCALENDAR

The token in the URL is the credential

There is no Authorization header on this call — that’s by design. It’s meant to be pasted once into an OTA’s “import a calendar” field and left there long-term, unlike an sk_/pk_ key. An unknown, malformed, or revoked token returns 404 feed_token_not_found.

The token itself is issued per resource with an sk_ key (channel:manage scope):

curl

curl -X POST https://api.<domain>/v1/resources/<RESOURCE_ID>/feed-tokens \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Airbnb export" }'

TypeScript

const { data: feedToken, error } = await client.POST("/v1/resources/{id}/feed-tokens", {
  params: { path: { id: "<RESOURCE_ID>" } },
  body: { name: "Airbnb export" },
});
if (error) throw error;

POST /v1/resources/{id}/feed-tokens returns the full URL exactly once — copy it immediately, it is never shown again. If you don’t hold an sk_ key yourself, ask your operator contact to issue one for you. Losing a feed URL means revoking it (DELETE /v1/resources/{id}/feed-tokens/{tokenId}) and issuing a new one — the old URL stops working immediately, and nothing else about your API keys is affected.

iCal import (bringing an OTA’s calendar in)

Not available yet

iCal import does not run today. GET/POST /v1/channel-connections answers 503 channel_unavailable.

The reverse direction — pulling an OTA’s own calendar in, so a booking made on that OTA blocks the date here too — is configured from the dashboard: Channels → Connect a channel → iCal calendar, then paste the URL the other site gives you. Once the connection is active we poll that URL on a short cycle and keep both calendars in sync; you don’t need to call anything for this to happen.

There is also a management API for it if you’d rather automate: GET/POST /v1/channel-connections and GET/POST /v1/channel-connections/{id}/listings.

Where iCal stops

iCal carries busy dates only. No prices, no restrictions, no guest details, no reservation records — and both sides poll on their own schedules, so the sync window is hours rather than seconds. That’s the trade for needing no partner agreement.

For rates, restrictions and real reservations you need a direct OTA integration. Booking.com and Agoda connections are not available yet either; see Connecting Booking.com and Agoda. Airbnb has no public API, so iCal will be the way to sync it once the channel manager is switched on.

Next steps

• Embed the calendar — a pre-built, copy-paste version of the JSON calendar above.
• Availability — the underlying reason vocabulary shared with this endpoint.