Requirements and holds

Some bookings are not finished when the time is picked. A licence has to be approved, a form has to come back, a payment has to land on your own site. A requirement is a thing a booking waits on, and while it waits the time is held: taken out of your availability, but not yet a meeting.

The three kinds

You add requirements to an event type. There are three kinds:

Host approval — you decide. This is the event type's existing "Requires confirmation" setting; you do not add it by hand.
External — something outside Calemander has to clear it. Your own system clears it through the API, or you clear it yourself. You can optionally let the attendee type a reference number for it.
Acknowledgement — the attendee has to tick something. You write the sentence they tick.

Each one has a key, a short stable name like licence_approved, which is what integrations use. An event type can carry up to twenty. What the attendee sees — the label, the instructions, the sentence they tick — is copied onto the booking at the moment they book, so editing the event type later never rewrites what somebody already agreed to.

When a requirement blocks

Each requirement chooses one of two moments:

After the time is booked. The booking is made and held until the requirement clears. This is the default.
Before any time can be taken. The public booking page refuses to hold the time at all until the requirement is already satisfied. This is what a bring-your-own checkout uses.

An acknowledgement cannot use the second option; there is nothing to satisfy in advance.

What a held booking does and does not do

Held bookings are deliberately quiet. While a booking is held:

The time is taken. Nobody else can book it, and it is out of your public availability.
There is no meeting on the calendar, but there is a marker. A held booking goes on your calendar as a placeholder titled HELD · and the event and invitee name, marked free so it blocks nothing and nobody is invited to it. When the booking confirms, that same event becomes the real one in place: the prefix goes, it turns busy, and your invitee is invited. See Connecting calendars.
No reminders are scheduled, and none can be sent. The reminder queue only ever looks at confirmed bookings.
No confirmation email goes out, because nothing is confirmed.

The attendee is told twice, and the first time is before they book. On an event type that holds its bookings, the booking page carries a notice above the button and in the sidebar, with the same sentence on the embed: what booking does, what confirms it, and when it is released. The submit button says Hold this time rather than Book, unless you have written your own button text or the click leads to a payment step, where the button keeps naming the amount.

The sentence is built from your own requirement labels and the release clock below, so it cannot drift from either. There is nothing to write and nothing to keep in step: change a requirement or a clock and the notice changes with it.

Then, at booking: unless you switch it off on the event type, they get a "Your time is held" email — and a text, if they booked by phone — that says in as many words that it is not confirmed yet, and repeats the same sentence with the real date on it. The confirmation screen says it too.

One attendee email address can hold at most two bookings in your workspace at a time. The third is refused with: You already have two bookings waiting on requirements. Complete or cancel one before holding another time.

The attendee's checklist

When there is something the attendee can actually do, their held email carries a link to a checklist page for that booking. The link is signed and needs no login, and it stays valid until seven days after the booking's start time, so a released hold gets explained rather than 404ing.

On that page they can tick an acknowledgement, and — where you allowed it — type a reference number for an external requirement. Typing a reference does not clear anything. It moves the requirement to submitted and the booking stays held until somebody verifies it. The page says so: Sending this does not confirm your booking. Someone checks it first.

There is no file upload. Evidence is a short typed reference, up to 200 characters, and nothing is stored in object storage.

If a booking question already collects the reference, bind it to the requirement and the attendee is not asked twice. Pick the question in the Requirements section, on an external requirement that lets the attendee give you a reference. Their answer becomes the requirement's reference the moment they book: the requirement is marked submitted with what they typed, and the checklist shows it as submitted instead of asking again. It still confirms nothing — you or your integration verify it as you would any other submission. The question has to be one on the booking form itself, of a kind the attendee types into. If you later delete that question, move it to after booking, or change it to a multiple-choice kind, Calemander tells you which requirement reads it and asks you to confirm before unhooking it; after that, the attendee is asked on the checklist as before.

If you send a submission back, the attendee gets a fresh link and the old one stops working immediately. They are told which reference did not match and asked to send it again; the note you wrote is for you and is never shown to them.

How long a hold lasts

A hold has a clock. Two settings drive it, and whichever comes first wins:

a number of hours counted from when the booking was made, and
a cut-off, counted backwards from the booking's start time.

If neither is set, the hold runs for 72 hours. There are two exceptions to that default. A booking that has already been paid for, or that is holding a card, is held indefinitely — money in hand buys patience. And a booking whose only outstanding item is host approval keeps the older behaviour of waiting for you, with no clock at all.

A computed release time that is already in the past is pushed to an hour from now, so a hold is never released the instant it is created. Moving a booking re-computes a cut-off clock against the new start time; a clock counted from creation does not move.

Both numbers, and the nudge below, are set per event type in the Requirements panel, and over the API as requirementsHoldHours, requirementsCutoffHours and requirementsNudgeHours. Leave a field empty to turn that clock off.

The nudge

One reminder goes out before a hold expires: by default 24 hours ahead, and never on a hold so short that the message would arrive within two hours of it being created. It is sent once per booking, by email, and by text as well for a phone-first attendee.

Because of that two-hour rule, a nudge lead bigger than the hold itself would never be sent at all. So saving one is refused, naming both numbers: A 24-hour nudge needs a hold of at least 26 hours; set the nudge lower or to none. A cut-off is warned about rather than refused: how much room a booking has depends on how far ahead it was made, so bookings that come in early are still nudged and only the last-minute ones are not.

What it says depends on who is holding things up. If the attendee still owes something, it lists what and says when the time is released. If they have sent everything and you are the one checking, it tells them there is nothing for them to do, and that the time is still released on that date if nobody confirms it. Chasing somebody about a thing they have already done is worse than saying nothing.

When a hold is released

If the clock runs out with something still open, the booking is cancelled and the time goes back into your availability. The cancellation reason names what was still outstanding.

Releasing a hold also:

cancels any queued email for that booking;
gives back what the booking was holding — a package credit, a membership allowance, a discount use;
emails the attendee and you, and texts the attendee if they booked by phone;
fires the booking.canceled and booking.released webhooks.

A release never refunds anything. If money was taken, the attendee's email says so and points them at your contact address; the decision is yours to make.

Those two facts — the time is gone, and nothing was refunded — are the product's, and you cannot edit them. You can add a sentence after them: your own line in the release email, up to 200 characters, in the Requirements panel. It goes into the release email and the late-clear one, and never into your own copy of either.

If your own system announces the release instead, you can turn Calemander's attendee messages off for that event type. It gates the attendee's release email, its text and the late-clear email; your copy still sends, because it is the one that says no refund was issued. Your copy follows your own Requirement submitted or hold ended choice under Your notifications, which is on unless you switch it off. Turning it off needs an active webhook subscription for booking.released in your workspace — you have to be able to hear the release you are announcing — and if that subscription is later removed, the switch turns itself back on. And a release is final: a requirement that clears afterwards is recorded on the cancelled booking and answered with an email explaining that the time has gone, not by bringing the booking back.

Picking a new time afterwards

Every message about a release carries the same link to pick a new time. It works once, and by default for 14 days — you can set that window per event type, between one day and 90 days, or turn it off entirely.

The re-time page changes the time and nothing else. Their answers, add-ons and payment carry over, and the form deliberately has no name, email, question, duration or payment fields. Requirements they already cleared carry over too, keeping the moment they actually cleared. If the new booking itself needs holding, the button says Hold this time rather than Book this time.

A used, expired or unrecognised link gets a page explaining which of those it is, not an error. A booking covered by tuition or a package credit gets no re-time link, because the credit already carries its own way back. You can also mint a fresh link by hand from the booking's detail pane and send it yourself; nothing is emailed when you do.

Clearing something before there is a booking

Sometimes the outside world answers first. A county approves a licence before the couple has picked a time. You can post that clearance to Calemander in advance, against an email address or a reference, and the next matching booking is created with that requirement already cleared — nobody has to make a second call.

A pre-clearance is good for 180 days by default and is used once, both of which are per-requirement settings. It only applies to external requirements. An expired one is ignored rather than deleted.

Payment collected on your own site

One external requirement per event type can be marked as the one your own checkout reserves against. Your checkout mints a claim, the customer picks a time inside your flow, the booking is held with a deadline you set, and you report the payment when it settles. That report is the only way to satisfy that requirement — the ordinary clear endpoint refuses it and tells you to record the payment instead.

Calemander never sees the money, so it never refunds it. If your report arrives after the deadline, the payment is recorded, the booking is not resurrected, and the seat has already gone back. The full contract, including the claim endpoints and the idempotency rules, is in the API reference. Pricing an event type inside Calemander is covered in Taking payment.

What you can do

Requirements are authored in the Requirements section of the event type editor. Per-booking state lives in the booking's detail pane on your schedule, where each requirement shows its state and offers up to four actions:

Verify — accept a submitted reference, which clears it.
Send back — reject it with a reason. The reason is required.
Clear — mark it done yourself, without a submission.
Waive — drop the requirement for this booking. A reason is required.

Both reasons are kept on the booking for you and never shown to the attendee. A host approval is handled by the pane's ordinary Approve and Decline buttons.

A booking confirms itself the moment its last requirement clears or is waived, whichever action does it. There is no separate confirm step, and no way to extend or end a hold early: your levers are clearing, waiving, sending back, and cancelling the booking.

Through the API

Two scopes cover this, and neither is included in the older blanket read, write or admin scopes — an existing key cannot reach requirements until you grant them.

requirements:read — read what a booking is still waiting on, and the requirements set on an event type.
requirements:write — clear, waive, verify or send back a booking's requirements, post a pre-clearance, record an external payment, and set which requirements an event type asks for.

Writes accept an Idempotency-Key header, and a replay returns the first answer rather than acting twice. One thing you cannot send is how a clear should be classified: the server derives that from your credential, so a caller cannot dress a guess up as a county's reference.

Three webhook events come out of this. booking.held fires whenever a booking takes a time it cannot be confirmed on — every path, including the public booking page, a one-off link and a booking created through POST /api/v1/bookings, which fires booking.created as well and fired neither before — and carries releaseAt, the requirement list, and a link to the attendee's checklist when there is one. requirement.cleared fires whenever one clears. booking.released fires when a hold expires, after a booking.canceled for the same booking.

booking.created still fires at booking with its status, and for a held booking it carries releaseAt and a {total, outstanding, releaseAt} summary, so one event is enough to show a customer "held until". Every endpoint is listed in the API reference, and the payloads and the consumer state machine are in the webhooks guide.

Which plan you need

None in particular. Requirements, holds, pre-clearance, re-time links and bring-your-own checkout work on every plan, including the free one.

Taking payment — prices, deposits, fees and refunds.
Managing bookings — approving, cancelling and rescheduling.
API reference — endpoints, scopes and webhooks.

Approving from an email

When a new booking needs host confirmation, its host notification includes Approve booking and Reject booking links (the host's Needs your approval email, on by default under Your notifications). An admin's team copy of the same booking carries no links. Opening a link shows a confirmation page; submitting it applies the decision without signing in. The links work only for that booking and action, can be used once, and expire when the meeting starts. A used or expired link says so. Other outstanding requirements still need to be satisfied before an approved booking confirms.

Last checked 2026-10-11.