Bookings & Account Claiming

When User Accounts is enabled, logged-in customers can see their own bookings and orders on your website, and someone who booked with you before creating an account can turn that email into a full login later. This page is for your developer — it explains what customers experience and gives them the code to wire it up.

Booking and order history

Once a customer is logged in, your website can show them a list of their own bookings and orders. This works whether or not you use Bookings — if you don't take bookings, getBookings() just returns an empty list.

HelmCustomers.getBookings().then(function (data) {
  // { items: [{ id, reference, spaceLabel, preferredDate, status, createdAt }, ...], nextCursor }
});

HelmCustomers.getOrders().then(function (data) {
  // { items: [{ id, reference, amount, currency, items, status, placedAt }, ...], nextCursor }
});

Both come back 20 at a time. To load more, pass the previous response's nextCursor back in:

HelmCustomers.getBookings({ cursor: data.nextCursor }).then(function (more) { /* ... */ });

These only work once the customer is signed in — call them after login()/register() resolves, or after the SDK's ready event fires with a signed-in customer. Every booking also carries a short reference the customer can quote — the same one that's included in their confirmation email.

Linking a booking to a logged-in customer

By default a booking is matched to a customer by the email address they typed into the booking form. If a customer is already logged in when they book, your site can forward their access token on the booking submission instead, so it attaches straight to their account rather than being matched by email:

fetch('https://api.usehelm.host/api/public/YOUR_PROJECT_ID/booking', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ' + HelmCustomers.getAccessToken(),
  },
  body: JSON.stringify({ spaceId: 'studio-a', name, email, preferredDate }),
})

If the customer isn't logged in, or the token has expired, the booking still goes through as normal — it just falls back to matching by email, the same as it does today.

Claiming a booking made before an account existed

Booking with just an email — no account — still creates a record your customer can claim later. Add a simple "claim your account" step to your website:

// 1. Customer enters the email they booked with
HelmCustomers.claim(email).then(function () {
  // Always resolves the same way, whether or not that email has anything to claim —
  // show a generic "check your inbox" message either way.
});

// 2. Customer opens the emailed link and chooses a password
HelmCustomers.completeClaim(token, password).then(function (data) {
  // On success this logs the customer straight in — data.customer is populated
  // and a 'login' event fires, same as after login()/register(). Passwords need
  // to be at least 8 characters.
});

The emailed link points at your account area with the claim token in the URL (?token=...) — by default /account/claim on your site. If your account area lives somewhere else, let us know and we'll point the link there instead. That page just needs to read the token query parameter, ask for a new password, and call completeClaim. The link lasts 60 minutes.

Because the one-time token travels in the URL, serve your claim page with a Referrer-Policy: no-referrer header (or a <meta name="referrer" content="no-referrer"> tag) so the token is never leaked to third parties in the Referer header.

Once claimed, the customer's earlier bookings and orders — already linked to that email — show up in getBookings()/getOrders() immediately.