← Back to home Hotel integration
Embed SDK v1 · hotel preset · handoff

The spa, within the hotel booking.

The guest chooses their treatment without leaving your booking engine, and the spa is added to their stay's bill. The Siana widget does not charge: it returns the selection for you to create it with your public API. This guide is all your technical team needs — copy, paste, and replace your domain.

What it does and what it doesn't

This integration is not like the other four. The others connect the engine to your website; this one connects it to your booking engine. The widget enters read-only mode: it shows availability and price, allows selection, and upon completion, emits the selection to your page. There is no checkout, no payment gateway, nothing is written to Siana's backend.

The Siana widgetdisplays catalog and real-time availability, and returns the selection. It does not charge or create anything.
Your hotel enginereceives the selection, saves it along with the room booking, and defers payment to the bill.
Your backendcreates the spa booking by calling the public API when the hotel booking is confirmed.
The payload price is for reference. It serves to display the line in your summary. The source of truth is the public API, which re-prices and re-validates availability upon creation. Never charge against the handoff amount.

The end-to-end flow

Two phases. The first occurs entirely in the guest's browser; the second, between your backend and the public API, when you decide.

StepActorWhat happens
Selectionbrowser · SianaThe hotel opens the widget (drawer) and the guest chooses service and time. Siana creates nothing.
Handoffwidget → hostWhen pressing "Finish", the widget emits cart:handoff with the payload. The host associates it with their booking via session_id.
start / createhost → public APIForwards slots/items to POST .../{purchase_type}-purchases (+ buyer + hotel_reservation_id). The public API re-validates price and availability, and creates the started (held) booking.
confirmhost → public APIChanges started → confirmed and issues the locator. Payment is included in the hotel bill (deferred payment).

When is each call made? start when adding the spa to the hotel checkout (reserves the slot, held; optional if you don't need a hold). confirm when the hotel booking is paid or confirmed. Abandonment = no API call → nothing pending. The payload price is only for reference; send what the public API recalculates.

There is no slot blocking between the handoff and the start. The slot is validated upon creation, so if a lot of time passes, it may have been taken. The public API will return an error and your engine decides: retry, offer another time, or notify. The sooner you create, the less risk.

Set up the widget

Load the engine's embed.js and mark a button with data-siana-* attributes. What activates hotel mode is data-siana-preset="hotel"; without it, the widget behaves like a normal embedded one and does charge.

<script src="https://YOUR-ENGINE/embed.js"></script>

<!-- Side panel, a specific service -->
<button
  data-siana-open
  data-siana-view="widget"
  data-siana-service="SERVICE-UUID"
  data-siana-mode="drawer"
  data-siana-chrome="minimal"
  data-siana-preset="hotel"
  data-siana-purchase-mode="appointment"
  data-siana-session-id="YOUR-BOOKING-ID"
  data-siana-callback-url="https://api.yourhotel.com/spa/handoff">
  Add spa to my stay
</button>
<!-- Centered modal -->
<button data-siana-open data-siana-mode="modal" data-siana-view="widget"
  data-siana-service="UUID-DEL-SERVICIO" data-siana-preset="hotel" data-siana-purchase-mode="appointment">…</button>

<!-- Embedded in the page, full catalog -->
<div data-siana-inline data-siana-view="full" data-siana-preset="hotel" data-siana-purchase-mode="appointment"></div>

Mode: drawer or modal (with data-siana-open), or embedded (with data-siana-inline). View: widget for a single service, full for the entire catalog. chrome="minimal" hides the engine's navigation.

session_id is your booking identifier, and it returns intact in the payload: it's what allows you to associate the spa with the correct room. It also isolates the cart, so if the guest closes and reopens the widget, their selection is still there. callback_url is optional and explained in point 4.

Receive the handoff

Three ways, and you can combine them. A is recommended; C is the fallback if you don't have JavaScript listening on the page.

// A) With the SDK — recommended, on the page itself
SianaBooking.on('cart:handoff', function (payload) {
  // payload.purchase_type, payload.slots | payload.items, payload.session_id …
  addSpaToBooking(payload)
})

// The guest can remove an item from your summary:
SianaBooking.on('cart:remove', function (data) { removeItem(data.item_id) })

// B) Raw postMessage, without SDK — ALWAYS verify the origin
window.addEventListener('message', function (e) {
  if (e.origin !== 'https://YOUR-ENGINE') return
  if (e.data && e.data.type === 'siana:cart-handoff') { /* e.data */ }
})

// C) Server-side — data-siana-callback-url receives the SAME payload via POST
//    (navigator.sendBeacon, Content-Type: text/plain). Only https and only
//    if your origin is in the allowlist (see point 8).

The SDK re-emits the postMessage siana:cart-handoff as a cart:handoff event: it's the same data, just easier to listen for. Each item arrives with its item_id, so you can offer a "remove" in your summary and the widget will be notified via cart:remove.

Create the spa booking

The payload already comes in the exact format accepted by the public API, so there's no need to translate anything: you add the buyer (you provide the identity, not the widget) and the reference to the hotel booking.

// This runs ONLY on your server: the partner key must never reach
// the browser. When your hotel booking is confirmed:
await fetch(`https://YOUR-ENGINE/api/v1/public/.../${payload.purchase_type}-purchases`, {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey YOUR-PARTNER-KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    buyer: hotelGuest,
    hotel_reservation_id: payload.session_id,
    ...(payload.slots ? { slots: payload.slots } : { items: payload.items })
    // the price is NOT sent: the public API re-prices server-side
  })
})

The endpoint depends on purchase_type: appointment-purchases when there is a date and time, or voucher-purchases when it's a voucher without a date. The payload already tells you which one, and brings slots or items accordingly.

Remove an item

Re-open the engine with data-siana-item-id (delete mode): it confirms the cancellation by emitting cart:remove and closes. You remove that item from your booking by its id.

SianaBooking.open({ preset: 'hotel', sessionId: 'HOTEL-BOOKING-ID', itemId: ITEM_ID, mode: 'drawer' })

SianaBooking.on('cart:remove', function (data) {
  // data.session_id, data.item_id → remove it from your booking
})
The "remove" button lives in your summary, not in the widget. Mark it with the item_id that arrived in the handoff: it's the same id the engine returns to you in cart:remove upon confirming the removal.

Payload contract

Example of an appointment with date (purchase_type: "appointment"). In voucher mode, "voucher" arrives with items[] instead of slots[].

{
  "v": 1,
  "type": "siana:cart-handoff",
  "session_id": "hotel-resv-DEMO-001",
  "center_uuid": "…",
  "purchase_type": "appointment",
  "slots": [
    {
      "item_id": "9c1f8f2a-4b77-4a5e-9f0e-2d31a6b8c554",
      "service_uuid": "3ea9a103-b45f-5442-bec3-592d1ba690cb",
      "service_name": "Spa Circuit",
      "fulfillment_on": "2026-06-01 10:00:00",
      "duration": 60,
      "pax": 2,
      "price_per_person": { "amount": 3000, "currency": "EUR" },
      "employee_db_id": null,
      "resource_db_id": null,
      "rate_db_id": 12
    }
  ],
  "total_reference": { "amount": 6000, "currency": "EUR" }
}
v
Contract version (today 1). If it changes incompatibly someday, this number increases: use it to detect such changes.
type
Type of the postMessage message: siana:cart-handoff. The SDK re-emits it as a cart:handoff event.
session_id
The data-siana-session-id you passed, returned intact. It is your booking reference: use it to associate the spa with the room.
center_uuid
UUID of the spa center to which the selection belongs.
purchase_type
appointment (dated appointment → slots arrives) or voucher (undated voucher → items arrives). Determines the endpoint when creating.
total_reference
Total reference amount, for display. The public API re-prices upon creation; do not charge against this number.
slots / items
The lines to create, already in the format accepted by the public API. They are re-sent untranslated.
↳ item_id
unique id of that line within the cart. This is the one that arrives in cart:remove and the one you pass in data-siana-item-id to remove it.
↳ fulfillment_on / duration
(appointment) date and time YYYY-MM-DD HH:MM:SS and duration in minutes.
↳ price_per_person
unit reference price: amount in cents and currency.
↳ rate_db_id
id of the chosen rate (0 = base rate).
↳ item_type
(voucher) line type: service, service_package or gift_card.
The handoff does not carry personal or payment data. Neither name, nor email, nor card. You provide the guest's identity when creating the reservation. This is deliberate: it reduces what a misconfigured origin exposes you to.

Security and allowlist

The engine only emits the handoff to explicitly authorized origins. This is configured in the engine's deployment, not on your website:

NUXT_PUBLIC_EMBED_ALLOWED_ORIGINS=https://booking.tuhotel.com,https://www.tuhotel.com
This is the first thing to resolve in a new integration. In production, the behavior is deny by default: if your domain is not on that list, the handoff simply won't be emitted — neither via postMessage nor via callback_url — and the widget will appear to do nothing upon completion. It is not a failure in your code. Pass us your exact domains (with protocol, no trailing slash) before you start testing.
  • With the list configured: the postMessage is only published to those origins, and the callback_url is only accepted if it is https and its origin is on the list.
  • Without a list, in production: nothing is emitted and a warning appears in the log.
  • In local development: there is a permissive fallback to allow setting up the demo, but the callback_url via beacon always requires an allowlist.
  • Verify the origin anyway if you listen for raw postMessage, without the SDK. It's one line and protects you from any other iframe on the page.
The allowlist controls where the handoff goes, not who accesses your endpoint. The callback_url is a public URL of yours: anyone can POST to it. Authenticate each request (secret header, shared signature, or mTLS), check that v is a version you support and that center_uuid and purchase_type are what you expect, and link the session_id to a guest session you have already authorized before creating or modifying anything. The received JSON does not by itself prove who is sending it.
9 · Live demo

Try it right here.

This simulates a hotel's website. Above, the stay reservation; below, its spa section. Click "Check availability", choose a treatment and "Finalize": the widget will not ask you to pay — the selection is added to the reservation and the total is recalculated. That's what your page receives via cart:handoff.

Pop-up alerts are part of the demo, not the product. Every time a cart:handoff or a cart:remove arrives, you will see an alert() with the raw JSON, so you can check at a glance what the engine is delivering to you. In your real integration, that data is processed in code and the user sees nothing: the alert() is here only to make the data visible while testing.

Checklist

What is needed to go from demo to production. The first three points depend on us; the rest, on your technical team.

  • Your domains in the allowlist. Provide us with the exact origins from which the widget will open. Without this, the handoff is not emitted (point 8).
  • Your engine's origin. We give you the engine's domain for the <script src> and to verify the postMessage origin.
  • Partner key for the public API. Your backend needs it to create the spa booking (point 5).
  • Decide what to show: a specific service (view="widget" + data-siana-service) or the entire catalog (view="full").
  • Choose the mode: side panel, modal, or embedded. It is changed with an attribute, without touching the rest.
  • Pass your booking reference in data-siana-session-id and save it along with the selection.
  • Listen for cart:handoff and render the lines in your summary. Add cart:remove if you allow them to be removed.
  • Create the spa booking when you confirm the hotel booking, and manage the case of an already occupied slot (point 2).
Questions about any point? Write to us with your specific case: mode, view, and at what point in your flow you want to create the booking. This is what is needed to finalize the details.