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 calendar event. Nothing is written to Google, Outlook or CalDAV, and no placeholder of any kind is created. The event is written when the booking confirms.
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. 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.

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

These two numbers are not editable in the dashboard today. They are set per event type, and setting them currently means going through the database.

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.

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. 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 when a paid booking lands still held, requirement.cleared whenever one clears, and booking.released when a hold expires. Every endpoint is listed in the API reference.

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.

Last checked 2026-09-10.